REST API fundamentals for BAs

The idea

An API requirement describes more than an endpoint. Capture consumer and provider, purpose, method and resource, request and response fields, authentication, validation, error codes, retries, idempotency, ownership and observability. Confirm what happens when an external service is slow or unavailable.

Example

POST /orders should define required fields, what a duplicate request does, what 400/401/409/503 mean, and whether a failed payment leaves an order in a recoverable state.

Illustrative BA scenario

Fictional payment integration: map the provider's transaction ID to the merchant order ID, specify timeout behaviour and reconciliation, and test duplicate callbacks before launch.

Try it yourself

1. List missing questions for a payment-provider API.
2. Define a success response and two failure responses.