My RESTful API design talk is a popular one and I often give it at various meetups around town. Over the course of time, I’ve collected some questions from the audience and aggregated them here. As with any design, tastes differ. Nevertheless, here’s my take…

1. Besides SSL, other security aspects?

The best practice today is to use HTTP Basic Authorization with Tokens and SSL. SSL encrypts the traffic and the tokens enabled authentication. Authorization can be done on a case-by-case basis via different keys for different use-cases.

Amazon seems to be a fan of signing each request, you could also look into that.

2. Should DELETEs be idempotent?

Yes, if possible. Usually, you’d mark resources as deleted in the database and not actually delete them. That way if a client requests an already deleted object, you ignore it. This is a better user experience than throwing an error.

3. Is django-rest-framework tied to django?

Despite its name, django-rest-framework isn’t tied to django. There are a set of generic views that can proxy any resource, including another API. In fact, I know of a team that used django-rest-framework to wrap a SOAP based API.

4. Is it possible to do RPC over REST?

Definitely possible. You’ll want to rip out all the extra overhead as RPC endpoints are meant to be used internally and not exposed to the public. You’ll also want to switch from HTTP to a more efficient transport like Thrift.

5. What about Thrift?

Thrift is a serialization framework that is compact in space (therefore efficient over the network). It also comes with various transport options to store to disk, or over a socket. The biggest win from using Thrift is that the serialization format is readable by dozens on languages, enabling a polyglot architecture.

6. Should you strictly use the 4xx HTTP codes for errors?

I’ve seen some Google APIs that wrap error codes within a 200 response. This is more RPC style and the API client is supposed to look inside to get the actual error message. An interesting use case, though not recommended.

7. Why not use automatic tools to generate API endpoints?

No particular reason. I’m yet to see an autogenerated API that is clean and performant.

8. How to do testing?

API Testing needs to be on a layer above unit testing the actual methods. You should be have a testing matrix for each (endpoint, HTTP verb) combination to be exhaustive.

9. How do to governance?

Managing the Who, What and How of endpoints is a big topic in itself. The simplest way to do this is by gating on the API Token, like row-level-permissions implemented by some packages (see django packages for example.) You’ll also want to log every request for audit purposes.

10. OK to use verbs in the url?

I feel if the need warrants the use of verbs in the url, then do so. Think of verbs like “search”, “move”, “analyze”, makes it clearer.

Photo Credit: Skley