A sign saying 'REST AREA', with an arrow pointing up and to the right. It’s not unusual to see examples where people think they are “doing REST”, but are not. A lot of people are trying to use simple web technologies in their microservice architectures, but I suspect there’s a prevalent idea that if you are using HTTP and sending JSON back and forth, you’re doing REST, which is simply not the case. (We’re talking about the Representational State Transfer style of software architecture here, in case you’re lost.)

Spring’s REST

Spring’s Web MVC Framework documentation says in the first paragraph: “With the introduction of Spring 3.0, the @Controller mechanism also allows you to create RESTful Web sites and applications…” Further on, introducing its @RestController interface, it says: “It’s a very common use case to have Controllers implement a REST API, thus serving only JSON, XML or custom MediaType content.” So, does creating a web service using a @RestController-annotated class magically make it a RESTful service?
No. Such no.

Not so REST

The big thing I see developers getting wrong when trying to use web technologies for inter-service communication is that they continue to think about operations. They continue to think at a procedural code level: “I want this piece of code to call that piece of code, but over the network.” This is just good old (bad old?) RPC – Remote Procedure Calls – not REST. In fact, I think the design of Spring’s @RequestMapping method annotation technology actually encourages the creation of non-RESTful services, because it is all about making it easy to connect up the request for a particular URL path to the execution of a method.

Why is this an issue?
Because REST is not primarily about operations and executing code.
REST is primarily about resources, and transferring representations of them.

So, this is the first thing you should know about REST: if your URLs don’t refer to resources, you’re doing it wrong.

RESTful URLs do not identify operations. In REST architectures, the operation is always specified separately to the resource. When using HTTP as the transport, this means the operation is always specified as the HTTP method, not as part of the URL. Another way to remember this it is that the URL should never contain a verb. Observe:

Task	RESTful example	Non-RESTful examples
Retrieve a User record	`GET /users/123456`	`GET /getUser?id=123456 GET /getUser/123456`

You can see the key problem here: the non-RESTful examples contain the verb “get” in the URL. They are naming an operation, not a resource. Note that moving the ID into the path instead of a query parameter does not make this “getUser” example RESTful.

Here’s some more examples:

Task	RESTful example	Non-RESTful examples
Create a User record	`POST /users`	`POST /users/createUser`
Update a User record	`PUT /users/123456`	`POST /users/updateUser`
Delete a User record	`DELETE /users/123456`	`POST /users/deleteUser`

In the last two examples, we see the same resource, at the same location, being manipulated in two different ways.

Starting to think in terms of resources, and doing that by carefully designing the words in your URLs, is not always easy, and it doesn’t magically make what you’re doing RESTful. It’s a great place to start, though, because it will encourage you to think less about invoking code on a server and more about moving representations of your resources between the server and the client.

There’s obviously way more to REST than just what I’ve described here. Martin Fowler has a good discussion of a ‘maturity model’ for REST with examples. But if you know nothing else about REST, what you really need to know is to stop putting operations into your URLs and start thinking about the resources that you’re manipulating.