REST API
Why REST?
Why JSON?
Design
Base URL
Resource
Resource Format
Content Negotiation
Query Parameters
Pagination
Errors
Security
Caching & ETags
Rate Limiting
Multi Tenancy
Maintenance
HTTP Verbs
Use HTTP Verbs to Make Your Requests Mean Something API consumers are capable of sending GET, POST, PUT, and DELETE verbs, which greatly enhance the clarity of a given request. (source)
Generally, the four primary HTTP verbs are used as follows:
GET Read a specific resource (by an identifier) or a collection of resources.
PUT Update a specific resource (by an identifier) or a collection of resources. Can also be used to create a specific resource if the resource identifier is know before-hand.
DELETE Remove/delete a specific resource by an identifier.
POST Create a new resource. Also a catch-all verb for operations that don't fit into the other categories.
HTTP Status Codes
Suggested usages for the "Top 10" HTTP Response Status Codes are as follows (source):
200 OK General success status code. This is the most common code. Used to indicate success.
201 CREATED Successful creation occurred (via either POST or PUT). Set the Location header to contain a link to the newly-created resource (on POST). Response body content may or may not be present.
204 NO CONTENT Indicates success but nothing is in the response body, often used for DELETE and PUT operations.
400 BAD REQUEST General error for when fulfilling the request would cause an invalid state. Domain validation errors, missing data, etc. are some examples.
401 UNAUTHORIZED Error code response for missing or invalid authentication token.
403 FORBIDDEN Error code for when the user is not authorized to perform the operation or the resource is unavailable for some reason (e.g. time constraints, etc.).
404 NOT FOUND Used when the requested resource is not found, whether it doesn't exist or if there was a 401 or 403 that, for security reasons, the service wants to mask.
405 METHOD NOT ALLOWED Used to indicate that the requested URL exists, but the requested HTTP method is not applicable. For example, POST /users/12345 where the API doesn't support creation of resources this way (with a provided ID). The Allow HTTP header must be set when returning a 405 to indicate the HTTP methods that are supported. In the previous case, the header would look like "Allow: GET, PUT, DELETE"
409 CONFLICT Whenever a resource conflict would be caused by fulfilling the request. Duplicate entries, such as trying to create two customers with the same information, and deleting root objects when cascade-delete is not supported are a couple of examples.
500 INTERNAL SERVER ERROR Never return this intentionally. The general catch-all error when the server-side throws an exception. Use this only for errors that the consumer cannot address from their end.
More Comprehensive HTTP Status Code from https://en.wikipedia.org/wiki/List_of_HTTP_status_codes
200 OK - Response to a successful GET, PUT, PATCH or DELETE. Can also be used for a POST that doesn't result in a creation.
201 Created - Response to a POST that results in a creation. Should be combined with a Location header pointing to the location of the new resource
204 No Content - Response to a successful request that won't be returning a body (like a DELETE request)
304 Not Modified - Used when HTTP caching headers are in play
400 Bad Request - The request is malformed, such as if the body does not parse
401 Unauthorized - When no or invalid authentication details are provided. Also useful to trigger an auth popup if the API is used from a browser
403 Forbidden - When authentication succeeded but authenticated user doesn't have access to the resource
404 Not Found - When a non-existent resource is requested
405 Method Not Allowed - When an HTTP method is being requested that isn't allowed for the authenticated user
409 Conflict - Indicates that the request could not be processed because of conflict in the request, such as an edit conflict between multiple simultaneous updates.
410 Gone - Indicates that the resource at this end point is no longer available. Useful as a blanket response for old API versions
415 Unsupported Media Type - If incorrect content type was provided as part of the request
422 Unprocessable Entity - Used for validation errors
429 Too Many Requests - When a request is rejected due to rate limiting
500 Internal Server Error - A generic error message, given when an unexpected condition was encountered and no more specific message is suitable.[60]
501 Not Implemented - The server either does not recognize the request method, or it lacks the ability to fulfill the request.
502 Bad Gateway - The server was acting as a gateway or proxy and received an invalid response from the upstream server.[62]
503 Service Unavailable
Miscellaneous
REST API Best practices
Where to put parameters?
Compare: 1. As part of the URL-path (i.e. /api/resource/parametervalue ) 2. As a query argument (i.e. /api/resource?parameter=value )
Designing a REST api by URI vs query string http://programmers.stackexchange.com/questions/270898/designing-a-rest-api-by-uri-vs-query-string
Reference
Books & Tutorials
Articles
Slides
Sub Topics
Security
HTTP Status Code
Examples
Last updated