Category: Networking and Internet

Some recommendations about RESTful API design

Reading time: 4 – 6 minutes

I want to recommend to you to watch the YouTube video called RESTful API design of Brian Mulloy. In this post I make an small abstract of the most important ideas of the video, of course from my point of view:

• Use concrete plural nouns when you are defining resources.
• Resource URL has to be focused in access collection of elements and specific element. Example:
  • /clients – get all clients
  • /clients/23 – get the client with ID 23
• Map HTTP methods to maintein elements (CRUD):
  • POST – CREATE
  • GET – READ
  • PUT – UPDATE
  • DELETE – DELETE
• Workaround, if your REST client doesn’t support HTTP methods, use a parameter called ‘method’ could be a good idea. For example, when you have to use a method HTTP PUT it could be changed by method HTTP GET and the parameter ‘method=put’ in the URL.
• Sweep complexity behind the ‘?’. Use URL parameters to filter or put some optional information to your request.
• How to manage errors:
  • Use HTTP response codes to refer error codes. You can find a list of HTTP response codes  in Wikipedia.
  • JSON response example can be like this:

    { 'message':'problem description', 'more_info':'http://api.domain.tld/errors/12345' }

  • Workaround, if REST client doesn’t know how to capture HTTP error codes and raise up an error losing the control of the client, you can use HTTP response code 200 and put ‘response_code’ field in JSON response object. It’s a good idea use this feature as optional across URL parameter ‘supress_response_code=true’.
• Versioning the API. Use a literal ‘v’ followed by an integer number before the resource reference in the URL. It could be the most simple and powerful solution in this case. Example: /v1/clients/
• The selection of what information will be returned in the response can be defined in the URL parameters, like in this example: /clients/23?fields=name,address,city
• Pagination of the response. Use the parameters ‘limit’ and ‘offset’, keep simple. Example: ?limit=10&offset=0
• Format of the answer, in this case I’m not completely agree with Brian. I prefer to use HTTP header ‘Accept’ than his proposal. Anyway both ideas are:
  • Use HTTP header ‘Accept’ with proper format request in the answer, for example, ‘Accept: application/json’ when you want a JSON response.
  • or, use extension ‘.json’ in URL request to get the response in JSON format.
• Use Javascript format for date and time information, when you are formatting JSON objects.
• Sometimes APIs need to share actions. Then we can’t define an action with a noun, in this case use verb. Is common to need actions like: convert, translate, calculate, etc.
• Searching, there are two cases:
  • Search inside a resource, in this case use parameters to apply filters.
  • Search across multiple resource, here is useful to create the resource ‘search’.
• Count elements inside a resource, simply add ‘/count’ after the resource. Example: /clients/count
• As far as you can use a single base URL for all API resources, something like this: ‘http://api.domain.tld’.
• Authentication, simply use OAuth 2.0
• To keep your API KISS usually it’s a good idea develop SDK in several languages, where you can put more high level features than in API.
• Inside an application each resource has its own API but it’s not a good idea publish it to the world, maybe use a virtual API in a layer above it’s more secure and powerful.