Level 0 is really easy to reach; you just have to make your resource available on a network through the HTTP protocol. You can use any data representation you find best suited for your use case (XML, JSON, and so on).

Most people think of resources when they hear the term REST. A resource is a unique identifier for an element of our model, a user or a tweet, for instance. With HTTP, a resource is obviously associated with a unified resource identifier URI, as shown in this example:

Maybe your API could allow access to a particular tweet related to a user with /user/42/tweet/3 or maybe each tweet is uniquely identified, in which case you might prefer /tweet/3.

The goal of this level is to deal with the complexity of an application by exposing multiple specialized resources.

There is no rule regarding the type of response that your server can return. You might want to include only scarce information when you list all the resources with /users and give more details when a specific resource is requested. Some APIs even let you list the fields you are interested in before serving them to you.

It really is up to you to define the form of your API, keeping one simple rule in mind: the principle of least astonishment. Give your users what they expect and your API will already be in good shape.

This level is about using the HTTP verbs to identify possible actions on the resources. This is a very good way to describe what can be done with your API since the HTTP verbs are a well-known standard among developers.

The main verbs are listed here:

Most applications that allow Create Read Update Delete (CRUD) operations get by with only three verbs: GET, DELETE, and POST. The more verbs you implement, the richer and more semantic your API becomes. It helps third parties to interact with your service by allowing them to type a few commands and see what happens.

The OPTIONS and HEAD verbs are rarely seen because they work on the metadata level and are typically not vital to any application.

At first sight, the PUT and POST verbs appear to do the same thing. The main difference is that the PUT verb is said to be idempotent, which means that sending the same request multiple times should result in the same server state. The implication of that rule is essentially that the PUT verb should operate on a given URI and contain enough information for the request to succeed.

For instance, a client can use PUT data on /user/42, and the result will be either an update or a creation, depending on whether the entity existed prior to the request.

On the other hand, POST should be used when you don't exactly know what URI you should write to. You could send POST to /users without specifying an ID in the request and expect the user to be created. You could also send POST to the same /users resource, this time specifying a user ID inside the request entity and expect the server to update the corresponding user.

As you can see, both of these options work. One frequent use case is to use POST for creation (because, most of the time, the server should be in charge of the IDs) and to use PUT to update a resource whose ID is already known.

The server might also allow a resource to be modified partially (without the client sending the full contents of the resource). It should respond to the PATCH method in that case.

At this level, I also encourage you to use meaningful HTTP codes when providing responses. We will see the most common codes in a moment.

Hypermedia controls are also known as Hypertext As The Engine Of Application State (HATEOAS). Behind this barbarous acronym lies the most important property of a RESTful service: making it discoverable through the use of hypertext links. This is essentially the server telling the client what its options are, using the response headers or the response entity.

For instance, after the creation of a resource with PUT, the server should return a response with the code 201 CREATED and send a Location header containing the URI of the created resource.

There is no standard that defines how the link to the other parts of the API should look. Spring Data REST, a Spring project that allows you to create a RESTful backend with minimal configuration, typically outputs this:

{
  "_links" : {
    "people" : {
      "href" : "http://localhost:8080/users{?page,size,sort}",
      "templated" : true
    }
  }
}

Then, go to /users:

{
  "_links" : {
    "self" : {
      "href" : "http://localhost:8080/users{?page,size,sort}",
      "templated" : true
    },
    "search" : {
      "href" : "http://localhost:8080/users/search"
    }
  },
  "page" : {
    "size" : 20,
    "totalElements" : 0,
    "totalPages" : 0,
    "number" : 0
  }
}

This gives you a good idea of what you can do with the API, doesn't it?