Whoah, that was a lot of code! Slow down and explain some of it?
I agree with you, but this was a lot of code for me and for you to type. So, let’s dig into the code in the next post.
For now, though, let’s start to think more abstractly about what is happening here, and tie it back to what we learned earlier about REST. Remember that REST stands for REpresentational State Transfer.
In this code, we can think about representations this way:
When we navigate to that URL, or use $.ajax() to GET it for us, the server sends back a representation of that resource. The representation of a resource can differ depending upon parameters, whether they be HTTP headers, such as the Accept types, or query string parameters that the server understands. In the case of the VersionOne REST Data API, we get a different representation if we navigate to http://eval.versionone.net/platformtest/rest-1.v1/Data/Story/1154?sel=Name,Description,Estimate. Precisely, we get a representation that contains only three attributes of the remote resource.
When we’re modifying data inside the HTML form, we aren’t really dealing with a representation at this point. It’s just data.
But, when we click the save button, and call upon the createDtoFromForm function, we are building a Data Transfer Object (DTO), that will serve as a representation when we POST it back to the API.
At that point, the server interprets the representation and behaves accordingly.
VersionOne’s API needs some improvements here
To be fair, the VersionOne REST Data API needs some updating. Why? Well, the REST community has some pretty good understanding now of a somewhat lesser known, but increasingly important HTTP method called PATCH. Here’s what the RFC for PATCH says:
The PATCH method requests that a set of changes described in the request entity be applied to the resource identified by the Request-URI. The set of changes is represented in a format called a “patch document” identified by a media type. If the Request-URI does not point to an existing resource, the server MAY create a new resource, depending on the patch document type (whether it can logically modify a null resource) and permissions, etc.
The difference between the PUT and PATCH requests is reflected in the way the server processes the enclosed entity to modify the resource identified by the Request-URI. In a PUT request, the enclosed entity is considered to be a modified version of the resource stored on the origin server, and the client is requesting that the stored version be replaced. With PATCH, however, the enclosed entity contains a set of instructions describing how a resource currently residing on the origin server should be modified to produce a new version. The PATCH method affects the resource identified by the Request-URI, and it also MAY have side effects on other resources; i.e., new resources may be created, or existing ones modified, by the application of a PATCH.
If you are wondering why we have not talked about PUT before, then you caught me. That’s another area where the API needs improvements. Right now, everything gets “tunneled through POST”.