Simple and Intuitive RESTful APIs

Introduction

Web services are purpose-built, custom web servers that support the needs of specific applications. Interaction with web-services is facilitated by Application Programming Interfaces (APIs) which are used by the client-side application. A web API is the gateway to any given web service – it listens to incoming client requests and sends the outgoing response to the client. Developers should aim to design web APIs that are easy to maintain, easy to extend, intuitive, and platform independent. The following article suggests some principles to keep in mind when designing RESTful APIs.

REST Method Guidelines

1. Use GET to retrieve representation of the resource identified by the request URL.
2. GET requests can be repeatedly executed and should not cause any side effects (e.g. no state changes allowed) on the resource identified by the URL.
3. Use PUT to add a new resource identified by the request URL. The request body must include a representation of a resource that needs to be stored.
4. Use PUT to update or replace an existing resource. If the resource already exists, PUT overwrites the resource state with the representation supplied in the request body.
5. Use POST to request creation of a new resource under a collection in request URL path. The POST response body is HTTP status 204 (empty) or HTTP status 201 (a representation of the resource created).
6. Use DELETE to completely remove the resource identified by that URL. After a successful DELETE request, the resource is no longer available. Subsequent GET requests on the resource must return HTTP status 404.
7. To partially update the state of an existing resource using a URL, use PATCH request and provide the requested updates in the request body. The PATCH response returns a representation of the resource identified by the URL once the requested changes are applied.

URL Path Guidelines

1. Forward slash separator (/) is used to represent hierarchical relationship.
2. Use Hyphen (-) to improve readability URLs are case-sensitive except for scheme and host components; prefer lowercase in the path.
3. Use a plural noun for collection names; it should reflect what the collection contains
4. Do not use CRUD function names in URLs e.g. DELETE /deleteUser/1234 is an anti-pattern.
5. The URL path segments are alphanumeric and follow camelCase convention.
6. The URL path segments are intuitive, unambiguous, and succinct.

Resource Representations Guidelines

1. Encode the resource representation as application/json except where standard media-type representations are available.
2. A collection within the resource representation is encoded as application/json with an array attribute (elements represent resources of the collection).
3. Date and time fields must be represented as strings and conform to RFC-3339 format.
4. If the service supports pagination for GET requests, the request must also accept limit parameter (maximum number of resources to return) and offset parameter (index in the result set).
5. Resource identifier field called “url” must be present in a server response which points to the absolute and canonical URL of the resource itself.
6. If another REST service is the source of truth for some data, that given data cannot be included in the resource representation (i.e. a given REST service cannot act as a proxy for another RESTful resource).
7. When returning an HTTP error code, it should conform to RFC-2616.

Security Guidelines

1. Use authentication and authorization (e.g. OAuth Open Authentication) to protect resources.
2. If a REST request contains sensitive and personally identifiable information (PII), it must be authenticated.
3. Authorization scopes required for access must be clearly defined for a REST request.
4. Do not allow content (when not intended) or PII leaks between users and server components.
5. Use HTTPS (secure channel) for authenticated REST requests.
6. A REST request cannot contain authentication, authorization, or PII in the URL.

Conclusion

Uniform programming language agnostic REST APIs that converge on a common set of guidelines will benefit the developers. They can focus on writing the server code that powers the web services rather than debating on whether to use HTTP POST or HTTP PUT or worrying about the intricacies of RESTful API design.