Chrome, JavaScript, webdev

How To Create A RESTful API

Google APIs with picturesque app

If you wish to read the background on RESTful APIs It’s all started here.  You can look at some good examples for RESTful APIs from Google, Twitter and many others. In this post, I will try to focus on some important aspect that you want to keep in mind when you are building your next RESTful API. Btw, if you are looking on an efficient way to create it – Checkout my talk from last Google I/O. It’s over a year now, but still very relevant.

Main aspects to pay attention

        • It should use web standards where they make sense. In HTTP world the main verbs are:
          1. GET – Read a specific resource (by an identifier) or a collection of resources.
          2. PUT – Update a specific resource (by an identifier) or a collection of resources. Can also be used to create a specific resource if the resource identifier is know before-hand.
          3. DELETE – Remove/delete a specific resource by an identifier.
          4. POST – Create a new resource. Also a catch-all verb for operations that don’t fit into the other categories.
        • It should be friendly to the developer and be explorable via a browser. Extra points if you can give the developers the option to ‘play’ with your API from their browser in your page.
        • It should be simple, intuitive and consistent. It’s easy to say and very hard to accomplish. However, try to build something and ask an ‘export’ Frontend developer to ‘try’ it. Their feedback will help you a lot to build something usable.
        • It should be efficient or in other words, make it responds as fast as you can.
          Speed is very important with raw APIs as in most cases there will be another layer of calculations on top of it.
        • JSON is the choice of most developers. It’s simple, efficient and if you must JSON-Schema offers schema-style validation capabilities.
        • Use HTTP Response Status Codes to ‘answer’ your developer. Here are few common examples:
          • 200 OK – Indicate success.
          • 201 CREATED – Successful creation occurred (via either POST or PUT). Set the Location header to contain a link to the newly-created resource (on POST).
          • 204 NO CONTENT – Indicates success but nothing is in the response body, often used for DELETE and UPDATE operations.
          • 400 BAD REQUEST – General error when fulfilling the request would cause an invalid state. Domain validation errors, missing data, etc. are some examples.
          • 401 UNAUTHORIZED – Error code response for missing or invalid authentication token.
          • 403 FORBIDDEN – Error code for user not authorized to perform the operation or the resource is unavailable for some reason (e.g. time constraints, etc.).
          • 404 NOT FOUND – Used when the requested resource is not found, whether it doesn’t exist or if there was a 401 or 403 that, for security reasons, the service wants to mask.
          • 405 METHOD NOT ALLOWED – Used to indicate that the requested URL exists, but the requested HTTP method is not applicable. For example, POST /users/111 where the API doesn’t support creation of resources this way (with a provided ID). The Allow HTTP header must be set when returning a 405 to indicate the HTTP methods that are supported. In the previous case, the header would look like “Allow: GET, PUT, DELETE”
          • 409 CONFLICT – Whenever a resource conflict would be caused by fulfilling the request. Duplicate entries, such as trying to create two customers with the same information, and deleting root objects when cascade-delete is not supported are a couple of examples.
          • 500 INTERNAL SERVER ERROR – Never return this intentionally. The general catch-all error when the server-side throws an exception. Use this only for errors that the consumer cannot address from their end.
        • Walk before you run. So start with small, easily defined resources (e.g. user, car, home), providing CRUD functionality on those. Later, you could work on those use-case-oriented resources later.
        • Try your API from few clients in order to see what can be improved. There are many cases, when your API will be consume from the web, Android and iOS. For each platform, you might want to make sure the client library you are maintaining (or in cloud endpoints case – Google is creating) is up to date and providing your developer a great experience.

Misc

 

Advertisement
Standard