This article does not describe a RESTful architecture. Several things that do not pass the Litmus test <<a href="http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypertext-driven>" rel="nofollow">http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hyperte...</a> or otherwise stick out like a sore thumb:<p>1. Explicit versioning, stuffed into each resource's URI<p>This is really bad, it shows the designer has only experience with RPC, but not resource-oriented. Bumping the server version breaks all clients for no good reason. Imagine if the Web sites worked that way: you have to upgrade your browser before you can visit an updated site. The correct way to do it is to version gradually, and express a changed semantic for a resource type by coining a new link relation for it. Do not put semantics in a resource URI as the article advises!<p>2. Utter lack of hypermedia controls<p>The article mentions CSV as possible media type for that entity. As we all know, CSV does not have or support hyperlinks, forms or any other hypermedia control. This is a serious oversight because it's not possible to have a RESTful architecture without those controls. Remedy: the designer must implement controls in the message body where natively supported by an entity type (e.g. XLink or XForms for XML) or else fall back to the message header (e.g. Link header/URI templates for CSV).<p>3. Fixed URI structuring<p>This is related to point 2 above. Example: </v1/stores/near?lat=12.34&lon=-12.34>
How does the client know how to construct this URI? The article mentions no hyperlinks or other controls. It does say "define the right endpoint names" which I surmise go into some sort of specification document, which is wrong. Doing so makes the server lose control over its URI space and creates unnecessary tight coupling, which is brittle. Express typed resources with link relations, not with the resource URI structure! There must be only exactly one entry point (bookmark) for the client to know, all other URIs are derived by traversing the resources through controls!<p>4. Lack of clue about security<p>The article talks about authentication with OAuth or HTTP basic authentication. OAuth is chiefly for 3rd party authorization, no wonder the article's author is confused. Implementing this is workable, but overkill if all you need is authentication, making it much more difficult for a programmer to implement client software correctly, but brings no benefit. HTTP basic authentication is either clear text or susceptible to replay attacks. <<a href="http://www.xml.com/pub/a/2003/12/17/dive.html>" rel="nofollow">http://www.xml.com/pub/a/2003/12/17/dive.html></a>
Remedy: it's 2014, just use TLS. Let the transport layer take care of authenticating a user, the application code on the server is free of authentication.<p>5. Reinvents the wheel for error handling<p>Established draft standards exist. Use them. <<a href="http://www.mnot.net/blog/2013/05/15/http_problem>" rel="nofollow">http://www.mnot.net/blog/2013/05/15/http_problem></a> <<a href="https://github.com/blongden/vnd.error>" rel="nofollow">https://github.com/blongden/vnd.error></a><p>tl;dr Article is pretty much amateur hour, I advise the interested reader to get one of the classic books on REST instead to learn it properly. <<a href="http://oreilly.com/catalog/9780596529260>" rel="nofollow">http://oreilly.com/catalog/9780596529260></a> <<a href="http://oreilly.com/catalog/9780596805838>" rel="nofollow">http://oreilly.com/catalog/9780596805838></a> <<a href="http://oreilly.com/catalog/9781449358068>" rel="nofollow">http://oreilly.com/catalog/9781449358068></a><p>Update: angle brackets are reserved characters for delimiting a URI, not part of a URI. Hackernews, you are out of compliance with RFC 3986, please fix your shit.
One the subject of versioning, one thing I rather like is to make the versions resources withing the API itself so you really can stick to the RESTful rule of clients only having to know one URL.<p>e.g. For Salesforce's REST API you can see all the versions at:<p><a href="http://na1.salesforce.com/services/data/" rel="nofollow">http://na1.salesforce.com/services/data/</a><p>Documentation:<p><a href="https://www.salesforce.com/us/developer/docs/api_rest/" rel="nofollow">https://www.salesforce.com/us/developer/docs/api_rest/</a>
Dig the article. A couple of things. 1) I can see what you mean for handling auth keys in query string as opposed to "key:" using basic auth. I started using the latter pattern after I went through easypost's api docs. Even though "key:" is a little unbalanced I guess I still dig the basic auth way. YMMV. 2) On error messages, I wrote some code to provide extended info only if the req host is in a white list (set up your white list in an ini file or whatever). I was originally just throwing back a 500 plus whatever the error returned, but the db error info returned by some of the golang drivers is detailed enough that I didn't want to share all of it. Just curious if you had noodled on this issue if it is one for you.
A couple of notes on Authentication:<p>- Including the clear text API key in the URI makes it very easy for anyone listening in to gain unauthorized access. To get around this, one can either enforce HTTPS, or require a hash of a pass phrase.<p>- Another option to look into is Kerberos.
Good article. On the authentication note thought, oath should only be used if you have partners that need to access the API on user's behalf. If the API is internal it's overkill.<p>I prefer single token methods like jwt.