14 Adapting the API design to the context
- Challenging or dealing with provider and consumer constraints
- Downloading and uploading files
- Notifying consumers about provider-sourced events with a webhook
- Handling long operations with polling and callbacks
- Considering other API types
Although they both measure time, an everyday watch does not have the same design as a deep-diving watch that’s used under high pressure by a person wearing bulky gloves. An everyday object’s design must consider various contextual factors to be entirely effective; the same goes for APIs. If the partners using the Shopping API need to be aware of any product price modifications in real time, requiring them to read all products every second to get up-to-date prices is likely not the best design option.
14.1 Integrating context into the API design
14.1.1 How context can affect the design of an API
14.1.2 Seeking constraints and limitations during design
14.1.3 Challenging constraints and limitations
14.1.4 Making trade-offs
14.2 Dealing with consumer and provider constraints
14.2.1 Working around consumer HTTP method limitations
14.2.2 Accommodating consumers who are used to different data formats
14.2.3 Managing planned interruptions
14.2.4 Ensuring data and URL compatibility
14.2.5 Implementing partial updates
14.3 Handling data and files
14.3.1 Collecting data and files in a flow
14.3.2 Sending data and files with a single call
14.3.3 Retrieving data and files with a single call
14.3.4 Describing files with OpenAPI
14.3.5 Describing mixed data and files with OpenAPI
14.4 Providing efficient file management features
14.4.1 Returning file data only when necessary
14.4.2 Enabling partial downloads and uploads
14.4.3 Preventing unnecessary uploads
14.5 Delegating file downloads and uploads
Summary