We do a lot of REST in the Pineapple team. We love REST. Why? There are many reasons:

• It is standard, so that creating services always follows a pattern
• Developing clients is super easy, in all programming languages
• Programmers can easily understand it
• Testing (of all types) can be easily automated
• Because it relies on HTTP, it’s highly scalable infrastructure wise
• We can choose the preferred data format for sending and receiving information – usually JSON 🙂

Which are the most important steps when developing RESTful services?

First step is to identify the resources, such as photos, people (and others) that the service handles. Next, determine the best way to map the resource behavior to HTTP methods. But mapping operations is easy once you know the characteristics of the HTTP methods.

Safety

An HTTP method is considered safe if the request made with it does not cause any side effects and does not change the state of the resource. For example, the operation of retrieving a photo is safe, because the operation does not imply any update on the photo.

Idempotent

If you get the same response no matter how many times you request it, the method is said to be idempotent. So, you can consider a repetitive update operation on an existing photo as idempotent, if executed with the same parameters, the result is the same every time the operation is performed.

But not all methods are safe or idempotent. Check the table below.

HTTP Methods

HTTP methods are at the heart of REST. Clients, like browsers, applications using the APIs of Facebook or Google, or any other clients rely on them. There is some confusion on how and when to use them, therefore we are going to cover them below.

GET

We already know that GET must be safe and idempotent. Web clients know this as well and do not expect side effects when repeating GET requests. Use GET only for retrieving the representation of resources or other information.

# Request to fetch your favorite photo
GET /rest/photos/1234 HTTP 1.1
Host: www.rest.example.com
..
# Response contains some properties of the photo resource
HTTP/1.1 200 OK
Content-Type: application/json
{"id":"1234","name":"My favorite photo","link":"http://photo.com/photo/location"}

POST

POST is most commonly used for creating resources. For this purpose, the body of the request must contain the representation of the resource. You can also find it useful in other situations, i.e. when updating several resources at once, on tunneling requests, or when avoiding browser limitations (like query size).

# Request to save your favorite photo
POST /rest/photos HTTP 1.1
Host: www.rest.example.com
{"name":"My favorite photo","link":"http://photo.com/photo/location"}
..
# Response contains the representation of the photo resource
HTTP/1.1 201 Created
Content-Type: application/json
{"id":"1234","name":"My favorite photo","link":"http://photo.com/photo/location"}

PUT

Because POST is not idempotent, avoid using it when updating a resource and use PUT instead, as shown below (this is a common mistake). Though you may return a body in the response, it is not required by the HTTP 1.1 specification.

# Request to update your favorite photo
PUT /rest/photos/1234 HTTP 1.1
Host: www.rest.example.com
{"id":"1234","name":"My awesome photo"}
..
# Response does not contain any body
HTTP/1.1 204 No Content
Content-Type: application/json

DELETE

As you can understand from its name, this method is used for deleting resources. The interesting thing is that you might not always be able to implement it as idempotent. If DELETE is idempotent, your service has to be aware of all the deleted resources and return the same HTTP status, for example 204 No Content, even if the resource has been previously deleted.

# Request to delete your ugly photo
DELETE /rest/photos/1234 HTTP 1.1
Host: www.rest.example.com
..
# Response
HTTP/1.1 204 No Content

However, there might be other restrictions, i.e. security policies, that will require your service to return the 404 Not Found status instead.

OPTIONS

Use it to query the server about the HTTP methods available for resource manipulation or to ping the service. Be aware that the request does not contain a body, but it’s free to return the representation of a resource in the response.

# Request to query about the photo service
OPTIONS /rest/photos HTTP 1.1
Host: www.rest.example.com
..
# Response contains the allowed HTTP methods that can be used for accessing this resource
HTTP/1.1 204 No Content
Allow: HEAD, GET, OPTIONS, DELETE, POST, PUT

HEAD

Use this method to look for a particular resource on the server. It usually returns the same headers as GET. The HTTP specification requires that nor request neither response contain a body.

# Request to query about the photo service
HEAD /rest/photos/1234 HTTP 1.1
Host: www.rest.example.com
..
# Response contains the same as GET
HTTP/1.1 200 OK
Content-Type: application/json

We hope that this article helps you choose the best solution for your services. And remember, if you want to join our team, we love new colleagues almost as much as REST! 🙂