REpresentational State Transfer, also known as REST, is a common standard, but it is not actually a defined standard, it is in fact an architectural style, or way of working. Whilst REST is a common "style" it does not lay down the rules on everything. When an API is implemented using a REST style, then it is usually said to be RESTful. This section is my view based on what I have seen, done and learnt, however there is nothing to say it is right. Given that REST is an architectural style then there is also nothing to say I am wrong....

See What is REST, or possibly The RESTful cookbook

API Design

This is a big, complex, non-trivial subject.... However, here is some personal opinion:

  • Start with the most general and get more specific when designing a URL path, for example /bookshop/invoice/lineitem
  • You can add version information to the URL Path, or you can use HTTP Headers or routing based on hostname, all of which work. My personal view would be to put it on the URL Path, for clarity.
Methods or Verbs

It is very important to agree on what HTTP methods (HTTP request methods - HTTP | MDN) to implement and also what HTTP response codes (HTTP response status codes - HTTP | MDN) each of these is going to possibly return. This is what I would suggest.

  • GET - self explanatory, it gets things, but without changing state, typically returning a 200 (Success) or 404 (Not Found)
  • POST - create new item/resource should return 201 (Created), should return status information and a Location header
  • PUT - this should primarily update existing resources, should return 201 (Created) if it made something new, although it could refuse to do this, generally returns a 200 (Success)
  • DELETE - delete the specified item, should return 200 (OK) if done, or 202 (Accepted) if the request is in a queue
  • PATCH - not often implemented, but should only update what is specified
  • OPTIONS - this should list what verbs are supported, but is not often implemented

PUT and DELETE are "idempotent", meaning that multiple identical requests have the same effect as any one of those requests.

REST can work with XML, JSON, YAML or anything else, it is not limited to one format of data and indeed can support many types.