Best practices for REST API design

A rough guide how to implement a REST API.

The discussion here Show archive.org snapshot includes some interesting points as well:

• Timestamps: ISO8601 format ("2021-02-22T20:34:53.686Z")
• Google API guideline: https://google.aip.dev/ Show archive.org snapshot
• Numbers: String vs. Number

  The JSON number type is not a double. It's just a number of arbitrary size and precision in integer/decimal/E format that can be parsed as whatever the parser finds fitting.

• Pagination: Limit + Offset vs. Object ID / Pointer vs. System-Version Tables
• Filter Attributes e.g. ?fields=f1,f2,f3
• Version in path (/api/v1/) or in header
• Microsoft API guideline: https://github.com/microsoft/api-guidelines/blob/vNext/Guidelines.md Show archive.org snapshot
• Zalando API guideline: https://opensource.zalando.com/restful-api-guidelines Show archive.org snapshot
• https://www.merixstudio.com/blog/best-practices-rest-api-development/ Show archive.org snapshot
• https://www.oreilly.com/library/view/rest-api-design/9781449317904/ Show archive.org snapshot

More topics in our deck:

• Rails: Rest API post-mortem analysis
• InfoQ: How to Design a Good API & Why it Matters