Bienvenue au bar API-ritif 🍹
Tout au long de ce cours, nous allons fréquenter un établissement très particulier : API-ritif, le bar de l'école de dev. On n'y entre pas par la porte, mais par HTTP.
L'adresse exacte du bar est donnée en cours.
Consommation responsable : les cocktails d'API-ritif sont 100 % virtuels.
L'abus de requêtes est sanctionné par le barman (voir 429).
La carte
| Cocktail | Description du barman |
|---|---|
| Hello World | Sans alcool. Le premier de tout développeur. |
| Null Pointer Mojito | Sans alcool : contient null alcool. |
| Segfault Sunrise | Un classique. Plante rarement, mais sans prévenir. |
| Pull Request Colada | Doux et crémeux. Nécessite deux approbations. |
| Blue Screen Lagoon | Bleu. Très bleu. |
| Java Martini | Un espresso martini. Long à démarrer, puis très efficace. |
| Merge Conflict | Deux alcools qui ne s'entendent pas. À résoudre à la main. |
| Kernel Panic | Le plus fort de la carte. Redémarrage conseillé après. |
| 404 Spritz | Introuvable, comme son nom l'indique. |
| Sudo Rhum | Pour ceux qui ont les droits. |
| Infinite Loop | On en reprend un, puis un autre, puis un autre… |
Le barman murmure qu'il existe d'autres cocktails, qui ne figurent pas sur la première page de la carte…
Les règles de la maison
- Toutes les routes commencent par
/v1. - Le bar parle JSON. Pensez au header
Content-Type: application/jsonquand vous envoyez des données. - Les listes sont paginées : paramètres
?page=et?per_page=. - Certaines routes demandent d'être client du bar : envoyez votre clé dans le header
X-API-Key. - Les erreurs sont renvoyées au format
application/problem+json: lisez-les, elles sont souvent bavardes. - Le barman n'est pas une machine : trop de requêtes d'un coup et il vous demande de patienter.
Les principales ressources
| Ressource | Description |
|---|---|
/v1/ |
L'accueil du bar |
/v1/customers |
Les clients (inscription) |
/v1/me |
Votre profil |
/v1/cocktails |
La carte |
/v1/cocktails/{id}/reviews |
Les avis sur un cocktail |
/v1/orders |
Vos commandes |
La documentation complète de l'API (le contrat OpenAPI) sera étudiée au chapitre 6. D'ici là, explorez !
La vie d'une commande
Une commande ne reste pas figée : elle avance toute seule dans le temps.
pending ──▶ preparing ──▶ ready ──▶ served
│
└──▶ cancelled (uniquement tant qu'elle est pending)Comme dans un vrai bar : une fois que le barman a commencé à préparer la commande, il est trop tard pour annuler !