Thursday, July 25, 2013

REST API Design Rules

Found REST API Design Rulebook to be a useful guideline in designing REST APIs, and it's short n sweet with only 144 pages.



It has dished out a set of clear rules that are practical and easy to follow. Here is a summarized list of all the rules given in the book.

Identifier Design with URIs

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

URI Authority Design
Rule: Consistent subdomain names should be used for your APIs
Rule: Consistent subdomain names should be used for your client developer portal

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

URI Query Design
Rule: The query component of a URI may be used to filter collections or stores
Rule: The query component of a URI should be used to paginate collection or store results

Interaction Design with HTTP

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

Response Status Codes
Rule: 200 (“OK”) should be used to indicate nonspecific success
Rule: 200 (“OK”) must not be used to communicate errors in the response body
Rule: 201 (“Created”) must be used to indicate successful resource creation
Rule: 202 (“Accepted”) must be used to indicate successful start of an asynchronous action
Rule: 204 (“No Content”) should be used when the response body is intentionally empty
Rule: 301 (“Moved Permanently”) should be used to relocate resources
Rule: 302 (“Found”) should not be used
Rule: 303 (“See Other”) should be used to refer the client to a different URI
Rule: 304 (“Not Modified”) should be used to preserve bandwidth
Rule: 307 (“Temporary Redirect”) should be used to tell clients to resubmit the request to another URI
Rule: 400 (“Bad Request”) may be used to indicate nonspecific failure
Rule: 401 (“Unauthorized”) must be used when there is a problem with the client’s credentials
Rule: 403 (“Forbidden”) should be used to forbid access regardless of authorization state
Rule: 404 (“Not Found”) must be used when a client’s URI cannot be mapped to a resource
Rule: 405 (“Method Not Allowed”) must be used when the HTTP method is not supported
Rule: 406 (“Not Acceptable”) must be used when the requested media type cannot be served
Rule: 409 (“Conflict”) should be used to indicate a violation of resource state
Rule: 412 (“Precondition Failed”) should be used to support conditional operations
Rule: 415 (“Unsupported Media Type”) must be used when the media type of a request’s payload cannot be processed
Rule: 500 (“Internal Server Error”) should be used to indicate API malfunction

Metadata Design

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

Media Type Design
Rule: Application-specific media types should be used
Rule: Media type negotiation should be supported when multiple representations are available
Rule: Media type selection using a query parameter may be supported

Representation Design

Message Body Format
Rule: JSON should be supported for resource representation
Rule: JSON must be well-formed
Rule: XML and other formats may optionally be used for resource representation
Rule: Additional envelopes must not be created

Hypermedia Representation
Rule: A consistent form should be used to represent links
Rule: A consistent form should be used to represent link relations
Rule: A consistent form should be used to advertise links
Rule: A self link should be included in response message body representations
Rule: Minimize the number of advertised “entry point” API URIs
Rule: Links should be used to advertise a resource’s available actions in a state-sensitive manner

Media Type Representation
Rule: A consistent form should be used to represent media type formats
Rule: A consistent form should be used to represent media type schemas

Error Representation
Rule: A consistent form should be used to represent errors
Rule: A consistent form should be used to represent error responses
Rule: Consistent error types should be used for common error conditions

Client Concerns

Versioning
Rule: New URIs should be used to introduce new concepts
Rule: Schemas should be used to manage representational form versions
Rule: Entity tags should be used to manage representational state versions

Security
Rule: OAuth may be used to protect resources
Rule: API management solutions may be used to protect resources

Response Representation Composition
Rule: The query component of a URI should be used to support partial responses
Rule: The query component of a URI should be used to embed linked resources

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

No comments:

Post a Comment