Simple and Intuitive RESTful APIs by@rohantiwari
394 reads
394 reads

Simple and Intuitive RESTful APIs

by Rohan TiwariSeptember 25th, 2021
Read on Terminal Reader
Read this story w/o Javascript
tldt arrow

Too Long; Didn't Read

REST is a very popular architecture choice for building web servers and RESTful APIs provide a flexible and extensive way to integrate applications. Well-designed RESTful APIs makes the life of engineers very easy. This article describes some best practices to design simple, intuitive RESTful APIs that are easy to maintain and use.

Companies Mentioned

Mention Thumbnail
Mention Thumbnail
featured image - Simple and Intuitive RESTful APIs
Rohan Tiwari HackerNoon profile picture


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.


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.