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.
Questions
- Which programming language should a REST API use?
- Choose based on team experience and system requirements. .NET, Node.js and Python can implement the same REST principles. Long-term quality depends more on the data model, error contract, test coverage and observability than on the language name.
- What is the difference between REST API and GraphQL?
- REST focuses on resources and standard HTTP behaviour; GraphQL lets a client select the fields it needs through one query language. REST may be simpler for stable, explicit workflows, while GraphQL is worth evaluating when many clients need substantially different data shapes.
- How do you test a REST API?
- Test at least three layers: unit tests for business rules, integration tests with the database and dependencies, and end-to-end or contract tests that protect client expectations. Unauthorized access, retries and third-party failures matter as much as happy paths.