---
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 %}