I have been working on Hypermedia API’s recently. They do provide a benefit to the client who wants to use your API, discovery. While you would want to still add some documentation, Hypermedia API’s give you best way to allow users to play with your API and learn it. Let me show you why.
It has been a while since I have done my last article on REST. I have learned much more as to why this new REST paradigm works, let me show you a real example, using a media type application/hal+json:
{ "page": 0, "pageSize": 1, "totalRecords": 40, "\_embedded": { "fbomb:data": [ { "Category": "Web", "Id": "1395077907732", "DateOfArticle": "2014-03-17", "Title": "OReilly Fluent Conference 2014", "Author": "Jorden Lowe", "Summary": "Just came back from OReilly Fluent Conference, and it was fun. Learned a bunch of topics like web components, security, best practices, hypermedia API's and organizing a team. I will talk about each one of these topics, based on my <a href=\"/fluent2014\">slides</a>.\n", "IsEnabled": true, "IsCommentingEnabled": "1", "\_links": { "self": "/article/1395077907732", "fbomb:comments": "/article/1395077907732/comments" } } ] }, "\_links": { "self": "/articles?pageSize=1&page=0", "curies": [ { "name": "fbomb", "href": "http://example.com/docs/rels/{rel}", "templated": true } ], "next": "/articles?pageSize=1&page=1", "last": "/articles?pageSize=1&page=39", "first": "/articles?pageSize=1" } }
So, this is from my new web api for the blog (still in the works). I punched in a base uri of /articles?pageSize=1 and it gave me a bunch of stuff back. What is cool is there is links to visit other parts of the site, not just this one URI.
Starting at the top, you will see some general properties, like page, pageSize and etc. These tell you about information you are requesting. These you can use in the request itself to control how much data you receive. It’s really great in paging data on the front end.
Next, you have an \_embedded property. This is for data that is related to the call, like in our case we have a list of articles. This makes sense to show all of this in a list and how to get to each individual record, if needed. Embedded resources could have more embedded resources, and the rule of thumb is to include all the information that makes sense. In my example, articles embed single articles, but I choose not to embed comments and make them a link. Later, if my workflow changes, I could remove them from the links, and embed the data into each article.
Lastly, I have links, and links are cool, because they point you to more information about the web api you are working with. So, in articles, we have pages. But, if you notice in the links section, we can visit the “next” page of the articles, which gives us another set of records, based on our page size. You can even change pageSizes and play with parameters now because you know how the formats of URL’s work.
Even though you can sorta discover things about the site, you can embed something called ‘curies’. These allow you to namespace special tags, much like xml namespacing works. The link you would give in the href for curies would be a location for documentation to tell you specifically how everything about your special namespace works.
The point to all of this is to allow users to link through your web api, just like users click links on a web page. This can be powerful because now the user can discover how to use your API, without documentation. Even if your user is lost, you can provide curies to help guide them to where they are going in your API. This provides a great way to allow a flexible API that can grow, just like the web. I’m thinking once I get the API going, I will write some clients to show how easy it is to navigate the API, compared to other REST services. More on that to follow.