What is a RESTful API?
A RESTful API is an acronym for Representational State Transfer. REST is an architectural style which defines a set of architectural constraints for stateless communication between Application Programming Interfaces, or APIs. It is not a standard, so it allows developers some flexibility, but it acts as a mediator between users, clients, and resources. Then SOAP vs REST, what is the main difference? REST has become ubiquitous in API programming because it emphasizes scalability and greater interoperability, while its predecessor SOAP was a highly-structured protocol that required XML.
Why REST?
REST offers a number of constraints that make life easier for developers while still providing functionality and security.
- Uniform interface. If you've ever had to order a special dongle for that one piece of hardware without a USB connector, you understand the problem that RESTful APIs solve. Imagine that same problem, but on internet scale: thousands of websites talk constantly to each other, but without a translator in between. RESTful APIs act as connectors between all these clients and servers, with a standardized contract between them.
- Client-server architecture. In a REST API, a request is issued by a client to a server. A client makes a request to an API at an endpoint which it has access to. The API validates the request and passes the request to the destination server or program. The server sends a response back, first through the API, which then transfers it back to the client. This decoupling and authentication provides security.
- Statelessness. Servers don't have to store state information, and at high volume, this is a key feature of API design.
- Cacheability. A cache is a place in a network where frequently accessed data can be stored to improve load times. Optimizing the network using caching improves the overall quality-of-service by reducing bandwidth, reducing latency, reducing load on servers, and hiding network failures.
- Layered system. Developers can add load balancers or proxies between clients and servers, and it doesn't require changes on either side. Security layers can also be added.
- Code on demand. Servers can execute code on the client side to improve functionality.
REST Contracts
At the heart of RESTful APIs is the contract between client and server. This contract defines what the API will do and what kind of requests and responses it will issue. In some ways it is the machine and human readable documentation of the API. If you call the API, you must do so in a way that it understands, and you must be able to accept its responses, also. An example of an API contract can be seen here. You can see the APIs URLs, verbs, HTTP responses, and contract statuses- all the rules of interacting with this API are defined in the contract.
For more on contracts, check out the Open API spec.
Conclusion
RESTful APIs solved a lot of problems from the early days of the internet, and contributed to the explosion in web and cloud-native development. They offer uniform interfaces, security by authentication, and statelessness to developers looking to solve problems quickly.
