Talk: https://www.youtube.com/watch?v=pspy1H6A3FM
Def: An architectural style defined by the constraints Client-Server, Stateless Communications, Cachin, Uniform Interface, Layered System and (optionally) Code-on-demand.
Rest is perfectly defined. There is a set of rules that define it. If you follow them, it's REST, if not, then it's not.
Identification of resources -> URI. If something has value, it has it's own URI. This mean we can link resources, we can bookmark them. They become entrypoints to our application.
Once we have "identifiable things", we need a way to represent them, here's
where the Content-Type headers come into play, metadata, etc. If we separate
an identity from its representation, we may have different representations for
the same identity over the course of time. This reduces the dependency. If we
add 5 more attributes to an entity, then that's a new representation.
We have "Hypermedia as the engine of the application state": Things are connected and we can provide links to them in the representations. This can take the shape of links, but also forms, flows, etc.
Self-descriptive messages: a message should make sense in itself. You don't need documentation to understand the messages. Standarisation plays an important role here.
The web is a good example: lots's of things with URIs, connected with hypermedia, governed by standard formats.
None of these can be assumed non-RESTful:
- /customers/format?drive=c
- /customers/getDetails?id=13
- /customers/delete?id=13
- /customers/13
- /customers/13/edit
It's all about the hypermedia returned, about the identity, not about the URI. The URI is only host + path + params. End of story.
Versions in URIs cause chagne for no good reason Documented URIs become APIs Assumptions about server details become facts
We make the URIs the API. If you do REST, this should actually be part of the
app. The app should be self-discoverable. Instead of people assuming that they
can concatenate /orders to /customers/{id} to get the orders, some part of
the the application should provide the link to get the orders.
The version number is in the URI because the URI is the API. However, Are we versioning data? Are we versioning documentation? formats? API? We should only version the hypermedia, the data, the representation... not the API. The fact that an API changes should not mean that the identifiable thing changes. Create new resources for new aspects, don't version. Reserve space for links.
Create a homepage for your API: links to your endpoints. There are some standards such as JSON Home. A benefit of this is that for clients to use the new stuff, you don't need to have them update: you just update your home.
Q: how does this differ from directly changing your endpoint? A: It's not about updating behaviour, it's about discoverability. Clients no longer need to hardcode the different endoints, but simply navigate the responses.
Links are about driving state: They allow you to access data transitions. You can cancel or accept an order through the links available.
Don't have clients build URIs using string concatenation, instead provide recipes so they can construct useful URIs.
But the same way you give them the possibility to construct URIs... you could also provide them recipes for building the request payloads.
Even when we're talking about machine2machine interface, we think about APIs. What we should really be doing is build hypermedia types independent of the server. We shouldn't be building a "twitter API", but a "tweet hypermedia format", so that any server can then implement his own version.
REST is about defining hypermedia formats, not APIs.