I’m learning about REST and had the chance to build a basic REST API. After doing so, most of the material I read was internalized and I now have a better understanding of it.
However, I do not see any real difference yet as to the tangible benefits of using REST over the old way I was doing things, which was simple URL query strings. It seems they both do the exact same things. But with REST, it’s cleaner, and standardized.
I thought REST had additional technical benefits. If they do, what are they? Or is REST simply that – an agreed way to implement and API?
2
There are no additional technical benefits. Many people simply think using a RESTful style makes for a cleaner interface. If nothing else, consumers can usually make inferences about how a RESTful API works (GET to fetch data, PUT and POST to create or save data, DELETE to delete, etc), whereas with random query strings they have to read the documentation a bit more closely.
1
REST has many technical benefits, and it’s not just about “style”. It’s an architecture, a way of thinking, that has many benefits over an rpc-style architecture. REST is also MUCH more than just a URI scheme.
REST provides 5 “constraints” that help guide toward a good API:
1. Client–server
Self-explanatory and already the nature of web apps.
2. Stateless
Statelessness means that state is maintained on the client. This makes every request/response transaction independent. Benefits are:
Stateless communications enable clients to recover from network errors.
Clients and servers can come and go without corrupting state.
New processing nodes can be attached without complex state management.
3. Cacheable
Cache control at multiple levels (client, server, intermediary) – because state exists in only one place. For obvious reasons caching at multiple levels decreases latency, bandwidth, and cost.
4. Layered system
Limits complexity at each layer. Also improves security because security can be implemented at multiple levels.
5. Uniform interface
Resources are identified by URIs. These URI’s serve as an abstraction and should not change often. Representations are representations of a resource to the client based on a negotiation. Control Data is what negotiates the representations and actions. Hypermedia protects the server from being locked into a uri scheme.
All of these are part of REST. It’s much more than a URI scheme.
REST is not about functionality, but about style. The idea behind it is not that it allows anything new but that it makes the API easier for people to learn and understand, and that it also makes for shorter, more readable URLs.
The other thing to keep in mind is that REST doesn’t mean “no query parameters”. The idea is that in most APIs, a lot of the information is by nature hierarchical and so for that information, why not use the hierarchical structure inherent in an URL? It makes the hierarchy explicit and this in turn often makes for more an API that is more flexible. (Because it makes the developer think in hierarchical terms.) Too often APIs based on parameters end up being an unholy mass of poorly organized options.
This is a “tangible benefit”. Good coding style in any domain can have direct impact in productivity and defect reduction. Clear, consistent style in an API is especially important because an API is something that many developers will use, and something intended for use by the people who did not design and code the software.