-
Describe API with OpenAPI spec See OpenAI example: https://github.com/openai/openai-openapi/blob/master/openapi.yaml
-
Generate client code with Stainless: https://www.stainlessapi.com/ See OpenAI client: https://github.com/openai/openai-python
REST API design
Great design / best practices
https://github.com/stickfigure/blog/wiki/How-to-%28and-how-not-to%29-design-REST-APIs
Good design principles
- Consistency
- All about resources
- IDs and Types
- Resource Names
- HTTP and JSON standards
- Completeness (Advice against HATEOAS links, but for completeness in being able to traverse the API ) https://link.medium.com/IPK3NQotbwb
Good principles, XML, HATEOAS
https://restfulapi.net/rest-api-design-tutorial-with-example/
JSON, best practices
https://docs.microsoft.com/en-us/azure/architecture/best-practices/api-design
JSON Patch
https://zuplo.com/blog/2024/10/10/unlocking-the-power-of-json-patch
43 principles for good API design
https://mathieu.fenniak.net/the-api-checklist/
Correct use of HTTP methods
https://link.medium.com/MmKCrdmybwb
HTTP status codes
https://en.m.wikipedia.org/wiki/List_of_HTTP_status_codes
https://link.medium.com/CpdpwmBybwb
Pagination
- prefer cursor-based to offset-based https://slack.engineering/evolving-api-pagination-at-slack/
Conditional HTTP requests
- caching with Etag and/or Last-Modified
- optimistic locking with Etag + If-Match
- limit upsert operations (PUT)
https://quadratic.fm/p/how-meta-microsoft-google-github
Simplistic advice, ok-ish
https://stackoverflow.blog/2020/03/02/best-practices-for-rest-api-design/
Standards
JSON
https://www.ecma-international.org/publications-and-standards/standards/ecma-404/
HTTP
core / semantics
https://httpwg.org/specs/rfc9110.html#RFC5789
HTTP
https://www.rfc-editor.org/rfc/rfc2616
HTTP, PATCH method
https://www.rfc-editor.org/rfc/rfc5789.html
Security
Common security issues
https://owasp.org/API-Security/editions/2023/en/0x11-t10/