This is a summary of best practices when creating or refactoring your APIs to be “REST-ful”. It is not meant to be an intellectual exercise, but rather a practical one.


  1. Follow REST standard best practices
  2. Follow consistent request/response format
  3. Provide adequate test coverage
  4. Provide adequate documentation
  5. Be secure
  6. Versioned

1. Follow REST standard best practices

There is plenty of documentation available on Google on what REST is. It is helpful if you think of APIs as a product. Like all good products, it has to look good, feel good, smell good, taste good and overall, make me feel better about myself after using it.

For example:

Good Api Better Api
getAllMyUsers GET /api/users

Examples of good API Signatures

Http Verb Entity: Users Entity: Receipts Notes
GET /api/users/{userid} /api/receipts  
POST /api/users /api/receipts  
PUT /api/users/{userid} /api/receipts/{receiptid}  
PATCH /api/users/{userid} /api/receipts/{receiptid}  
DELETE /api/users/{userid} /api/receipts/{receiptid}  

A good pattern for searches

  • /api/entity/filter or /api/entity/search
  • Send parameters via POST As your search/filter criteria expand, you add it as a new field in JSON Update your docs

Golden rules

  • Use the HTTP verbs as much as possible to indicate status.
  • Creating a resource should return a valid HTTP status Ex: code 201 (Created) or 409 (conflict) if resource already exists.
  • Able able to deduce the response based on the HTTP Status code.
  • Keep it simple and consistent.

2. Consistent request/response format

Although there are libraries that convert the database object to JSON and vice versa, do not dump the database object as a response.

Wrap every request and response into a standard JSON envelope.

This is the format used by Instagram - which does the trick.

    "meta": {
        "errors": [{
            "error_type": "OAuthException",
            "code": 400,
            "error_message": "..."
    "data": {
    "pagination": {

3. Test Coverage

What does adequate test coverage mean for that API mean? Every API must have accompanying unit tests. Ex: API exists to create user. The test must test

  • Positive case (perfect user creation)
  • Negative case (test for invalid input parameters)

4. Have documentation

The APIs will be consumed by other developers. A good documented API includes:

  • Clearly defines the method signature
  • An explanation of the request/response (what it does in a sentence or two)
  • Clearly defines all inputs, if any
  • Clearly define the input types (i.e. string, number, date…)
  • Error messages (what happens if wrong date of birth is passed in?)
  • A sample request/response

5. Security

In addition to validating API inputs for valid values, there must be a check to ensure the requestor of resource has adequate permissions.

  • Ex: Must have permission to create a user check before creating the user
  • Do this check as early as possbile in the API call to avoid unncessary processing.


There are 5 pillars for good APIs.

  1. Restful
  2. Consistent request/response format
  3. Test coverage
  4. Documentation
  5. Secure

APIs are a product created by technical people for other technical people.

A developer consuming your APIs will appreciate the thought and engineering you’ve put into your work, even if he/she cannot consciously discern it.

When in doubt, look to other popular SAAS products who also provide great APIs.

Some examples of great APIs.