HTTP
This section outlines best practices for communicating efficiently with a server, from design to integration.
General guidelines
Do send as few requests as possible.
- ❌ Send requests in a loop.
Sending too much requests can lead to performance issues. Consider redesigning your API and aim for a single request that retrieves all the necessary data.
Avoid sequential requests.
Sequential requests can lead to performance issues and increased latency. Consider redesigning your API into a single request, or parallel requests.
Do send as little data as possible in responses.
- ❌ Fetch a collection for just one item.
- ❌ Send a complete object but use only its id and name.
- ✅ Send only useful data.
Sending too much data can lead to performance issues, increased bandwidth usage and slower response times. This is particularly true for low-end and mobile devices, or if your application is used in a location with poor network coverage. Remember to use paging, filtering and selecting the minimum required fields.
Going further
Jump into details in the following sections.
API specification
An API specification is a language-agnostic contract that define how a client and a server communicate.
API design
This section gives you best practices for designing an API with clear naming conventions and data modeling strategies.
Error handling
Do use a generic error response model.