According to that model REST APIs come in 4 levels of sophistication:
- Level 0, aka the “Everything is a POST request” model for example propagated by SOAP. This is basically tantamount to remote procedure invocation.
- Level 1 – Resources: Every resource is accessed through its own canonical URL.
- Level 2 – HTTP Verbs: Verbs such as GET, PUT, PATCH and DELETE and HTTP status codes are used to distinguish between different types of actions and possible responses, different types of errors and resulting states.
- Level 3 – Hypermedia Controls: HTTP responses contain canonical links to requested or newly created resources and the various actions that are possible with those resources (e.g. DELETing a resource). This means that REST APIs of this level become inherently self-documenting by giving client developers hints about what to do with a resource. It also allows clients to (somewhat …) automatically access and manipulate resources.
ThoughtWorks consultant Ian Robinson is quoted as describing these levels like this:
- Level 1 tackles the question of handling complexity by using divide and conquer, breaking a large service endpoint down into multiple resources.
- Level 2 introduces a standard set of verbs so that we handle similar situations in the same way, removing unnecessary variation.
- Level 3 introduces discoverability, providing a way of making a protocol more self-documenting.