API Design¶

"An API is like a bady: it's fun to make, but you have to support it for 18 years."

- Ty Smith, Mobile Tech Lead Manager, Uber

API Documentation¶

Open API for synchronous REST APIs.

Asynchro API for message-driven architectures.

WSDL for SOAP Web Services.

Approaches for versioning of REST API:

URL path

https://api.example.org/api/v1/orders
https://api.example.org/api/v2/orders

Media types

Accept: application/vnd.my-api.v2+json
Accept: application/vnd.my-api+json;version=2

Query parameters

https://api.example.org/api/orders?version=2

Design your API very thoroughly before releasing the first version.
Prioritize using Contract-First development and complement it with standard API documentation to describe the API.
Try to maintain backward compatibility as long as possible.
Consider to create a new api or version when a breaking change is made.
Document the used versioning strategy.
Don't forget to notify your API consumers for any changes.