The REST you know!! Or not? Part 1

Why this POST if you already know REST?

I have noticed that there are many different opinions about what REST is and how you can use to create an API that is easy to use. Sometimes REST API’s are complex just because they are not created using correct REST. 

As a serious developer I don’t want to write ‘Bad Code’ and hopefully I am not the only one! If you are planning to use REST and don’t want to write ‘Bad Code’ either read this article. If you don’t mind to write ‘Bad Code’ also read this article because you then know how to create ‘Bad Code’ by not implementing the solutions below ;-).

What is REST?

Let’s begin with the basics. REST stands for Representational State Transfer (see WIKI – REST). Okay… So now you know, right? In short, REST is a communication protocol between client and server that is stateless. This means that the server does not keep track of the state between two requests. The communication can be cached for performance reasons. In most cases HTTP(S) will be used for communicating REST.

How does the communication work?

REST uses the HTTP verbs GET / POST / PUT / DELETE in most of the cases. Other Verbs can be used but in this article I will focus on these 4 verbs.

A lot of blogs and articles write about the REST verbs as a CRUD pattern with the following assumptions:

• POST = CREATE (Insert)
• GET = READ
• PUT = UPDATE
• DELETE = DELETE

The above assumption is partially correct but you are not limited to this assumption. A PUT can also be used for the CREATE. This will be show in the PUT chapter below.

How do you think?

When you know other communication protocols between client and server you may have noticed that a lot of protocols are RPC (Remote procedure call) based. Which means that the client will request some operation from the server which will than result the output of the operation. REST is not RPC based but RESOURCE based, which means that your thinking pattern must change from RPC style (GetCars, RentCar) to RESOURCE based style (GET /cars, POST /rentals). Let’s take a look how this really works. When you are implementing a REST API try to use Nouns and not to use Verbs for your URI’s.

Domain model

When defining a REST interface the domain model for the rest interface must be clear. During a project changes will always occur, but some kind of domain model must be available to be able to define your model for the REST interface. 

The model I will use in my examples is about renting cars:

The model consists of 3 classes:

• Customer which is the person that rents a car
• Address which is an address of the customer 
• Rental which is the resource for holding the rental period and link the Customer to a Car.
• Car which is a car that can be rent.

When defining resources you have to identify the root aggregates of the model. For my model I see 3 root aggregate Customer, Rental, Car. From the application perspective these objects are likely to get their own screen with a list of object. All customers in the system, all Rentals in the system, all Cars in the system. Address is not a root aggregate because we will never lookup an Address on its own. Address will always be displayed for a Customer.

By identifying the root aggregates the following URI structure is appropriate:

/customers
/customers/{id}/addresses/
/rentals
/cars

One other resource can be the resource to show rentals for a customer:

/customers/{id}/rentals

In the next post(s) I will be talking about the different HTTP Verbs in detail, different Response Results, Security issues, Maturity model and lots of other topic about REST.