HTTP

HTTP API implementation quick guide

Request design

Use resource name paths (nouns, not verbs)
Use plural resource name paths
Use only two base URL paths per resource: collection and element in collection
Use standard HTTP method verbs to operate on collections and elements
Use custom methods only for functionality that cannot be easily expressed via the standard methods
Use versioned paths
Use idempotent POST and PUT methods
Use a unique identifier with every request
Use pagination with size and token query parameters
Use a rate limiter
Use size limiters and message validators
Use a separate domain or sub-domain

Response design

Use HTTP status codes
Use descriptive error responses (do not include sensitive information)
Use alerting for 5xx errors

Timeline

1997 Roy Fielding, T. Berners-Lee et al.: RFC2068: Hypertext Transfer Protocol – HTTP/1.1
2000 Roy Fielding: Architectural Styles and the Design of Network-based Software Architectures
2007 Leonard Richardson, Sam Ruby: RESTful Web Services
2007 Open Data Protocol (OData)
2008 Roy Fielding: REST APIs must be hypertext-driven
2012 Joshua Bloch: How To Design A Good API and Why it Matters
2012 Restful Objects
2014 Roy Fielding et al.: RFC7231: Hypertext Transfer Protocol (HTTP/1.1): Semantics and Content
2015 Google, Mozilla: RFC7540: Hypertext Transfer Protocol Version 2 (HTTP/2)
2017 Roy Fielding et al.: Reflections on the REST architectural style and “principled design of the modern web architecture”
2018 Ole Begemann: Roy Fielding’s REST dissertation
2020 Google: AIPs
2020 Sinclair Target: Roy Fielding’s Misappropriated REST Dissertation
2020 Mike Amundsen: Design and Build Great Web APIs
2021 JJ Geewax: API Design Patterns (book)
2021 Michael Scharhag: Making POST and PATCH requests idempotent
2023 Mike Bishop: RFC9114: HTTP/3
2023 Alex Xu: ByteByteGo: Design effective and safe APIs
2023 Joshua Stein: Advice for Operating a Public-Facing API
2023 Carson Gross et al.: Hypermedia Systems

Misc