What exactly does a REST API do?
A REST API is the boundary between a client and the backend that manages data and business rules. A mobile app or web interface sends a request such as “retrieve the order” or “approve the service record”; the API checks identity and permission, runs the rule and returns a predictable response.
| HTTP method | Typical purpose | Example resource operation |
|---|---|---|
| GET | Read data | Retrieve the order list |
| POST | Start a new transaction | Create a new order |
| PUT / PATCH | Change existing data | Update the delivery address |
| DELETE | Delete or deactivate a resource | Remove a draft record |
A REST API is not the same as a backend
The backend is the entire server side: database, business rules, scheduled jobs, queues, file storage and integrations. A REST API is its outward-facing contract. The same backend may expose a REST API to a mobile app, a queue to internal jobs and event messages to other services.
The 6 core decisions behind a reliable API
Endpoint count does not determine API quality; consistent behaviour does. Documenting these 6 decisions before development lets mobile, web and backend teams work against the same contract.
| Decision | Question to answer | Expected output |
|---|---|---|
| 1. Resource model | Which entities do URLs represent? | Consistent naming and relationships |
| 2. Validation and errors | How is an invalid request explained? | Stable field-level error format |
| 3. Identity and authorization | Who can perform which action on which record? | Role and ownership matrix |
| 4. Versioning | How are breaking changes released? | Migration plan that protects old clients |
| 5. Idempotency | What if the same request arrives twice? | Prevention of duplicate payments or records |
| 6. Observability | Which request caused a failure? | Request ID, logs and metrics |
Why are error responses part of the contract?
Clients do not operate only on successful responses. Lost connectivity, expired sessions, invalid fields, rate limits and third-party failures need different user-facing paths. If every endpoint returns a different error shape, interface code branches and real problems collapse into a generic “something went wrong” message.
- Include a traceable request ID in every response.
- Separate user-facing messages from technical log detail.
- Return field validation errors with the relevant field name.
- Do not confuse authentication, authorization and not-found states.
- Define timeouts and retry limits for third-party failures.
Security is more than a login screen
API security requires checking identity, authorization, data scope and rate limits on every request. A signed-in user is not automatically allowed to see another user's record. Resource ownership must be verified on the server, and secret keys must never be placed in a mobile or web client.
What documentation belongs in an API handoff?
A deliverable API includes machine-readable endpoint definitions, example requests and responses, the identity flow, an error catalogue and local setup steps alongside working code. A new developer should be able to send the first request without an oral handover.