As developers, we have all heard terms like REST APIs and RESTful APIs. But what do they actually mean?
Before REST, most developers had to deal with SOAP. With SOAP, integrating APIs meant manually writing an XML document with a Remote Procedure Call (RPC) inside, specifying the endpoint, and sending a POST request with the SOAP envelope to that endpoint.
SOAP was powerful but notoriously complex to build, use, and debug. Fortunately, Roy Fielding and a group of developers introduced REST, a paradigm that revolutionized the way we design and consume APIs.
Key Terminology
API (Application Programming Interface): A set of definitions and protocols for building and integrating applications. It acts like a contract between an information provider and an information consumer, ensuring both sides know what to expect in terms of requests and responses.
REST (Representational State Transfer): An architectural style defined by Roy Fielding that outlines principles for designing scalable and maintainable web services.
RESTful: Refers to APIs or systems that strictly follow all REST principles.
REST Principles
REST is not a protocol; it is a set of constraints and guidelines. A RESTful API should follow these principles:
1 – Client–Server Separation: the client (UI) and server (business logic) are independent. Communication happens through HTTP requests.
2 – Statelessness: the server does not store any client session information. Each request must contain all the data needed to process it.
3 – Cacheability Responses: must indicate whether they are cacheable
4 – Uniform Interface:Use consistent resource naming, standard HTTP methods, and self-descriptive messages.
5 – Layered System: The architecture can have multiple layers such as load balancers, proxies, or gateways, and each component only interacts with the layer directly above or below it.
6 – Code on Demand (Optional): The server can send executable code, such as JavaScript, to the client to extend functionality.
REST vs. RESTful
- REST: The architectural style and set of principles.
- RESTful: APIs that implement all of those principles in practice.
Example RESTful Endpoint Structure with HTTP Codes
In short:
REST is the theory.
RESTful is the practice.
Using standard HTTP status codes make REST APIs predictable and easier to work with.