how-to-rest

Designer une belle API Rest

Ou en tout cas essayer ...

On se demande souvent comment développer une API Rest simple, solide et évolutive, c’est la question à laquelle je vais essayer de répondre en présentant mon approche des différentes problématiques à prendre en compte.

Qui suis-je ?

Designer une belle API Rest

Qu'est-ce que REST ?
Points forts de REST
Rappel des bases
Les méthodes
Relations entre ressources : abuser des headers !
Versionning
Authentification

Qu'est-ce que REST ?

Un type d'architecture d'API

Manipule des ressources/collections

Orienté services

Contient plusieurs niveaux de définition

Un type d'architecture d'API : - Pas une norme - Un design d'API - Pas obligatoire Manipule des objects, collections et récupère des données. Plusieurs niveau de définition : - Je ne vais pas les faire 1 à 1 - A ne pas mettre en opposition à SOAP : SOAP = rest de niveau 0

Qu'est-ce que REST ?

Manipule des ressources/collections

Un type d'architecture d'API

Orienté services

Contient plusieurs niveaux de définition

Points forts de REST

Simple : on abstrait la couche de persistance

Stateless : pas de session

Performant pour du texte : avec une politique de cache adaptée

Uniforme : Prévisible, self documenté (HATEOAS)

Portable : Aujourd'hui tout le monde connait HTTP/1.1

Rappel des bases

1 URI correspond à 1 ressource

GET /data/2.0/some-collection/some-id
Host : api.example.com

HTTP/1.1 200 OK

{
  hello : 'World',
  hey   : 'Ho',
  lets  : 'Go'
}

PAS REST : Une URI par version, pour une même ressource

Pas REST : Version dans l'URI

Rappel des bases

1 URI correspond à 1 ressource

GET /data/some-collection/some-id
Host : api.example.com

HTTP/1.1 200 OK

{
  hello : 'World',
  hey   : 'Ho',
  lets  : 'Go'
}

REST

Rappel des bases

Les collection, au pluriel ou non ?

Peu importe, mais rester consistant !

/user/user/1

/users/users/1

Rappel des bases

Format/tri/filtre/ordre de données en paramètre de requête où dans le header

GET /data/some-collection/some-id.xml
Host : api.example.com

GET /data/some-collection/some-id.json
Host : api.example.com

PAS REST : 2 URIs pour une ressource

Rappel des bases

Format/tri/filtre/ordre de données en paramètre de requête où dans le header

GET /data/some-collection/some-id
Host : api.example.com
Accept : application/json,application/xml;q=0.9

GET /data/some-collection/some-id
Host : api.example.com
Accept : application/xml,application/json;q=0.9

REST

Rappel des bases

Format/tri/filtre/ordre de données en paramètre de requête où dans le header

GET /data/some-collection/0/10/
Host : api.example.com
Accept : application/json

PAS REST : So damn many URIs

Rappel des bases

Format/tri/filtre/ordre de données en paramètre de requête où dans le header

GET /data/some-collection?start=0&size=10
Host : api.example.com
Accept : application/json

HTTP/1.1 206 Partial Content

REST

BONUS : Retour 206 et non 200 : Partial content

Rappel des bases

Pas de majuscules dans l'URI, priviléger le tiret

GET /data/someCollection
Host : api.example.com

Danger zone

GET /data/some-collection
Host : api.example.com

Safe zone

Une URI est case-insensitive sur certains sites et d'autres non, préférer être consistant - Wikipedia l'est sur le premier caractère - Stackoverflow est case insensitive

Rappel des bases

Jamais de verbes dans l'URI

GET /data/some-collection/some-id/get-data
Host : api.example.com
Accept : application/json

POST /data/some-collection/some-id/delete-data
Host : api.example.com
Accept : application/json

PAS REST : Utiliser les méthodes HTTP

Les méthodes HTTP

Les classiques (CRUD basique)

GET
DELETE
PUT
POST

Mais aussi

PATCH
OPTIONS
HEAD
TRACE
CONNECT

GET

READ du CRUD
Nullipotent
On récupère des données

GET

GET /data/user
Host : api.example.com

Renvoie la collection d'utilisateurs (ou la collection de leur URIs)

GET /data/user/1
Host : api.example.com

Renvoie l'utilisateur avec id 1

DELETE

DELETE du CRUD
Idempotent
On supprime la donnée ou on vide la collection

DELETE

/userVide la collection d'utilisateur

/user/1Supprime l'utilisateur ayant pour id 1

PUT

CREATE ou UPDATE du CRUD
Idempotent
On crée ou on écrase les données

PUT

/userÉcrase toute la collection user par la collection envoyée en corps de requête

/user/1Si l'utilisateur n'existe pas, la crée, sinon l'écrase

Attention à bien envoyer la ressource entièreLe PUT ne correspond pas à une mise à jour partielle

PUT

PUT /data/user/1
Host : api.example.com

{
  "login"    : "Hello",
  "password" : "World"
}

On crée (ou remplace) l'utilisateur 1 à partir de tout le corps de la requète

Si l'utilisateur avait d'autres champs comme des ROLES, on les supprime

POST

2 comportements différents
Non-idempotent

POST

1er comportement : Provoque le changement d'une ressource

/user/1/pictureSi l'utilisateur a une photo, la crée. Sinon autre chose (par ex: exception/remplace/...)

/user/1/friend/5Ajoute l'utilisateur 5 à sa friend list, sinon le retire

POST

2nd comportement : ajoute un élément à une collection, sans définir son id

/user/1/center-of-interestAjoute un centre d'intérêt à la liste.

Si on appelle 3 fois, 3 ajouts de la ressource passée en body, avec 3 ids différents

PATCH

Non-idempotent
On met à jour partiellement des données

PATCH

Mon conseil : RFC 6902

PUT /data/user/1
Host : api.example.com
Content-Type: application/json-patch+json

[
  { "op": "test", "path": "/a/b/c", "value": "foo" },
  { "op": "remove", "path": "/a/b/c" },
  { "op": "add", "path": "/a/b/c", "value": [ "foo", "bar" ] },
  { "op": "replace", "path": "/a/b/c", "value": 42 },
  { "op": "move", "from": "/a/b/c", "path": "/a/b/d" },
  { "op": "copy", "from": "/a/b/d", "path": "/a/b/e" }
]

GET /data/user/1
Host : api.example.com

{
  "a" : {
    "b" : {
      "d" : 42,
      "e" : 42
    }
  }
}

OPTIONS

Nullipotent
Retourne les methodes autorisées à l'URI appelée

OPTIONS

OPTIONS /data/user/1
Host : api.example.com

HTTP/1.1 204 No content
Allow : GET,PUT,DELETE,OPTIONS,PATCH,HEAD

HEAD

Nullipotent
Retourne le header renvoyé lors d'un GET à l'URI appelée

Les relations entre ressources

Des relations ? Mais pourquoi ?

Le niveau 3 d'une architecture REST indique qu'une telle api doit être self-descritive

Le mot clé : HATEOASHypermedia as the Engine of Application State

Les relations entre ressources

Que nous dit HATEOAS ?

Je ne dois jamais avoir à deviner :

Comment accéder à une ressource
Quelles sont les relations entre mes ressources

Les relations entre ressources

Simple avec XML

GET /data/user/1
Host : api.example.com

HTTP/1.1 200 OK

<!--?xml version="1.0" encoding="utf-8" ?-->
<user>
  <id>1</id>
  <firstname>CHALET</firstname>
  <lastname>Nicolas</lastname>
  <link rel="self" href="/data/user/1" />
  <link rel="shipping-adress" href="/data/adress/29" />
</user>

XML c'est bien, si on aime la redondance ...

Les relations entre ressources

Hal+json

{
  "_links": {
    "self": { "href": "/orders" },
    "curies": [{
      "name": "ea",
      "href": "http://example.com/docs/rels/{rel}",
      "templated": true
    }],
    "next": { "href": "/orders?page=2" },
    "ea:find": {
      "href": "/orders{?id}",
      "templated": true
    },
    "ea:admin": [{
      "href": "/admins/2",
      "title": "Fred"
    }, {
      "href": "/admins/5",
      "title": "Kate"
    }]
  },
  "currentlyProcessing": 14,
  "shippedToday": 20,
  "_embedded": {
    "ea:order": [
      {
        "_links": {
          "self": { "href": "/orders/123" },
          "ea:basket": { "href": "/baskets/98712" },
          "ea:customer": { "href": "/customers/7809" }
        },
        "total": 30.00,
        "currency": "USD",
        "status": "shipped"
      }, {
        "_links": {
          "self": { "href": "/orders/124" },
          "ea:basket": { "href": "/baskets/97213" },
          "ea:customer": { "href": "/customers/12369" }
        },
        "total": 20.00,
        "currency": "USD",
        "status": "processing"
      }
    ]
  }
}

Verbeux ...

Les relations entre ressources

Pour une ressource

GET /data/user/1
Host : api.example.com

HTTP/1.1 200 OK

{
  "_links": {
    "self"            : { "href" : "/data/user/1" },
    "shippingAddress" : { "href" : "/data/address/29" }
  },
  "_data": {
    "id"        : 1,
    "firstName" : "Nicolas",
    "lastName"  : "CHALET"
  }
}

Les relations entre ressources

Pour une collection paginée

GET /data/user?start=0&size=2
Host : api.example.com

HTTP/1.1 206 Partial Content

{
  "_links": {
    "self"  : { "href" : "/data/user?start=0&size=2" },
    "next"  : { "href" : "/data/user?start=2&size=2" },
    "first" : { "href" : "/data/user?start=0&size=2" },
    "last"  : { "href" : "/data/user?start=16&size=2" },
  },
  "_data": [
    {
      "_links": {
        "self"            : { "href" : "/data/user/1" },
        "shippingAddress" : { "href" : "/data/address/29" },
      },
      "id"        : 1,
      "firstName" : "Nicolas",
      "lastName"  : "CHALET"
    }, {
      "_links": {
        "self"            : { "href" : "/data/user/2" },
        "shippingAddress" : { "href" : "/data/address/35" },
      },
      "id"        : 2,
      "firstName" : "Tony",
      "lastName"  : "STARK"
    }
  ]
}

Les relations entre ressources

Étoffons le header

GET /data/user?start=0&size=2
Host : api.example.com

HTTP/1.1 206 Partial Content
Accept-Ranges: user
Content-Range: user 0-2/18

{
  "_links": {
    "self"  : { "href" : "/data/user?start=0&size=2" }
  },
  "_data": [
    {
      "_links": {
        "self"            : { "href" : "/data/user/1" },
        "shippingAddress" : { "href" : "/data/address/29"  }
      },
      "id"        : 1,
      "firstName" : "Nicolas",
      "lastName"  : "CHALET"
    }, {
      "_links": {
        "self"            : { "href" : "/data/user/2" },
        "shippingAddress" : { "href" : "/data/address/35"  }
      },
      "id"        : 2,
      "firstName" : "Tony",
      "lastName"  : "STARK"
    }
  ]
}

Mais on a toujours un niveau d'indentation inutile

Les relations entre ressources

Web Linking (RFC 5988)

GET /data/user?start=0&size=2
Host : api.example.com

HTTP/1.1 206 Partial Content
Accept-Ranges: user
Content-range: user 0-2/18
Link: </data/user?start=0&size=2>; rel="self"

[
  {
    "_links": {
      "self"            : { "href" : "/data/user/1" },
      "shippingAddress" : { "href" : "/data/address/29"  }
    },
    "id"        : 1,
    "firstName" : "Nicolas",
    "lastName"  : "CHALET"
  }, {
    "_links": {
      "self"            : { "href" : "/data/user/2" },
      "shippingAddress" : { "href" : "/data/address/35"  }
    },
    "id"        : 2,
    "firstName" : "Tony",
    "lastName"  : "STARK"
  }
]

Les relations entre ressources

Pour l'utilisateur

GET /data/user/1
Host : api.example.com

HTTP/1.1 200 OK
Link: </data/user/1>; rel="self",
</data/address/29>; rel="shippingAddress"

{
  "id"        : 1,
  "firstName" : "Nicolas",
  "lastName"  : "CHALET"
}

Les relations entre ressources

On peut même retirer le self avecle header Content-Location

GET /data/user/1
Host : api.example.com

HTTP/1.1 200 OK
Content-Location: /data/user/1
Link: </data/address/29>; rel="shippingAddress"

{
  "id"        : 1,
  "firstName" : "Nicolas",
  "lastName"  : "CHALET"
}

Les relations entre ressources

Maintenant la méthode HEAD prends tout son sens, on va pouvoir parcourir toute l'API sans requêter vraiment la ressource

HEAD /data
Host : api.example.com

HTTP/1.1 204 No Content
Link: </data/user>; rel="user",
</data/address>; rel="shippingAddress"

De plus, avec la méthode OPTIONS, on saura ce qu'on peut y faire

Versionning d'une API REST

Il y a 3 façons "communes", aucune n'est vraiment bonne, mais bon, faut bien en choisir une ...

Dans l'URI
Dans un custom header
Dans le header Accept

Versionning d'une API REST

Dans l'URI

GET /data/v1/user
Host : api.example.com

HTTP/1.1 200 OK
...

GET /data/v2/user
Host : api.example.com

HTTP/1.1 200 OK
...

Versionning d'une API REST

Dans l'URI

PROS

URI très "portables", un simple copier coller et on partage la bonne version
Le routing est plus simple si chaque version est concernée par une application à part entière

CONS

Plusieurs URIs pour une même ressource : pas REST
Sémantiquement incorrect

Versionning d'une API REST

Dans un custom header

GET /data/user
Host : api.example.com
api-version: 1

HTTP/1.1 200 OK
...

GET /data/user
Host : api.example.com
api-version: 2

HTTP/1.1 200 OK
...

Versionning d'une API REST

Dans un custom header

PROS

Cool URIs don't change
Sémantiquement 'presque' correct

CONS

Non portable d'un simple copier-coller
On se retrouve hors spec HTTP

Versionning d'une API REST

Dans le header Accept

GET /data/user
Host : api.example.com
Accept: application/com.myapp-v1+json

HTTP/1.1 200 OK
...

GET /data/user
Host : api.example.com
Accept: application/com.myapp-v2+json

HTTP/1.1 200 OK
...

Versionning d'une API REST

Dans le header Accept

PROS

Cool URIs don't change
Sémantiquement correct

CONS

Non portable d'un simple copier-coller

Versionning d'une API REST

Que faire si l'utilisateur ne fournit pas de version ?

Fournir la dernière version
Fournir la première version

Versionning d'une API REST

Mon choix personnel

Version dans le header AcceptSi pas de version demandée, fournir la première

Authentification

Les grands principes

Une API doit rester stateless : pas de session
Un token encrypté et indécryptible côté client
Le token encrypté côté serveur à l'aide d'un code secret
Une solution simple à implémenter, le token JSON : JWT

Authentification

Etape 1 : côté client, premier appel

POST /login
Host : api.example.com
Accept: application/com.myapp-v1+json

{
  "name"     : 'SupAdmin',
  "password" : 'SuPassword'
}

Authentification

Etape 2 : côté serveur, réponse

var API_SECRET = 'IKeepMySecretsLockedDown';

User.findByName({name : req.body.name}, function(user) {
  if (!user) {
    res.json({
      success : false,
      message : 'User not found'
    });
  } else if (user.password !== req.body.password) {
    res.json({
      success : false,
      message : 'Wrong password'
    });
  } else {
    var token = jwt.encode(req.body, API_SECRET);
    res.json({
      success : true,
      message : 'Authentificated !',
      token   : token
    });
  }
});

Authentification

Etape 3 : côté client, réception, stockage du token

HTTP/1.1 200 OK

{
  "success" : true,
  "message" : "Authentificated",
  "token"   : "BLAHblahBLAHblahTOKEN"
}

Plusieurs choix pour le stocker

En cookie
En local storage
... juste en mémoire ? ...

Authentification

Etape 4 : côté client, requête sur une resource protégée

Envoie du token à chaque requête mais encore plusieurs choix ...

En paramètre de requète (?token=BLAHblah...)
En header de requête (Authorization/X-quelquechose)

Authentification

Etape 4 : côté client, requête sur une resource protégée

GET /data/over-protected-data
Host : api.example.com
Accept: application/com.myapp-v1+json
Authorization: JWT BLAHblahBLAHblahTOKEN

HTTP/1.1 200 OK

{
  "wow"  : "suchSecret",
  "much" : "data"
}

Authentification

Etape 5 : côté serveur, contrôle des autorisations

var API_SECRET = 'IKeepMySecretsLockedDown';

function (req, res) {
  var authToken = req.headers.Authorization,
    credentials = jwt.decode(authToken, API_SECRET);

  User.validate(credentials).then(function(error) {
    if (error) {
      res.sendStatus(401);
    } else {
      res.json(OverProtectedData.get());
    }
  });
}

Des question ? :)

Reférences

Retrouver les slides : https://grobim.github.io/how-to-rest

1/60

Designer une belle API Rest Ou en tout cas essayer ... On se demande souvent comment développer une API Rest simple, solide et évolutive, c’est la question à laquelle je vais essayer de répondre en présentant mon approche des différentes problématiques à prendre en compte.

Designer une belle API Rest – Rappel des bases – Rappel des bases

Grobim

Designer une belle API Rest – Rappel des bases – Rappel des bases

0 1 (function() { var po = document.createElement('script'); po.type = 'text/javascript'; po.async = true; po.src = 'https://apis.google.com/js/platform.js'; var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(po, s); })();

how-to-rest

Designer une belle API Rest

Qui suis-je ?

Designer une belle API Rest

Qu'est-ce que REST ?

Qu'est-ce que REST ?

Points forts de REST

Rappel des bases

Rappel des bases

Rappel des bases

Rappel des bases

Rappel des bases

Rappel des bases

Rappel des bases

Rappel des bases

Rappel des bases

Les méthodes HTTP

GET

GET

DELETE

DELETE

PUT

PUT

PUT

POST

POST

POST

PATCH

PATCH

OPTIONS

OPTIONS

HEAD

Les relations entre ressources

Les relations entre ressources

Les relations entre ressources

Les relations entre ressources

Les relations entre ressources

Les relations entre ressources

Les relations entre ressources

Les relations entre ressources

Les relations entre ressources

Les relations entre ressources

Les relations entre ressources

Versionning d'une API REST

Versionning d'une API REST

Versionning d'une API REST

Versionning d'une API REST

Versionning d'une API REST

Versionning d'une API REST

Versionning d'une API REST

Versionning d'une API REST

Versionning d'une API REST

Authentification

Authentification

Authentification

Authentification

Authentification

Authentification

Authentification

Des question ? :)

Reférences

0 1