====== Qu'est ce qu'une API ? ======
===== API Rest =====
==== Que signifie REST ? ====
=== Separation of Concerns (Client / Server) ===
L’API ReST n’est pas concernée par l’affichage, les interactions utilisateur et la session.
Tous ces éléments doivent être gérés par le client (Ex. : application web frontend).
=== Stateless ===
Une API ReST ne doit pas maintenir de session ou de contexte.

La communication doit être de nature sans état, de sorte que chaque demande du client au serveur doit contenir toutes les informations nécessaires à la compréhension de la requête, et ne peut tirer profit d'aucun contexte stocké sur le serveur. 

L'état de la session est donc entièrement conservé sur le client. 

Cette contrainte induit les propriétés de visibilité, de fiabilité et de scalabilité.
 
  * **La visibilité** est améliorée parce qu'un système de surveillance n'a pas besoin de regarder au-delà d'une seule donnée de la demande pour déterminer la nature complète de la demande. 
  * **La fiabilité** est améliorée parce qu'elle facilite la tâche de récupération après des pannes partielles. 
  * **La scalabilité** est améliorée parce que le fait de ne pas avoir à stocker l'état entre les demandes permet au composant serveur de libérer rapidement des ressources, et simplifie encore la mise en œuvre parce que le serveur n'a pas à gérer l'utilisation des ressources entre les demandes.


=== Layered ===
La présence de connecteurs intermédiaires doit être implicite pour le client et le serveur (composant de cache / sécurité etc…).
=== Uniforme ===
L’interface est uniforme à tous les niveaux. Tous les éléments (et connecteurs) communiquent en utilisant la même interface.
Chaque ressource est identifiée de façon unique et canonicalisée avec son URI (URL ou URN dont voici deux exemples respectifs https://www.googleapis.com/books/v1/volumes/-DNcBAAAQBAJ et isbn:9780134051994).
In order to obtain a uniform interface, multiple architectural constraints are needed to guide the behavior of components. REST is defined by four interface constraints: identification of resources; manipulation of resources through representations; selfdescriptive messages; and, hypermedia as the engine of application state.
=== Cacheable ===
Il doit être possible de mettre les ressources en cache à tous les niveaux (front, connecteur intermédiaire, back, etc…).
Il doit être possible d’utiliser les implémentations standards de cache HTTP.

==== Modèle de maturité de Richardson ====
  * Source : [[https://architecturelogicielle.wordpress.com/2013/04/25/le-modele-de-maturite-de-richardson/]]

=== Niveau 0 : POX et XML-RPC ===

Dans ce type de système, le point d’entrée (l’URI) vers l’application est unique, et un seul verbe HTTP est utilisé par les requêtes du client (usuellement GET ou POST).

La méthode POX (Plain Old XML, que l’on peut traduire de manière prosaïque par « bon vieil XML »), consiste à concentrer la description applicative de la requête à l’aide d’XML, alors que la méthode XML-RPC (XML Remote Procedure Call) décrira sous forme XML quelle procédure serveur exécuter et avec quels paramètres.

Prenons comme exemple un système bancaire gérant des clients et des comptes dans lequel l’URI d’entrée est /banking.

Une requête client pour obtenir la description d’un client en mode POX pourra être
<code html>
POST /banking HTTP 1.1
...
<getClient id="1234" />
</code>

son équivalent XML-RPC étant
<code html>
POST /banking HTTP 1.1
...
<method name="getClient">
<params>
<param name="id">1234</param>
</params>
</method>

</code>

De manière analogue, voici à quoi pourrait ressembler une mise à jour de l’email d’un client en POX :
<code html>
POST /banking HTTP 1.1
...
<updateClient id="1234">
<email>leonard.richarson@nicemail.com</email>
</updateClient>
</code>
ou en XML-RPC :
<code html>
POST /banking HTTP 1.1
...
<method name="updateClient">
<params>
<param name="id">1234</param>
<param name="email">leonard.richarson@nicemail.com</param>
</params>
</method>
</code>
Ce type de modèle n’utilisant qu’une seule URI et le verbe HTTP utilisé ne déterminant pas le type d’action à exécuter coté serveur est classé au niveau 0 dans le MMR.
HTTP y sert uniquement de moyen pour véhiculer des appels au serveur applicatif. Le client est tenu de connaître précisément l’implémentation technique de l’application, d’où un fort couplage entre les 2.

=== Niveau 1 : plusieurs URIs, un seul verbe ===

Ce niveau de maturité consiste en l’utilisation de plusieurs URIs comme points d’entrée du système d’information mais d’un seul verbe HTTP(usuellement GET ou POST) ; c’est le premier pas vers une architecture REST de niveau 3. Les domaines applicatifs ou techniques du système sont éclatés en plusieurs URIs, par exemple ''/banking/clients'' pour la partie clients et ''/banking/accounts'' pour la partie comptes.

Ce modeste pas évite à un client (un agent) de connaître l’ensemble des domaines applicatifs du système (comme c’était le cas au niveau 0) s’il ne sert qu’à traiter un domaine unique par exemple. De plus, cette différentiation d’URIs par domaine applicatif apporte une sémantique aux points d’entrée du système ce qui est, une des grandes forces du style d’architecture REST.

Pour connaître les comptes d’un client, il suffit alors d’appeler la ressource ''/banking/accounts?client_id=1234''. La création d’un compte pour un client donné pourra se faire au moyen de la ressource ''/banking/accounts/create?client_id=1234'' en ajoutant dans le corps du message les détails, en XML par exemple, du compte à créer pour ce client :
<code html>
POST /banking/accounts/create?client_id=1234 HTTP 1.1
...
<account type="current" currency="EUR">
<balance>1000.10</balance>
</account>
</code>

La réponse du serveur en cas de succès pourra être :
<code html>
HTTP/1.1 200 OK
...
<account id="abcd-12" type="current" currency="EUR">
<creation>2013-04-24 15:22</creation>
<balance>1000.10</balance>
...
</account>
</code>
On peut voir que le corps du message contient les informations complètes du compte nouvellement créé. Le client peut alors s’il le désire supprimer le compte car il possède maintenant son identifiant :
<code html>
POST /banking/accounts/delete?id=abcd-12 HTTP 1.1
...
</code>

Ces exemples montrent un allègement de complexité dans la manière d’accéder au système d’information dès lors que la syntaxe des URIs est connue ainsi que le langage XML du domaine applicatif qui se trouve être réduit du fait de l’éclatement des URIs par rapport au niveau 1.

=== Le niveau 2 : plusieurs URIs, plusieurs verbes et les codes retour ===

Ce niveau de maturité ajoute l’utilisation sémantique des verbes (ou méthodes) et codes retours HTTP afin d’enrichir le niveau de protocole applicatif entre le client et le serveur. 

Même si la liste est plus longue (mais restreinte), les verbes GET, POST, PUT ou DELETE suffisent dans la grande majorité des cas à couvrir l’ensemble des besoins d’un système, en accord avec le principe CRUD ; soulignons quand même le dernier venu, PATCH, qui permet une modification partielle d’une ressource, contrairement à PUT qui impose le remplacement complet d’une ressource.

Si nous reprenons les exemples du niveau 1, l’utilisation des verbes et codes retour HTTP peuvent se faire ainsi :
<code html>
POST /banking/accounts/1234 HTTP 1.1
...
<account type="current" currency="EUR">
<balance>1000.10</balance>
</account>
</code>

pour la création d’un compte attaché au client 1234, et
<code html>
DELETE /banking/accounts/abcd-12 HTTP 1.1
...
</code>

pour la suppression du compte abcd-12.

L’utilisation du verbe POST a permis de clairement signifier une création de ressource de type compte à l’aide de l’URI /banking/accounts/1234. Comme il s’agit de la création d’un compte, la partie /1234 de l’URI n’est pas ambiguë pour le serveur : il s’agit bien entendu de l’identifiant du client pour lequel créer le compte.

De même, l’utilisation du verbe DELETE a permis de clairement signifier une suppression de ressource de type compte à l’aide de l’URI /banking/accounts/abcd-12. Comme il s’agit de la suppression d’un compte, la partie /abcd-12 de l’URI n’est pas ambiguë pour le serveur : il s’agit bien entendu de l’identifiant du compte à supprimer.

Concernant les réponses du serveur suite à la demande de création, l’utilisation des codes retour HTTP permet d’apporter une sémantique claire au client ; si la réponse est
<code html>
HTTP/1.1 201 Created
...
<account id="abcd-12" type="current" currency="EUR">
<creation>2013-04-24 15:22</creation>
<balance>1000.10</balance>
...
</account>
</code>

le client en déduit que le compte a bien été crée et il peut en récupérer l’identifiant.

Si la réponse du serveur est
<code html>
HTTP/1.1 404 Not Found
...
</code>
le client en déduit que le client n’existe pas parce qu’il a été supprimé avant la requête par exemple.

La simple utilisation des verbes et codes retour prédéfinis par HTTP a permis un allègement de couplage entre le client et le serveur : nul besoin pour lui de connaître l’implémentation détaillée coté serveur pour créer, interroger, mettre à jour ou supprimer une ressource, et pour analyser le résultat d’une requête au serveur. Même si l’implémentation technique coté serveur évolue, les verbes et codes retour HTTP resteront les mêmes et rien ne perturbera le client.

En outre, l’utilisation des verbes et codes retour HTTP a permis de simplifier, d’alléger, la codification des URIs du domaine applicatif.

=== Le niveau 3 : les services hypermédias ou HATEOAS ===

Ce niveau de maturité est le dernier du MMR et ajoute une notion cruciale au style d’architecture REST : Hypermedia As The engine Of Application State, HATEOAS.

Au niveau 2, le client doit connaître à l’avance l’ensemble des URIs correspondant aux différentes fonctionnalités du système ainsi que les actions possibles sur ces URIs (les méthodes HTTP). En somme, le client doit être au courant des requêtes possibles au fur et à mesure de son parcours au sein de l’applicatif : il doit connaître à l’avance les états applicatifs possibles du système.

Au niveau 3, le client découvre pas à pas ce qu’il lui est permis de faire au niveau de l’application et ce, grâce au hypermédias. 

Nous sommes déjà familiarisés avec cette notion lorsque nous naviguons sur le Web : chaque page HTML affiche des liens vers d’autres pages. Ces dernières ne sont en fait que les prochains états de l’application (du site) que nous pouvons explorer à partir de la page courante. Dans REST, ce principe est appelé HATEOAS pour illustrer que les liens hypermédias nous guident d’état en état applicatif sans que nous les connaissions à l’avance.

Reprenons nos exemples.

Pour créer un compte pour le client 1234, le client commencera par en obtenir la description (GET) :
<code html>
GET /banking/clients/1234 HTTP 1.1
</code>
Le serveur renvoie alors
<code html>
HTTP/1.1 200 OK
...
<client type="company">
<address>
...
</address>
...
<link rel="/banking/accounts" uri="/banking/accounts/1234">
</client>
</code>

Le tag link représente un lien hypermédia en spécifiant le domaine applicatif « comptes du client » avec l’attribut rel ainsi que l’URI correspondante ''/banking/accounts/1234''.
Ainsi, les modifications d’URI coté serveur n’impacteront jamais le client qui ne doit juste connaître la signification, la sémantique des valeur d’attribut rel.
De plus, l’ajout ou la suppression de tags link auto-documente les réponses du serveur avec les fonctionnalités accessibles depuis une réponse.

Si le client décide d’atteindre la ressource ''/banking/accounts/1234'' pour créer un compte, il émettra la même requête qu’au niveau 2 mais sans avoir eu besoin de connaître l’URI au préalable :
<code html>
POST /banking/accounts/1234 HTTP 1.1
...
<account type="current" currency="EUR">
<balance>1000.10</balance>
</account>
</code>

La réponse du serveur
<code html>
HTTP/1.1 201 Created
...
<account id="abcd-12" type="current" currency="EUR">
<creation>2013-04-24 15:22</creation>
<balance>1000.10</balance>
...
<link rel="self" uri="/banking/accounts/abcd-12">
</account>
</code>

offre un lien vers la ressource créée que le client pourra utiliser pour supprimer le compte à l’aide d’un DELETE.
===== Sources et ressources =====
  * [[https://architecturelogicielle.wordpress.com/2013/04/25/le-modele-de-maturite-de-richardson/|Le modèle de maturité de Richardson]]