Understand How and Why REST APIs Work // Demonstrated with the Digital.ai Agility, formerly VersionOne, Data API

Developing Custom VersionOne Apps 101 Series Guide If you've come from the group of aside articles, then you've read one or all of these:

• Hello HTTP: How to GET What You Want and POST What Ya Got on the Web
• How to Spy on Your Browser's HTTP Requests and Responses!
• The Evolution of the Web is Being YouTubivised, and it's Linked
• PUT yourself in a State of REST // How to GET the Web's Architecture

If you've done that, then you've learned why the web was created in the first place, how it works, and that it is powered by the HTTP protocol and the RESTful interaction style that HTTP provides. You've also read about some of the amazing practical implications of that style // like the mass collaboration enabled by the OpenStreetMap REST API after the Haiti earthquake. If you didn't read those, and you don't want to, that's fine too.

In this article, you will

• See a REST API in action // the VersionOne REST Data API
• Learn how REST is different from other kinds of architectural styles, such as Remote Procedure Calls (RPC)
• Reinforce your understanding of why REST's uniform interface enables collaboration across disparate organizations and entities

What a REST/based web API looks like

In a REST/based web API, data and services that act upon data are exposed as, well, simply put: resources with URLs. Those resources can be fetched with HTTP GET, created with HTTP POST, replaced with HTTP PUT, and deleted with HTTP DELETE. Pretty simple, isn't it? Taking VersionOne's REST Data API as an example, here's the URL for a story resource: Note: use admin / admin when prompted for credentials http://eval.versionone.net/platformtest/rest/1.v1/Data/Story/1154 As we've seen before, clicking that makes your browser issue an HTTP GET operation to fetch the representation of the resource. By default, the API will return an XML/formatted representation. But, if we go to this URL we get a JSON/formatted representation: http://eval.versionone.net/platformtest/rest/1.v1/Data/Story/1154?acceptFormat=haljson And, if we go here we get a slimmed down representation of the resource, conforming to our request's parameters: http://eval.versionone.net/platformtest/rest/1.v1/Data/Story/1154?sel=Name,Description,Estimate&acceptFormat=haljson The JSON representation that returns looks like: [gist id=4684567 file=gistfile1.json] Now, if we want to modify that resource, we could use HTTP PUT (or, HTTP POST when it is used this way) with the following JSON content as the payload of an HTTP request: [gist id=4684567 file=gistfile2.json]

How REST differs from RPC, and why it matters

If you've read the Wikipedia article for REST, you may have seen the section Vocabulary re/use vs. its arbitrary extension: HTTP and SOAP. That section describes the conceptual difference between modeling a service with REST and modeling a service with SOAP, which uses a Remote Procedure Call (RPC) architecture style to issue requests over the internet. Let's just look at how the VersionOne REST Data API might look if it were done using a SOAP/based, RPC approach.

Every VersionOne asset type would have its own set of verbs and would need a customized proxy client

Instead of being able to issue an HTTP GET with our web browser or other HTTP client against the URL http://eval.versionone.net/platformtest/rest/1.v1/Data/Story/1154?acceptFormat=haljson, we might have to do something like this: [gist id=4684567 file=gistfile3.js] And, instead of being able to issue an HTTP POST to create a new story by sending a JSON payload to http://eval.versionone.net/platformtest/rest/1.v1/Data/Story we might have to do: [gist id=4684567 file=gistfile4.js]

What if every web site in the Linked Data world used RPC, not REST?

You might think that it is not such a bad idea to have a programmatic API wrapper like the JavaScript example code above. You'd be right, but only if that is not the only compatible, practical way to use the API. We'll use VersionOne as an example, but you can think of the OpenStreetMap or other REST APIs out there in Linked Data Land. Let's see what would happen in a REST world and in an RPC world if VersionOne adds a new kind of asset, like a WorkInProgressLimit asset.

You can use new APIs features immediately with no "data access component library" changes in the REST world

In a REST world, you read about the new WorkInProgressLimit asset type in a VersionOne email, and you go out to your web browser and type: http://eval.versionone.net/platformtest/rest/1.v1/Data/WorkInProgressLimit You authenticate, and then it downloads whatever the current state is of the defined WorkInProgressLimit assets for that particular server. Cool.

You must upgrade your fancy proxies or binary components in an RPC wrapper world

But, if the only way you can communicate with a remote API is via a custom/built, must/download wrapper library, then you have to go download that and update the applications with which you want to start using the new WorkInProgressLimit asset. Then, to explore it, you'd end up firing up a code editor and typing in: [gist id=4684567 file=gistfile5.js]

Wait, don't I have to add code anyway even if the remote API uses REST?

Yes, you still have to add new code to take advantage of the asset regardless of whether the remote API is REST or RPC, but in the REST case: You are not forced to upgrade a custom data access component because no such custom data access component need exist at all for a REST API. A REST API is built atop the generic interface using the standard HTTP methods GET, POST, PUT, DELETE, PATCH, etc. Your "data access component" is actually the HTTP protocol itself and the HTTP client libraries of your web browser or programming stack!

Implications for the Linked Data movement

As Sir Berners/Lee discussed in his TED talks, the Linked Data web is powered by these principles:

1. Use URIs as names for things.
2. Use HTTP URIs, so that people can look up those names.
3. When someone looks up a URI, provide useful information, using the standards (RDF, SPARQL).
4. Include links to other URIs, so that they can discover more things.

In practice, we can see how this works with some abbreviated output from another VersionOne REST Data API query. http://eval.versionone.net/platformtest/rest/1.v1/Data/Story/1154?acceptFormat=haljson (admin / admin for authentication) In this JSON output, there is a _links property. The _links property contains relationships for self, and Scope (parent project) which define the address for where the HTTP client can go to drill into their representations. That's how Linked Data works. That's how the web grows. [gist id=4684567 file=gistfile6.json] Roy Fielding has a maddeningly obtuse acronym related to this called HATEOAS, or Hypermedia As The Engine of Application State, but he explains it very well on his blog.

Let's write some code.

In the next couple of articles, we'll actually start constructing HTTP GET and HTTP POST requests using code in the web browser, through a great free tool called JSFiddle and an open source, extremely powerful and popular JavaScript library named jQuery. Of course, we'll be doing these requests against the VersionOne REST Data API, so stay tuned!

Related Resources

Yep. The web is full of resources about resources indeed:

• Building Web Services the REST Way / Roger Costello's excellent article on RESTful services
• REST APIs must be hypertext/driven / Roy Fielding's blog post about proper REST api design
• Stefan Tilkov on REST and Hypermedia, ROCA, WebSockets vs. HTTP / December 2012 interview about recent REST trends and related techniques from Goto conference
• InfoQ Explores: REST / Compiliation book of prominent articles from InfoQ
• REST FEST conference and video archive / Mike Amundsen's REST FEST conference and video archive, with tons of great talks and information on RESTful design
• Building Hypermedia APIs with HTML5 and Node / Mike Amundsen's book on hypermedia design
• REST Fundamentals Pluralsight Video Course / Howard Dierking's excellent REST course on Pluralsight. Interestingly, it uses an agile tracking board as the domain. Don't go using his ideas to build a tool that's better than VersionOne, now, you hear?
• HAL / Hypertext Application Language / Mike Kelly's proposed standard a 'lean hypermedia type'

Next up

Yes, we're getting into code, at last. Hey I told you in the guide where to go if you wanted to jump into code, here: How To Query the VersionOne REST Data API for User Stories in JSFiddle with jQuery, JSON, HTTP GET, and 9 Lines of Code.