112 karma · joined September 12, 2013
This also is a reason for including hypermedia in your API, because really, being machine-discoverable is not just something that the API itself benefits from... each resource and state can benefit from included hypermedia as well.
The hard part is, instead of asking, "What is the value of my work?" you have to ask "What is the value of my work here?" It's a very odd question to ask if you work for a company that is in national or global markets.
[1] https://www.blossom.io/ [2] http://www.ramen.io/post/46936028144/we-are-switching-to-dar...
https://httpd.apache.org/docs/current/content-negotiation.ht...
With that said, there is nothing wrong with linking to the HTML file with .html, but the developer (or user) consuming the API (or website) should not be adding suffixes to get the representation they want... the API should be returning those URLs in the response.
Additionally, regarding screen scraping, HTML coupled with something like RDF, Schema.org, or other microformats/microdata allows you to parse the HTML looking for that data without breaking clients on HTML changes. It really is a good media type for REST, which does seem odd at first and does feels like screen scraping, but you're just parsing the HTML like you would XML. The difference is HTML is a hypermedia type and XML knows nothing about hypertext.
Here's the great thing about it. If APIs are built this way, and if clients are built to read and understand common and registered hypermedia types, there could be a time where clients and servers are able to communicate in such a way that the media type becomes seemingly invisible to the developer. We see this with the most popular REST client/server combo, the browser and the web server that serves up HTML. As the user, you can traverse the RESTful HTML API that websites have while the media type, HTML, is mostly concealed to the user. In other words, there is a chance that a good number of HTML websites are more RESTful than most of the APIs we see today.
In reducing REST to simply RPC over the web and skipping over the ideas of content negotiation and hypermedia types, we are missing out on the genius behind how the web was designed to be used. The author is really wanting us to go back to that instead of progressing toward the current patterns of fracturing your resources into separate APIs.
REST is an architecture that can be implemented in many different ways, so I doubt there will ever be a one size fits all for REST. I think the real win will be when web frameworks allow us to work primarily with resources and representations instead of an MVC architecture.
If we all built our APIs with a registered content type, it would really go a long way for standardizing APIs. Throw in some HATEOAS and you've got standards and links.
Additionally, your resources should be described through link relations, which, along with media types, allow your API to be self describing and discoverable.
Take, for example, the Business API that is listed on the site [2] and picture Collection+JSON [3] being used to represent the business collection resource and the business item resource. If you used Collection+JSON, what would be left to describe? It would seem like you wouldn't need a Swagger file because your API would be describing itself.
Lastly, even though media types may not be actively promoted or used at this time, I think we should push toward promoting really good hypermedia types.
Edit: I wanted to also add a couple other interesting media types to check out, HAL [4] and Siren [5]. I'm sure there are other really good ones, too.
[1] By definition I'm taking it to mean fully describing an API.
[2] https://github.com/ongithub/businesses/blob/gh-pages/busines...
[3] http://amundsen.com/media-types/collection/
I really think one day down the road, someone will come out with a great "new" architecture and it will be what was outlined in REST.
As a side note, I went looking through many of these and they pointed to Swagger documents, which contained lots of URLs. This seemed to be a relevant article on the pitfalls of doing this along with some ideas on moving forward:
After creating the representations of each of these resources, I would then create URI templates in my root response (I guess found at /rest) that allow for the searching aspect that this site is providing, which would be something like:
{
"_links": {
"search_by_name": {
"href": "/rest/name/{name}",
"templated": true
}
}
}
I may build on to this to provide other resources, like a collection of capitals, each with a link to "/rest/capital/{capital_city}", or a resource of currencies, linking to "/rest/currency/{currency}".The goal of all of this would be to tell the client how to find resources rather than having that hard-coded into the client. These are just some first steps toward being RESTful, and there are lots of different directions you could take this and still be RESTful.
edit: example was incomplete
Take for instance the example above. Whether the URL is /images/10/view or /images/10.png, the developer has no idea what kind of resource that is without any media types or relations (the file extension != to the media type). In other words, you could use both URLs to return the same exact resource, and the client shouldn't care. You could even change back and forth between those URLs and the client should never flinch.
This is actually a good example. Say you are serving a static PNG file at /images/10.png, linked in your server response (i.e. in some href like above). Say you want to change things up to do some type of logging on how many times the image has been viewed, so you write some code, create a response at /images/10/view, log views, and return the image with an image/png media type. You just did a really big API change and the client didn't have to be changed.
Now if your client was dumber, and was crafting URLs as /images/{id}.png, you would break all of your clients if you did the above changes. This of course is really just the tip of the iceberg of what flexibility HATEOAS can bring.
If, on the other hand, you don't conform and use HATEOAS, you have to go look at the documentation on how to build the URL to make a call to the API. Your client can never explore an API, but must be built to make certain calls to certain URLs that are built a certain way.
True REST with HATEOAS was what HTTP 1.1 was built around. It may take some extra work to implement, but it was designed to make communication over the web simpler (and it's worth the trouble). Unfortunately, this article is not really endorsing what REST is, but rather a very common RPC that has been popularized by Rails and labeled as REST.
On their site, they say, "RAML isn't strict: in the end it is only describing HTTP with a few higher-level (optional) constructs." Looks like it's aiming to describe HTTP and URLs rather than hypermedia types.
"In addition to these operations, the subscription server may verify the intent of the subscriber by making an HTTP call to the provided callback with the same parameters requested before and an additional hub.challenge that must be echoed back by the subscriber."