REST API Design Rulebook

REST API Design Rulebook

Disclaimer: The following content is a modified index of REST API Design Rulebook.

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 Types

• 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

Uniform Implementation

• Principle: A REST API should be designed, not coded
• Principle: Programmers and their organizations benefit from consistency

A poor man's lesson plan to Data Science

Basic

Data Structure & Algorithms (Coursera Part I : Princeton University, Coursera Part II : Princeton University)
Analysis of Algorithms (Coursera Stanford University, Coursera Princeton University)
Algorithm Design (Slides: Princeton University)

Statistics

Statistics : Making Sense of Data (Cousera Toronto University)
Probabilistic Graphical Models (Coursera Stanford University)

Data Mining/Data Science/Machine Learning

Introduction to Data Mining (Booksite, Instructor Solution Manual)
Introduction to Data Science (Coursera Washington University)
Core Concepts of Data Analysis (Coursera)
Machine Learning (Coursera Stanford University, Coursera Washington University)
Web Intelligence and Big Data (Coursera)
Introduction to Recommendar Systems (Coursera)

Technologies

Hadoop, Hive, R (http://bigdatauniversity.com/, http://www.statmethods.net/index.html)