UP | HOME

REST Api

Table of Contents

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 Guidelines

  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

2 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.

2.1 For example:

Good Api Better Api
getAllMyUsers GET /api/users

2.1.1 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}  

2.1.2 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

2.1.3 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.

3 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": {
       ...
    }
}

4 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)

5 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

6 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.

7 Summary

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.