HomeToolsAbout a20k

API Design

Versioning

/api/v1/resource_name

Deprecated

Should return 410 Gone HTTP Status Code to indicate that the new endpoint is not supported and should not redirect

  • Alternatively, if a new API endpoint is backwards-compatible, you can redirect to the new endpoint
/api/v2.2/customers/1234 >>> /api/customers/1234
/api/v2.0/customers/1234
/api/v2/customers/1234
/api/v1.1/customers/1234
/api/v1/customers/1234

Simple is better

api/products/12345
  • Easy to learn/use
  • hard to misuse
  • fails fast
  • good names (self-explanatory)
  • split into modules
  • when in doubt, leave it out (easy to add, hard to remove)
  • maximize info hiding. don't let info leaks in logs/exceptions
  • minimize coupling between APIs
  • document as many details as possible
  • keep performance in mind while designing API
  • It is always good practice to keep backward compatibility so the customers can get enough time to move to the next version when the  API version changes
  • Pagination
    • Use of pagination is a must when you expose an API which might return huge data and if proper load balancing is not done
    • Without pagination, one customer might end up bringing down the entire service
  • Proper Error Message
    • Always good practice to keep set of error messages application sends and responds with proper corresponding id
    • Alternative is to return a URL with error message which tells you more about the error message and how to handle it as well
// facebook's API Error messages
{
  "error": {
    "message": "(#803) Some of the aliases you requested do not exist: products",
    "type": "OAuthException",
    "code": 803,
    "fbtrace_id": "FOXX2AhLh80"
  }
}

Return Format

Most of modern day APIs should return JSON response

  • Open API standard allows you to design your APIs first and share that with the consumer in an easy manner
    • https://swagger.io/resources/open-api/

Bulk API Operation

Use POST or PATCH with list payload

POST /group/users
X-Action: renumbering
[
    { "id": "userId1", "sequence": "newSequenceNumber1" },
    { "id": "userId2", "sequence": "newSequenceNumber2" },
    (...)
]
© VincentVanKoh