RESTful

RESTful means that the API in question is fully compatible with the REST standard. The REST software development standard refers in particular to websites. In order to claim that the API we wrote meets the REST standards, it must meet the following requirements in practice:

• Unique methods by which it queries the API such as GET, PUT, DELETE, PATCH defined as a unified interface.
• The given query is independent of the state of the application, it always returns the same thing, i.e. if we ask for a resource with ID=1 in the API then regardless of whether we are user A or B we should get the same thing
• The API returns messages about whether the query was successful or returned an error. The API should indicate exactly what the error was.
• The query to the API should explicitly state what type of resource it is querying, and for book querying we will use a different one
• The client does not directly interact with the server's resources in any way
• Ability to use cache. The API must return information whether the resource is stored and whether it can be stored

It is worth remembering that REST is not the same as HTTP, and also REST does not impose in any way the type of data that is returned from the API. It can be either JSON or plain text.

What a REST query to the API looks like

Each API query should have the following elements:

• Endpoint name
• Type of method
• Headers
• Data

An example query of type GET would be

curl -H "Authorization: OAuth <ACCESS_TOKEN>" http://www.example.com/users/2

Practical RESTful tips

There are a lot of generalities about RESTful APIs, but it's hard to find good resources on what to do to actually make our APIs meet REST standards.

URL construction in a RESTful API

One of the most important things is the construction of the URL. The url should have:

• use only lowercase letters
• use a hyphen ( - ) instead of an underline ( _ )
• do not add the return data type to our url, instead you should use Content-Type in the header
• use plural in the name for collection names, e.g. /books/
• use singular for document names, e.g. /books/sciencefiction/
• do not use create, delete methods in the name e.g. it is a mistake to make /deletebook/
• we can version and should add the main api version to the name e.g. /v1/books/

Returned response codes

The API should return response codes. The standard is responses containing error codes numbered from 2xx, 3xx, 4xx, 5xx. All but responses in the 200 group mean that there is an error in our API.