List of RFCs affecting and around HTTP:
Building Blocks for HTTP APIs Working Group Home Page
HTTP Toolkit (Sources): a beautiful & open-source tool for debugging, testing and building with HTTP(S) on Windows, Linux & Mac. Docs
/users/{id}
, /orders/{id}
or /user/{id}
, /order/{id}
Api-Key
for passing an API keyMake an exception for public endpoints: Every endpoint should require authorization by default. Most endpoints require an authenticated user to be called, so making this the default makes sense. If an endpoint needs to be called publicly, explicitly set this endpoint to allow unauthorized requests.
Provide a health check endpoint: Provide an endpoint (for example GET /health) that determines whether or not a service is healthy. This endpoint can be called by other applications such as load balancers to act in case of a service outage.
Version the API: Make sure you version your API and pass the version on each request so that consumers aren't affected by any changes to another version. API versions can be passed using HTTP headers or query/path parameters. Even the first version of the API (1.0) should be explicitly versioned.
https://api.averagecompany.com/v1/health
https://api.averagecompany.com/health?api_version=1.0
Accept API key authentication: If an API needs to be called by a third party, it makes sense to allow authentication via API keys. API keys should be passed using a custom HTTP header (such as Api-Key). They should have an expiration date, and it must be possible to revoke active keys so that they can be invalidated in case they get compromised. Avoid checking API keys into source control (use environment variables instead).
Use reasonable HTTP status codes: Use conventional HTTP status codes to indicate the success or failure of a request. Don't use too many, and use the same status codes for the same outcomes across the API. Some examples:
Use reasonable HTTP methods
Use self-explanatory, simple names
Use standardized error responses
Return created resources upon POST
Prefer PATCH over PUT: As mentioned earlier, PATCH requests should apply partial updates to a resource, whereas PUT replaces an existing resource entirely. It's usually a good idea to design updates around PATCH requests, because:
Be as specific as possible
Use pagination
Allow expanding resources: Allow consumers to load related data using a query parameter called expand (or similar). This is especially useful to avoid round-trips and load all data that is necessary for a specific action in one go.
Last modified 09 December 2024