RESTful web services are a thing I love to discuss, build, and use. However, most of them stop short at sending JSON (or XML) back and forth over the wire.<\/p>\n
I read the documentation. I write some code with URLs in it and tie my JavaScript, Python, or PHP right into the vendor\u2019s API as it\u2019s currently structured. Any changes to the URLs, and I need to change my code.<\/p>\n
What I know about the web doesn\u2019t jive with that. You didn\u2019t read any documentation to find out the URL Codeship uses for this blog post or the blog\u2019s main page or their services list<\/a> or sign-up page<\/a> either. That\u2019s because HTML, the original web hypermedia format, has these fabulous things called links. JSON and XML don\u2019t.<\/p>\n Let\u2019s take a quick dive into a world of browsable, hypermedia APIs.<\/p>\n Hypermedia APIs are RESTful APIs that use links and media types to avoid some of the chaos of change.<\/p>\n When you visit a web page, you don\u2019t have to read the website\u2019s documentation to know which thing is something you can click or which part of the site can receive data. The web page has all that information in it. You just click. You fill out forms. You browse.<\/p>\n Web browsers take the HTML documents on the web and make them browsable, make them linked, and make the web updatable via forms. Hypermedia APIs offer that same flexibility and opportunity to code.<\/p>\n Hypermedia enables browsable APIs by using media types that are defined to contain hypermedia affordances<\/a> \u2014 essentially, links and forms.<\/p>\n Sadly, sprinkling URLs into some JSON values doesn\u2019t cut it. In essence, Hypermedia-enabled media types, however, contain this information within their definitions. Here\u2019s a short list of some JSON-based hypermedia types:<\/p>\n Many of these also have more specific extensions or additional vocabularies such as Hydra<\/a> and Schema.org Actions<\/a> for JSON-LD. In this case, the media type stays the same, but the contents have additional \u201cmeaning\u201d specific to APIs.<\/p>\n For today, we\u2019re going to run with HAL, the Hypermedia Application Language<\/a>.<\/p>\n Apache CouchDB is a NoSQL database that uses JSON and HTTP for its entire API. It\u2019s about as simple and straightforward an API as you\u2019ll find. It\u2019s also a great foundation for building CRUD applications quickly.<\/p>\n However, it lacks any hypermedia affordances, which means if you land at any of its endpoints, you\u2019ll have no idea where to go next or what else may be possible.<\/p>\n The stock API is about as simple as it gets:<\/p>\n All three of these endpoints return \u201cpure JSON,\u201d typically sent as What would this API be like if you didn\u2019t have to read the docs? What would it mean to be able to \u201cbrowse your database\u201d from your code? Let\u2019s hypermedia this thing.<\/p>\n HyperCouch<\/a> is an exploration of what CouchDB might be like with a hypermedia API. It wraps the core CouchDB API in various hypermedia formats. It can also be used to hypermedia-enable a CouchDB-based data store such as your next API.<\/p>\n Here are the standard responses to the three endpoints referenced above, along with the new Hypermedia Application Language variations:<\/p>\n Just a pure JSON object with some numbers in it.<\/p>\n Now. If you\u2019d asked for that first and wanted to see the contents of the database, where would you go? Don\u2019t go search for the CouchDB docs! Your code can\u2019t.<\/p>\n Let\u2019s take a look at a HAL variation:<\/p>\n HAL+JSON documents are essentially \u201cjust JSON\u201d plus a Let\u2019s look at the other two endpoints.<\/p>\n The The If CouchDB served its own JSON-based media type for this endpoint, it could have been defined to state that The Now, with these links in place, client code could start at any one of these endpoints and could follow the values of those link relationships \u2014 rather than hard coding URLs \u2014 to find its way around the database.<\/p>\n One thing HAL leaves out of the equation are in-line hints about what methods can be used at which URL. Thankfully, HTTP has that skill.<\/p>\n The HTTP Alternatively, it\u2019s possible to simply attempt a However, there are efforts, such as the in-progress HAL Forms specification<\/a>, that allow developers to encode HTML-style form information directly in the HAL response.<\/p>\n The HAL community has its own (minimal) browser for finding your way around these HAL responses know as (obviously enough) the HAL Browser<\/a>. They have an example API which is loaded by default, but it also works on In the end, your next API may be \u201cjust JSON\u201d over HTTP. However, your API will change, and when it does, how will you address those changes? The web, thanks in part to links and media types, has survived a couple decades of incremental change. Perhaps it\u2019s time our APIs were this resilient.<\/p>\nHypermedia APIs<\/h2>\n
Media Type Mastery<\/h2>\n
application\/json<\/code> is no more a hypermedia, link-containing format than text\/plain<\/code>. They may contain text that is a URL, but they could be anywhere and mean anything. Most importantly, to a JSON parser, they\u2019re just strings.<\/p>\n\n
application\/ld+json<\/code> \u2013 spec<\/a> and registration<\/a><\/li>\napplication\/collection+json<\/code> \u2013 spec<\/a> and registration<\/a><\/li>\napplication\/hal+json<\/code> \u2013 spec<\/a> and registration<\/a><\/li>\napplication\/vnd.siren+json<\/code> \u2013 spec<\/a> and registration<\/a><\/li>\napplication\/vnd.api+json<\/code> \u2013 spec<\/a> and registration<\/a><\/li>\n<\/ul>\nApache CouchDB: an HTTP Database<\/h2>\n
\n
\/{db}<\/code>\n\n
\/{db}\/{doc}<\/code>\n\n
\/{db}\/_all_docs<\/code>\n\n
application\/json<\/code>. Handy, if you know what you\u2019re getting at each endpoint (a.k.a.<\/em>, you\u2019ve read the docs). However, if all you\u2019d been given was the \/{db}<\/code> URL, you\u2019d have no idea how to even find the list of documents within it.<\/p>\nHyperCouch(DB)<\/h2>\n
GET \/{db}<\/code><\/p>\n{\r\n \"db_name\":\"hypercouch\",\r\n \"doc_count\":2,\r\n \"doc_del_count\":0,\r\n \"update_seq\":2,\r\n \"purge_seq\":0,\r\n \"compact_running\":false,\r\n \"disk_size\":12393,\r\n \"data_size\":7377,\r\n \"instance_start_time\":\"1459778528583743\",\r\n \"disk_format_version\":6,\r\n \"committed_update_seq\":2\r\n}<\/pre>\n{\r\n \"db_name\":\"hypercouch\",\r\n \"doc_count\":2,\r\n \"doc_del_count\":0,\r\n \"update_seq\":2,\r\n \"purge_seq\":0,\r\n \"compact_running\":false,\r\n \"disk_size\":12393,\r\n \"data_size\":7377,\r\n \"instance_start_time\":\"1459778528583743\",\r\n \"disk_format_version\":6,\r\n \"committed_update_seq\":2,\r\n \"_links\": {\r\n \"self\": { \"href\": \"\/hypercouch\/\" },\r\n \"index\": { \"href\": \"\/hypercouch\/_all_docs\" }\r\n }\r\n}<\/pre>\n_links<\/code> object and (optionally) an _embedded<\/code> object (which we\u2019ll look at shortly). The keys within the _links<\/code> object are the link relationship<\/a> of the contained links. The included href<\/code> does what any old href<\/code> does: It contains a URL. In this case, it\u2019s a small additional bit of content that routes the code (or user) to the appropriate endpoint for the primary index within the database.<\/p>\nGET \/{db}\/{doc}<\/code><\/p>\n{\r\n \"_id\": \"db74fd2411e1a0da283b3f0fc8000074\",\r\n \"_rev\": \"1-1d7fcf86f6f6ec8d0e63f6de7af5ce81\",\r\n \"first_name\": \"Benjamin\"\r\n}<\/pre>\n_id<\/code> and _rev<\/code> values are reserved by CouchDB and record the name and revision identifier of the document.<\/p>\n{\r\n \"_id\": \"db74fd2411e1a0da283b3f0fc8000074\",\r\n \"_rev\": \"...\",\r\n \"first_name\": \"Benjamin\",\r\n \"_links\": {\r\n \"self\": { \"href\": \"\/hypercouch\/db74fd2411e1a0da283b3f0fc8000074\" },\r\n \"index\": { \"href\": \"\/hypercouch\/_all_docs\" },\r\n \"collection\": { \"href\": \"\/hypercouch\/\" }\r\n }\r\n}<\/pre>\n_links<\/code> object here feels at home among the native _prefixed<\/code> CouchDB reserved keys. In this case, it contains the link relationships we saw earlier for self<\/code> and index<\/code>. I\u2019ve also added a collection link relationship from RFC6573<\/a>: \u201cThe Item and Collection Link Relations.\u201d Essentially, it points back to the database this document is contained within.<\/p>\nGET \/{db}\/\\_all\\_docs<\/code><\/p>\n{\r\n \"total_rows\":2,\r\n \"offset\":0,\r\n \"rows\":[\r\n {\r\n \"id\": \"_design\/hal\",\r\n \"key\": \"_design\/hal\",\r\n \"value\": { \"rev\":\"1-0b1f6e8f2662fc5e7efcd9f930acec60\" }\r\n },\r\n {\r\n \"id\": \"db74fd2411e1a0da283b3f0fc8000074\",\r\n \"key\": \"db74fd2411e1a0da283b3f0fc8000074\",\r\n \"value\": { \"rev\":\"1-1d7fcf86f6f6ec8d0e63f6de7af5ce81\" }\r\n }\r\n]}<\/pre>\nid<\/code> here was a relative URL. However, since that didn\u2019t happen, we\u2019ll upgrade this one to HAL also. The changes to this one though are more significant and change the shape of the original JSON:<\/p>\n{\r\n \"total_rows\":2,\r\n \"offset\":0,\r\n \"_embedded\":{\r\n \"item\": [\r\n {\r\n \"id\": \"_design\/hal\",\r\n \"key\": \"_design\/hal\",\r\n \"value\": { \"rev\":\"1-0b1f6e8f2662fc5e7efcd9f930acec60\" },\r\n \"_links\": {\r\n \"self\": { \"href\": \"\/hypercouch\/_design\/hal\" }\r\n }\r\n },\r\n {\r\n \"id\": \"db74fd2411e1a0da283b3f0fc8000074\",\r\n \"key\": \"db74fd2411e1a0da283b3f0fc8000074\",\r\n \"value\": { \"rev\":\"1-1d7fcf86f6f6ec8d0e63f6de7af5ce81\" },\r\n \"_links\": {\r\n \"self\": { \"href\": \"\/hypercouch\/db74fd2411e1a0da283b3f0fc8000074\" }\r\n }\r\n }\r\n ],\r\n \"_links\": {\r\n \"self\": { \"href\": \"\/hypercouch\/_all_docs\" },\r\n \"collection\": { \"href\": \"\/hypercouch\/\" }\r\n }\r\n}<\/pre>\n_embedded<\/code> object contains partial representations of the embedded resources. Each of these partial representations includes its own _links<\/code> object which points to the self<\/code> value which can be used to retrieve the entire representation \u2014 which of course contains a link back to the index<\/code> and collection<\/code>.<\/p>\nWrite Semantics<\/h2>\n
Allow<\/code> header is intended to provide a comma separated list of HTTP method names available on the requested resource. HTTP also comes with a handy HEAD<\/code> method that allows you to only get the meta information about the resource \u2014 without the overhead of GET<\/code>ing the entire representation.<\/p>\nPUT<\/code> (for overwrite\/update) or POST<\/code> (for append) operation and see how it goes. If the server\u2019s doing its job, it should respond with a 404 Method Not Allowed<\/code> error. If it\u2019s really doing its job well, then that response will have the Allow<\/code> header.<\/p>\nHAL Browsing<\/h2>\n
localhost<\/code> URLs or your very own hypercouch.dev<\/code> instance.<\/p>\nAPIs + Links<\/h2>\n