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)
- 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
- Use verbs for action declarations
Singular or Plural?
Use correct grammar for declaration
/people/154 Assume to return 154th person from list of people
Use anyone of the below patterns and be consistent!
Relationships and Resources
- Resources can have
many-to-onerelationships etc. Mapping them correctly is crucial.
Tickets/145/messages/4 suggests one-to-many relationship between
1 ticket has
N messages. Message isn’t standalone resource. You can’t have
Many to Many Mapping
/usergroups/345/users/56 suggests select 345th user group and get user with id 56. However, one user might be in multiple
/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
- PATH : required to access the resource E.g.
- Query Parameters : optional filter the list E.g.
- 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
/carsshould return HTTP 201 created with
locationheader stating how to access the resource E.g.
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.
4xx or message
Expecting int car id /car/id got string car/MH09234