Many people describe their HTTP APIs as REST or RESTful, but almost 100% of the time these APIs are not REST. I have made the same mistake in the past, so some clarification is necessary.
What is REST?
REST is an architectural style defined by Roy Fielding in his doctoral dissertation which defines a very specific set of constraints for distributed systems: client-server; statelessness; cacheability; layered system; (optional) code-on-demand; and a uniform interface between components with the following requirements:
- identification of resources
- manipulation of resources through representations
- self-descriptive messages
- hypermedia as the engine of application state (HATEOAS)
HTTP is not a requirement for REST, but maps very well to it. So what happened over time is that people started building HTTP APIs and calling them REST or RESTful. The Richardson Maturity Model was developed to lay a path for evolving your API towards a real REST API.
But in real life most people never implemented all the requirements necessary for their APIs to be REST—specially HATEOAS—because it is a lot of work and there is a lack of tooling. I don’t know many examples of true REST APIs including HATEOAS, and I only know of one production quality library to make it easier, Spring HATEOAS.
Does this matter so much?
I think it’s important to call things by their right name.
Also, it is not a sin to not be RESTful. REST is not the only or ultimate architectural style, it has drawbacks.
Finally, when Roy Fielding, creator of REST, has said don’t call it REST unless it adheres to all the constraints necessary to be called REST—specially HATEOAS—, there is no point in arguing.
What to call it then
HTTP API. Most real life examples I see are simply RPC-style HTTP APIs. A popular style is the OpenAPI specification (formerly Swagger). Notice that it doesn’t mention REST once.
Orlando Ramírez 