API Design



Posted by JB Uy on February 05, 2014 at 07:27 PM UTC
Edited on February 12, 2014 at 09:41 PM UTC
7 Notes

Errors


http://www.vinaysahni.com/best-practices-for-a-pra...

Should return a sensible 400 or 500 series error code, with an error message in a consumable format.

ie.

{
  "code" : 1234,
  "message" : "Something bad happened :(",
  "description" : "More details about the error here"
}
Posted by JB Uy on February 05, 2014 at 07:55 PM UTC
via hutility.notedock.com | Link

Caching


2 Ways that come with HTTP:

  • ETag
  • Last-modified
Posted by JB Uy on February 05, 2014 at 07:52 PM UTC
via hutility.notedock.com | Link

Authentication

  • no cookies, no state
  • all requests should come with their own authentication credentials

Why not HTTP Basic Auth (over SSL)?

FromĀ http://www.stormpath.com/blog/secure-your-rest-api...

  • if passwords are changed, you need to change the password for everything using the API as well.
  • there will be thousands of requests for authentication (unlike on a website with cookies, b/c auth needs to happen every time), having to hash and check if the password is correct can be slow and costly.

Alternative:

Use a system like Twilio's (if the use case applies) where HTTP Basic Auth is used with an 'Account SID' and 'Auth Token' in place of username and password.

This way, the cons of HTTP Basic Auth for an API aren't in play (2 sets of auth: 1 for user to login, the other for API; No need to hash and check password against DB)


OAuth:

http://net.tutsplus.com/tutorials/oauth-2-0-the-go...

http://oauthlib.readthedocs.org/en/latest/oauth_1_...



This usage of OAuth does not apply to a client/server RESTful API. Something like this would only make sense if your RESTful API can be accessed by third party applications (consumers).

http://blog.miguelgrinberg.com/post/restful-authen...

Posted by JB Uy on February 05, 2014 at 07:52 PM UTC
Edited on February 06, 2014 at 09:11 PM UTC
via hutility.notedock.com | Link

Overriding the HTTP method


http://www.vinaysahni.com/best-practices-for-a-pra...

Some HTTP clients can only work with simple GET and POST requests. To increase accessibility to these limited clients, the API needs a way to override the HTTP method. Although there aren't any hard standards here, the popular convention is to accept a request header X-HTTP-Method-Override with a string value containing one of PUT, PATCH or DELETE.

Note that the override header should only be accepted on POST requests. GET requests should never change data on the server!

Posted by JB Uy on February 05, 2014 at 07:46 PM UTC
via hutility.notedock.com | Link

Updates with PUT and POST:


http://www.vinaysahni.com/best-practices-for-a-pra...

A PUT, POST or PATCH call may make modifications to fields of the underlying resource that weren't part of the provided parameters (for example: created_at or updated_at timestamps). To prevent an API consumer from having to hit the API again for an updated representation, have the API return the updated (or created) representation as part of the response.

In case of a POST that resulted in a creation, use a HTTP 201 status code and include a Location header that points to the URL of the new resource.

Posted by JB Uy on February 05, 2014 at 07:35 PM UTC
via hutility.notedock.com | Link

Versioning


http://www.vinaysahni.com/best-practices-for-a-pra...

Always version your API. Versioning helps you iterate faster and prevents invalid requests from hitting updated endpoints. It also helps smooth over any major API version transitions as you can continue to offer old API versions for a period of time.

There are mixed opinions around whether an API version should be included in the URL or in a header. Academically speaking, it should probably be in a header. However, the version needs to be in the URL to ensure browser explorability of the resources across versions (remember the API requirements specified at the top of this post?).

Posted by JB Uy on February 05, 2014 at 07:31 PM UTC
Edited on February 05, 2014 at 07:32 PM UTC
via hutility.notedock.com | Link

SSL


http://www.vinaysahni.com/best-practices-for-a-pra...

One thing to watch out for is non-SSL access to API URLs. Do not redirect these to their SSL counterparts. Throw a hard error instead! The last thing you want is for poorly configured clients to send requests to an unencrypted endpoint, just to be silently redirected to the actual encrypted endpoint.

Posted by JB Uy on February 05, 2014 at 07:27 PM UTC
Edited on February 05, 2014 at 07:33 PM UTC
via hutility.notedock.com | Link
Public Comments
comments powered by Disqus