---
layout: post
title: "A quick look at REST"
date: 2013-10-06 14:27
comments: true
categories: [server, shell, webdev]
cover: /images/cover/avatar.png
keywords: rest, restful, Representational State Transfer, crud, api, post, get, put, delete
description: An intro to REST
---

Three months ago I've chosen a 
[REST](http://en.wikipedia.org/wiki/Representational_state_transfer) 
architecture for designing my new project at work. The project goal is to create 
<abbr title="Application Programming Interface">API</abbr> for managing gyms, 
trainings and trainees. 

This article is just light intro to the REST world, don't expect cool tips & 
tricks (maybe in next article).

# HTTP request methods

REST without using proper [HTTP methods](http://en.wikipedia.org/wiki/
Hypertext_Transfer_Protocol#Request_methods) is a nonsense. There are about 9 
methods but we need only 4.

* ```POST``` -- create a new resource
* ```GET``` -- get resource data
* ```PUT``` -- update a resource
* ```DELETE``` -- delete a resource

There is also ```PATCH``` method which is very similar to ```PUT``` method.
In fact ```PUT``` should rewrite a whole resource and ```PATCH``` only update 
some attributes of a resource. More about ```PUT``` vs ```PATCH```
[here](https://restful-api-design.readthedocs.org/en/latest/methods.html#patch-
vs-put).

<!-- more -->

# Simple example (we always work with objects)

REST greatly improves a simplicity of using the API. Let's have a look at an 
example how we manage trainings:

	http://api.example.com/training/
	http://api.example.com/training/:training/

We can access that URLs via ```GET```, ```POST```, ```PUT``` or ```DELETE``` 
HTTP methods. If we want 
to create a new training then we call the first URL. If we want to read 
training data, or update data, or delete a training then we use the second URL 
(just replace ```:training``` with some integer). Actually, REST force you take 
an advantage of 
[CRUD](http://en.wikipedia.org/wiki/Create,_read,_update_and_delete). And 
that's good. As you can see, to make operations with trainings we need just two 
URLs (I call them *access points*).

The philosophy of REST is to access *objects*. In the example ```training``` 
was the object. The reason is simple -- we can make CRUD operations (read, 
write, update, delete) only with objects.

# Another example

Well, you can ask: "What if I need to tell a trainee X wants to join training 
Y?". I solved the problem by creating another access point:

	http://api.example.com/training/:training/attendance/:trainee/

Now we are working with ```attendance``` object. Allowed HTTP methods for this 
access point are PUT and DELETE. 
If a trainee with ID 541 wants to join training with ID 1050 we call 
```http://api.example.com/training/1050/attendance/541/``` with ```PUT``` 
method. Later the trainee changes his mind and wants to leave the training, so 
we call the same URL with ```DELETE``` method.

# How to send data to server with cURL

I'll illustrate using REST API with curl utility.

## POST method:
 
Let's create a new training:

{% codeblock lang:bash %}
	curl -X POST \
		--data-urlencode "starts_at=2013-12-12 12:00" \
		--data-urlencode "ends_at=2013-12-12 13:00" \
		--data-urlencode "name=New training" \
		http://api.example.com/training/
{% endcodeblock %}

A simplified server response can look like this (in JSON):

{% codeblock lang:json %}
{
	"id"             : 800,
	"name"           : "New training",
	"starts_at"      : "2013-12-12T12:00:00+0100",
	"ends_at"        : "2013-12-12T13:00:00+0100",
	"created_at"     : "2013-10-06T17:23:12+0200",
	"updated_at"     : "2013-10-06T17:23:12+0200"
}
{% endcodeblock %}

## GET method:
 
Now we know training ID. Getting information about training:

{% codeblock lang:bash %}
	curl http://api.example.com/training/123/
{% endcodeblock %}

We haven't changed training data so a server response looks exactly like in 
above example.

## PUT method:
 
I made a mistake! The training should ends at 13:30, let's change it:
 
{% codeblock lang:bash %} 
	curl -X PUT \
		--data-urlencode "ends_at=2013-12-12 13:30" \
		http://api.example.com/training/800/
{% endcodeblock %}

A simplified server response:

{% codeblock lang:json %}
{
	"id"             : 800,
	"name"           : "New training",
	"starts_at"      : "2013-12-12T12:00:00+0100",
	"ends_at"        : "2013-12-12T13:30:00+0100",
	"created_at"     : "2013-10-06T17:23:12+0200",
	"updated_at"     : "2013-10-06T17:32:11+0200"
}
{% endcodeblock %}

## DELETE method:

This deletes training:

{% codeblock lang:bash %}
	curl -X DELETE \
		http://api.example.com/training/800/
{% endcodeblock %}

An obligatory server response:

{% codeblock lang:json %}
{
	"success" : true
}
{% endcodeblock %}