Having gone through in detail of various design guidelines in preceding sections, let's do a quick recap of the best practices as applicable to each of the key focus areas:
Focus area
Best practices
Resource
Expose only those resources that are required for implementing the business use case
Naming of resource must be nouns; avoid using verbs
Avoid using generic name for resources, rather be specific
Resource names may include hyphens; avoid using underscores and other punctuation
Limit the length of the resource URI not to exceed 2,000 characters
Child resource must limit the scope to respective parent
Resource representation
Specify the content type supported by consumers of the API
Avoid using multiple content type for a resource representation, JSON is becoming the de facto standard for content type, so avoid using XML
Include Content-Type header in the response
If the API supports multiple content types, recommend client to specify their preferred content type in the Accept Request Header
If the API supports multiple languages, recommend client to specify their preferred language in the Accept-Language Request Header
It is recommended to use the ISO-8601 format for representing the date and time in your RESTful APIs
Use pagination to avoid returning all the records in response when the result set is of large size and connect the paginated results using Link Header
When large datasets are requested, use relevant encoding such as GZIP compression for efficient usage of the available bandwidth
HTTP method
Avoid using idempotent HTTP methods for non-idempotent operation
Avoid using safe HTTP methods for non-safe operation
Use each HTTP method for its defined purpose
To modify the state of a resource, use the widely supported HTTP POST method
Restrict the DELETE operation on a collection of resources, if the result is expected to perform hard delete and unrecoverable
Use caching only for idempotent and safe HTTP methods
Use the relevant HTTP status code in the response to qualify the correct response status
Faults must be qualified with correct HTTP error status code
Avoid sending OK Status(200) in case of faults
Enforce clients to use X-RateLimit-Limit and X-RateLimit-Remaining headers to avoid overloading the service
Security
Whitelist allowable actions on an entity.
Mention only allowable action verbs such as GET/POST, so other actions even if triggered by client are denied.
Validate the input data against the interface contract specification and reject bad request.
Validate URL to protect from injection attacks.
Avoid encoding sensitive information in the URL. If the request/response involves sensitive data/personal identification information as classified by enterprise data security guidelines, use HTTPs for encrypting the communication. For APIs exposed outside the enterprise for third-party clients, implement robust authentication and authorization such as JWT or OAuth 2.0.
Documentation of API
The interface must be documented clearly, qualifying the request, response, errors, and metadata as relevant
Specify example of request and response for applicable business scenarios
Mentio the backward and forward compatibility of newer version of APIs
