Inherently, HTTP transactions have no "state", e.g. an event is only available during the transaction and exists no longer than the transaction. RESTful API's utilize HTTP request + response transactions to communicate data between services and consumers.
Hyper Text Transfer Protocol (HTTP) is used to communicate these transactions. RESTful services utilize routes, queries, bodies, headers, methods, and status-codes to create a meaningful interface/standard for these transactions.
The core goal of REST services is to provide Create, Read, Update and Delete (CRUD) mechanisms on a resource. A well-designed REST API utilizes the components of HTTP requests & responses to provide a consistent, meaningful syntax for performing CRUD operations.
HTTP request methods indicate to a service what action should be performed on a resource.
| METHOD | ACTION |
|---|---|
GET |
(R) Retrieve from a resource |
POST |
(C) Add to a resource |
PUT |
(U) Replace an item (full update) in a resource |
PATCH |
(U) Replace data in an item (partial) in a resource |
DELETE |
(D) Remove an item from a resource |
Path parameters and queries are used to indicate the target of an action on a REST API.
<protocol>://<domain>/<resource>/<parameter>?<query>
Examples:
>> Use HTTPS protocol to connect to `api.com` and interact with the `users` resource:
https://api.com/users
>> Use HTTPS protocol to connect to `api.com` and interact with the `users` resource, specifically the item with id `12345`
https://api.com/users/12345
>> Use HTTPS protocol to connect to `api.com` and interact with `users` resource, specifically those with property `type` of `admin`
https://api.com/users?type=admin
Headers provide a method for communicating specifics on an action that cannot be expressed with the method or the path.
Headers can send a variety of information to a REST API, from authentication to resource-specific instructions
Examples:
{
Content-Type: 'application/json',
Authorization: 'Bearer KDIN73dDJi83jk9WKs99djSSSKs',
x-limit: 10,
x-start-record: '56789'
}
The above headers indiacte the following:
- Content sent will be in JSON format
- Authorization will be done with the included
Bearertoken - Limit response to 10 items
- Start pagination at record with id
56789
There are a myriad of standard HTTP headers (Content-Type and Authorization in the above example). Non-standard headers are represented with a prefix, typically x-.
Response headers are also important. A response header could include information like x-last-record. If the above example were used in a situation where results from a search were being paginated, the consumer would utilize x-last-record to indicate the next requests x-start-record in order to preserve the "state" of the pagination action.
It is imperative for consuming services of n API to understand context of a response immediately as this indicates to the consuming service how to process the response.
For example, a success (200) for a POST could indicate to the consumer that the record should be shown in an interface, whereas an invalid request (400) could indicate that the user interface should display verbiage to instruct a resolution to the error (e.g. validation error on an input).
1×× Informational
100 Continue
101 Switching Protocols
102 Processing
2×× Success
200 OK
201 Created
202 Accepted
203 Non-authoritative Information
204 No Content
205 Reset Content
206 Partial Content
207 Multi-Status
208 Already Reported
226 IM Used
3×× Redirection
300 Multiple Choices
301 Moved Permanently
302 Found
303 See Other
304 Not Modified
305 Use Proxy
307 Temporary Redirect
308 Permanent Redirect
4×× Client Error
400 Bad Request
401 Unauthorized
402 Payment Required
403 Forbidden
404 Not Found
405 Method Not Allowed
406 Not Acceptable
407 Proxy Authentication Required
408 Request Timeout
409 Conflict
410 Gone
411 Length Required
412 Precondition Failed
413 Payload Too Large
414 Request-URI Too Long
415 Unsupported Media Type
416 Requested Range Not Satisfiable
417 Expectation Failed
418 I'm a teapot
421 Misdirected Request
422 Unprocessable Entity
423 Locked
424 Failed Dependency
426 Upgrade Required
428 Precondition Required
429 Too Many Requests
431 Request Header Fields Too Large
444 Connection Closed Without Response
451 Unavailable For Legal Reasons
499 Client Closed Request
5×× Server Error
500 Internal Server Error
501 Not Implemented
502 Bad Gateway
503 Service Unavailable
504 Gateway Timeout
505 HTTP Version Not Supported
506 Variant Also Negotiates
507 Insufficient Storage
508 Loop Detected
510 Not Extended
511 Network Authentication Required
599 Network Connect Timeout Error
Get all items from resource users
Request:
Method: GET
URL: http://api.com/users
Response:
[
{
id: '1234567890'
email: '[email protected]'
}
...
]
Get a specific item from resource users
Request:
Method: GET
URL: http://api.com/users/1234567890
Response:
{
id: '1234567890',
email: '[email protected]'
}
Get items from resource users based on query
Request:
Method: GET
URL: http://api.com/[email protected]
Response:
[
{
id: '1234567890',
email: '[email protected]'
}
]
Create a new item in resource users
Request
Method: POST
URL: http://api.com/users
Payload:
{
email: '[email protected]'
}
Response:
{
id: '2345678901',
email: '[email protected]'
}
Updates an existing item in resource users
Request:
Method: PUT
URL: http://api.com/users/2345678901
Payload:
{
id: '2345678901',
email: '[email protected]'
}
Response:
{
id: '2345678901',
email: '[email protected]'
}
Removes an existing item in resource users
Request:
Method: DELETE
URL: http://api.com/users/1234567890
Response:
Ok