Engineering notes / Backend engineering
Reliable APIs start at the boundary
A practical checklist for validation, predictable failures and safe retries across application boundaries.
Make the contract explicit
An API connects teams as well as systems. Define the request shape, response shape and failure behaviour together. Validate external input at the boundary, then keep business rules close to the domain they protect. Authentication identifies the caller; authorisation still needs to decide which operation that caller may perform.
Design the failure path
A timeout does not prove that an operation failed. The server may have completed the work before the response was lost. For operations with side effects, decide how duplicate requests are handled before adding retries. Use bounded timeouts, consistent error responses and enough operational context to investigate failures without logging confidential data.
Test beyond the happy path
Check invalid input, access restrictions, unavailable dependencies and repeated requests. Keep tests focused on observable behaviour rather than implementation details. A useful review question is whether a client can distinguish a validation problem from a temporary service failure and respond appropriately.