What is a ReST API
First of all, I want to clarify some misconceptions:
1) REST is not a standard for web APIs, nor is it a pattern for naming resources.
2) REST is not coupled to HTTP.
3) REST does not promote nested URIs. In fact, it is advised not to do so.
What is REST? REST is an architecture, mainly the architecture of the Web. It’s constraints are:
- Stateless: no client context is stored server-side between requests
- Layered system
- Code on demand
- Uniform interface
- Identification of resources: All resources have an identifier. For REST web APIs, this identifier is a URI
- Manipulation of resources through representations: Imagine a Car resource. This resource has many representations: JSON, XML and YAML documents with the car’s characteristics; an HTML document for humans to read; and a JPEG picture of the car. All of these are representations of the car, but none are the car itself. With a REST API you may only interact with the resource through it’s representations (eg: obtainting the HTML document, or sending a JSON document which modifies the resource).
- Self-descriptive messages: Each message includes enough information to describe how to process the message. With web APIs, oftenly this translates into correctly using HTTP methods, which have semantics on its own and explicitly indicate their cacheability.
- Hypermedia as the engine of application state (HATEOAS): All resource representations should have links which the user can explore. For example, one explores the Web through links in HTML pages, which take you to new HTML pages. You need not know all specific URIs you need, you discover them dynamicly. This constraint is almost never taken into account in REST web APIs.