REST API Design

Copyright

All the contents are from the book "REST API Design Rulebook" . All rights reserved by the author and publisher

General concepts

KISS

• Anyone should be able to use your API without having to refer to the documentaTon.
• Use standard, concrete and shared terms, not your specific business terms or acronyms.
• Never allow application developers to do things more than one way.
• Design your API for your clients (Application developers), not for your data.
• Target major uses cases first, deal with exceptions later.

CURL

You should use CURL to share examples, which can be easily copy/paste.

Medium grained resources

You should use medium grained, not fine nor coarse. Resources shouldn’t be nested more than two level deep

Design Rules

URI Format

• Forward slash separator (/) must be used to indicate a hierarchical relationship
• A trailing forward slash (/) should not be included in URIs
• Hyphens (-) should be used to improve the readability of URIs
• Underscores (_) should not be used in URIs
• Lowercase letters should be preferred in URI paths
• File extensions should not be included in URIs

URI Path Design

• A singular noun should be used for document names
• A plural noun should be used for collection names
• A plural noun should be used for store names
• A verb or verb phrase should be used for controller names
• Variable path segments may be substituted with identity-based values
• CRUD function names should not be used in URIs

URI Query Design

• The query component of a URI may be used to filter collections or stores
• The query component of a URI should be used to paginate collection or store results

Request Methods

• GET and POST must not be used to tunnel other request methods
• GET must be used to retrieve a representation of a resource
• HEAD should be used to retrieve response headers
• PUT must be used to both insert and update a stored resource
• PUT must be used to update mutable resources
• POST must be used to create a new resource in a collection
• POST must be used to execute controllers
• DELETE must be used to remove a resource from its parent
• OPTIONS should be used to retrieve metadata that describes a resource’s available interactions

Response Status Codes

• 200 (“OK”) should be used to indicate nonspecific success
• 200 (“OK”) must not be used to communicate errors in the response body
• 201 (“Created”) must be used to indicate successful resource creation
• 202 (“Accepted”) must be used to indicate successful start of an asynchronous action
• 204 (“No Content”) should be used when the response body is intentionally empty
• 401 (“Unauthorized”) must be used when there is a problem with the client’s credentials
• 403 (“Forbidden”) should be used to forbid access regardless of authorization state
• 404 (“Not Found”) must be used when a client’s URI cannot be mapped to a resource. This also means when the request to search or get details of an entity, like say /user/100
• 409 (“Conflict”) should be used to indicate a violation of resource state
• 412 (“Precondition Failed”) should be used to support conditional operations
• 500 (“Internal Server Error”) should be used to indicate API malfunction

HTTP Headers

• Content-Type must be used
• Content-Length should be used
• Last-Modified should be used in responses
• ETag should be used in responses
• Stores must support conditional PUT requests
• Location must be used to specify the URI of a newly created resource
• Cache-Control, Expires, and Date response headers should be used to encourage caching
• Cache-Control, Expires, and Pragma response headers may be used to discourage caching
• Caching should be encouraged
• Expiration caching headers should be used with 200 (“OK”) responses
• Expiration caching headers may optionally be used with 3xx and 4xx responses
• Custom HTTP headers must not be used to change the behavior of HTTP methods

Error Representation

• A consistent form should be used to represent errors
• A consistent form should be used to represent error responses
• Consistent error types should be used for common error conditions

Versioning

• New URIs should be used to introduce new concepts

Security

• OAuth may be used to protect resources
• API management solutions may be used to protect resources

JavaScript Clients

• JSONP should be supported to provide multi-origin read access from JavaScript
• CORS should be supported to provide multi-origin read/write access from JavaScript

References

http://blog.octo.com/wp-content/uploads/2014/10/RESTful-API-design-OCTO-Quick-Reference-Card-2.2.pdf