History
REST stands for Representational State Transfer protocol. Roy Fielding defined REST in his PhD dissertation in 2000.
What is a REST API?
REST was developed to provide a uniform interface for
- Identifying resources
- Manipulation of resources
- Self descriptive messages
- Using Hypermedia as the Engine of Application State (HATEOS)
Best Practices
Basics
Method || http://api.co/v2/cars || http://api.co/v2/cars/1234
- GET || List all the cars || Retrieve an individual car
- POST || Create a new car || Error
- PUT || Replace cars collections || Replace the car with id 1234
with new one - DELETE || Delete all cars || Delete car with id 1234
Note while PUT operations either client or server can generate id’s
Nouns are good Verbs are bad
- Use nouns to refer resources like
cars
,fruits
etc. - Use verbs for action declarations
convertMilesToKms
,getNutritionalValues
Singular or Plural?
Use correct grammar for declaration
Avoid /person/145
Prefer /people/154
Assume to return 154th person from list of people
Use cases
Use anyone of the below patterns and be consistent!
Case StylesExampleUpperCamelCasehttp://api.fintech.cp/DailyTransactions/Today
lowerCamelCasehttp://api.fintech.cp/dailyTransactions/today
snake_casehttp://api.fintech.cp/daily_transactions/today
Relationships and Resources
- Resources can have
one-to-many
,many-to-many
,many-to-one
relationships etc. Mapping them correctly is crucial.
One-to-Many Mapping
For example, Tickets/145/messages/4
suggests one-to-many relationship between tickets
and messages
. Meaning 1
ticket has N
messages. Message isn’t standalone resource. You can’t have /messages/4
.
Many to Many Mapping
For example, /usergroups/345/users/56
suggests select 345th user group and get user with id 56. However, one user might be in multiple usergroups
i.e. /usergroups/209/users/56
is also valid. In such case so for seperating the depedant resource users
into a seperate endpoint like /users/56
and provide resource linking in /usergroups/209/users/56
API Parameters
- PATH : required to access the resource E.g.
/cars
,/fruits
- Query Parameters : optional filter the list E.g.
/cars?type=SUV&year=2010
- Body : Resource specific logic. Advance search query. Sometimes it might have both Query and body.
- Header : Should contain global or platform wide data. E.g. API key parameters, encrypted keys for auth, device type information e.g. mobile or desktop or endpoint, device data type e.g. xml or json. Use header to communicate these parameters
HTTP Status Codes
Use correct status codes
CodesMeaning1xxRequest received and understood.2xxAction requested by client was received, understood and requested.3xxClient must take additional action to complete the request. Most of these status codes are used in URL Redirection.4xxIntended for situations where it seems the error was caused by the client.5xxThe server failed to fulfil a request.
Little more on 2xx!
- 201 Resource Created. POST
/cars
should return HTTP 201 created withlocation
header stating how to access the resource E.g.location
:api.com/cars/124
in header
202 - Accepted
Use this if the task is huge to run. Tell the client, it has accepted the request and will/is process/processing No payload is returned
204 - No content
Used when deleted DELETE cars/124
Returns no content. But can also return 200 OK
if API intends to send the deleted resource for further processing.
The dangerous 5xx resources!
- 500 Internal Server Error
- 504 Gateway Timeout. Server didn’t receive timely response
Less known 4xx suggests that you are passing wrong parameter. Can also pass information that is wrong. E.g.
DELETE /cars/MH09234
returns 4xx
or message Expecting int car id /car/id got string car/MH09234