API as a long-term contract
In an enterprise environment, an API serves as a fundamental contract upon which the stability of all connected systems depends. Design should begin with the definition of business objects rather than simply replicating internal database table structures. Describing interfaces using Swagger 2.0 is the standard, allowing for documentation automation and machine-readable contracts.
Key design principles
Particular attention should be paid to backward compatibility. When making changes (e.g., adding new fields), it is essential to ensure that existing clients remain functional. Incompatible changes (such as deleting or renaming fields) must be accompanied by the release of a new API version via the URI (e.g., /v1/ to /v2/).
Ensuring data reliability
- Idempotency: To protect against network failures and duplicate requests (e.g., POST during order creation), the client should send a unique request identifier, which the server uses to check for previously executed operations.
- Optimistic locking: To prevent conflicts during concurrent resource editing, use HTTP If-Match headers with ETags, as per RFC 7232. If the resource version on the server does not match the one provided by the client, the server returns a 412 Precondition Failed status.
- Error handling: HTTP status codes must correspond to the business context (e.g., 409 Conflict when a state violation occurs). Using standardized error messages instead of system logs enables clients to respond correctly to failures.
Asynchronous operations should be implemented by returning a 202 Accepted status, allowing the client to poll for the execution result. Enterprise discipline in API management—through alignment with a business vocabulary and rigorous change control—ensures the system remains manageable throughout its entire lifecycle.
Author