REST APIs
A REST API (Representational State Transfer Application Programming Interface) is an architectural style for designing networked applications. It leverages standard HTTP methods to transfer representations of resource states between a client and a server, decoupling the two and enabling highly scalable, interoperable systems.
Core Concepts & Key Principles
To be considered RESTful, an API must adhere to six constraints defined by Roy Fielding:
- Statelessness – Every request from a client to a server must contain all of the context and information needed to understand and complete the request. The server does not store session state or context about the client.
- Client-Server Architecture – The client (user interface/frontend) and the server (data storage/backend) are decoupled, allowing them to evolve independently.
- Uniform Interface – Clients interact with resources through a standardised interface, which typically involves:
- Resource Identification: Resources are identified by stable URIs (e.g.,
/api/v1/users/123). - Manipulation of Resources through Representations: Clients modify resources by passing updated state representations (e.g., JSON or XML).
- Self-Descriptive Messages: Each message includes enough info to describe how to process it (e.g.,
Content-Type: application/json). - Hypermedia as the Engine of Application State (HATEOAS): Dynamically providing hyperlinks guiding client actions.
- Resource Identification: Resources are identified by stable URIs (e.g.,
- Cacheability – Responses must define themselves as cacheable or non-cacheable to improve network efficiency and reduce server load.
- Layered System – Clients cannot tell whether they are connected directly to the end server or to an intermediate (e.g., load balancer, CDN, or security gateway).
- Code on Demand (Optional) – Servers can temporarily extend client functionality by transferring executable code (e.g., scripts).
REST HTTP Methods Map
| HTTP Method | CRUD Action | Idempotent | Safe | Description |
|---|---|---|---|---|
GET | Read | Yes | Yes | Retrieves representation of the resource. |
POST | Create | No | No | Creates a new resource or triggers controller-like side-effects. |
PUT | Update/Replace | Yes | No | Replaces the target resource or creates it if not present. |
PATCH | Update/Modify | No | No | Applies partial modifications to a resource. |
DELETE | Delete | Yes | No | Deletes the specified resource. |
REST Stateless Communication Flow
Strategic Utility (Why CTOs Should Care)
For technology leaders, standardising on REST APIs influences integration speed, developer experience, and long-term operating costs:
- Optimising Developer Experience (DX): Because REST relies on standard HTTP methods and status codes, onboarding new engineers or external integration partners is simple. There is no need for specialised client SDK generators as required by RPC frameworks.
- Simplifying Operations & Scalability: The stateless nature of REST allows API servers to scale horizontally without complex sticky sessions or shared-state memory replication.
- System Decoupling and Lifetime Value: Strong client-server separation means that you can rewrite backend systems or migrate databases without impacting existing client applications, as long as the resource URIs and payloads remain stable (see Hyrum's Law).
- Hybrid API Strategies: Standardising on REST for public-facing/third-party developer APIs provides maximum compatibility, even if you utilise gRPC or GraphQL for internal microservice communication.
Explore Next
- HATEOAS — Hypermedia As The Engine Of Application State constraints.
- Hyrum's Law — API scaling and client dependency behaviours.
- C4 Diagrams — Documenting software architecture and API layers.
- OSI Model — How REST operates at the Application Layer (Layer 7).
- Event-Driven Architecture — The asynchronous alternative/complement to request-response REST APIs.
References
- Slack Web API Reference — An example of a SaaS communication platform API. It utilises standard endpoints, token-based authentication, and structured JSON payloads to manage channels, users, and messaging features.
- SendGrid Web API v3 — A high-throughput transactional utility API. It showcases clean resource-oriented endpoints for mail delivery, contact management, and analytics dashboard integrations.
- Cloudflare API — An infrastructure and edge network management API. It demonstrates how complex cloud networking, DNS management, and CDN rules can be modelled as standard REST resources.
- Toast POS OpenAPI Reference — A vertical SaaS restaurant-tech API. Standardised using the OpenAPI specification, it shows how complex physical-world entities (menus, tables, orders, payments) are represented and manipulated via REST.
- MongoDB Atlas Admin API v2 — A database-as-a-service administrative API. It models cluster deployments, database users, security configurations, and cloud projects as manageable REST resources.