Rest API Design guidelines and best practices

When designing an api you should think about

  • naming
  • Proper http verbs and response codes for different CRUD operations
  • Think about versioning.

General guidelines to keep in mind:

-> Always prefer to use lowercase characters in uri’s. A forward slash should be used to indicate a hierarchical relationship. Also a trailing forward slash should be not be included. Hyphens (-) can be used for better readability but underscores ( _ ) should not be used.

Note: File extensions like ‘json’ or ‘xml’ should not be used to indicate a format preference. You should look at the ‘Content-Type’ header to determine how to process the body’s content.

-> The uri path should convey the resource model with each segment path identifying an addressable resource.

-> The actual words in the path should either be a singular ,plural  noun or a verb.

Note: Do not use CRUD function names in the uri’s. You can use the query component of the uri for pagination.


-> GET and POST must not be used to tunnel other request methods

->  POST must be used to execute controllers

-> HEAD should be used to retrieve response headers

Response Codes:

200 (OK) Non-specific Success.Must not be used to communicate errors in response body.
201 (OK) Successful resource creation.
204 (No content) Used when response body is intentionally empty
301(“Moved Permanently”) Should be used to relocate resources
302 (“Found”) Should not be used
303 (“See Other”) Should be used to refer the client to a different URI
307 (“Temporary Redirect”) Should be used to tell clients to resubmit the request to another URI
400 (“Bad Request”) Used to indicate nonspecific failure
401 (“Unauthorized”) Used when there is a problem with the client’s credentials
403 (“Forbidden”) Used to forbid access regardless of authorization state
404 (“Not Found”) Used when a client’s URI cannot be mapped to a resource
405 (“Method Not Allowed”) Used when the HTTP method is not supported
406 (“Not Acceptable”) Used when the requested media type cannot be served
415 (“Unsupported Media Type”) Used when the media type of a request’s payload cannot be processed
500 (“Internal Server Error”) Used to indicate API malfunction

HTTP Headers:

-> Content-Type, Content-Length should be used

Note: Cache-Control, Expires, and Date response headers should be used to encourage caching.Expiration caching headers should be used with 200 (“OK”) responses

-> Custom HTTP headers must not be used to change the behavior of HTTP methods

Error Representation

A consistent form should be used to represent errors and error responses.Consistent error types should be used for common error conditions.


Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out /  Change )

Google photo

You are commenting using your Google account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s