Developing Custom VersionOne Apps 101 Series Guide

After the last article, How To Use jQuery to GET a User Story in JSON Format from the VersionOne REST Data API and Render it as HTML, we’ve now explored all the major client-server interactions that take place over HTTP GET and HTTP POST. Now, let’s build the “simplest thing that could possibly work”, as they say in agile shops, to edit the User Story with HTML forms.

In this article, you will

  • Use the JSFiddle online editor
  • Create a simple HTML form that lets you edit a VersionOne User Story asset
  • Build a simple, but fully features, DTO (Data Transfer Object) binding function to populate the form from a JSON DTO fetched via HTTP GET from the VersionOne REST Data API
  • Build a simple, still fully featured, JSON DTO creator function that plucks values from the HTML form and packages them up to send back the API via HTTP POST

What you’ll need

  • Google Chrome. While it should work, I have not tested this in other browsers, so if you run into any snags, please let me know in the comments

Fire up a new JSFiddle

  • Open a brand new window or tab in Chrome and navigate to
  • From the left side, under Choose Framework. It should have onLoad preselected (leave it this way)
  • Select the most recent version of jQuery
  • Type the following code into the HTML panel:

[gist id=4685001 file=gistfile1.html]

  • Add this to the CSS panel:

[gist id=4685001 file=gistfile2.css]

  • And, to wrap it up, add this to the JavaScript panel:

[gist id=4685001 file=gistfile3.js]

Try live JSFiddle

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:

  • The URL provides the address of some resource.
  • 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,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”.

We’re taking a strong look at the open source ServiceStack project. What do  you think?

Next up

Let’s slow down and examine jQuery’s secrets in more depth in Understand jQuery’s Magic in the Barebones User Story Editor.

Stay agile, not fragile.

Join the Discussion

    There are currently no comments.

    − 1 = 4