Service REST | Échange de données

class: main-title

<h1>Échange de données</h1>

<h2>Service REST</h2>

---

<ul>
<li>Ressources</li>
<li>Status</li>
<li><em>Header</em></li>
</ul>

---

<p><a href="https://restfulapi.net/" target="_blank">REST</a> propose une architecture standard pour l'élaboration d'application serveur</p>

<ul>
<li>Interface uniforme pour l'accès aux <strong>ressources</strong></li>
<li><strong>Séparation</strong> client-serveur</li>
</ul>

<p>Le protocole HTTP offre plusieurs mécanismes permettant de respecter les principes REST en développant un service web respecter les principes REST en développant un service web</p>

<ul>
<li>URL</li>
<li>Verbe</li>
<li>Status</li>
<li><em>Headers</em></li>
<li>Body</li>
</ul>

---

<h1 class="slide-only">HTTP, récapitulatif</h1>

<div class="fifty-left">
    <b>Requête</b>
    <img src=/sessions/2023A/0SV/documentation/assets/03.1-service-rest/request.png alt="">
</div>

<div class="fifty-right">
    <b>Réponse</b>
    <img src=/sessions/2023A/0SV/documentation/assets/03.1-service-rest/response.png alt="">
</div>

---

<p>La structure des URLs permet d'identifier clairement et de manière uniforme les <strong>ressources</strong> accessible via le service web.</p>

<pre><code class="language-md">/products
/products?brand=keychron&amp;sort=price-asc
/products/B09NLTWKGP

/semesters
/semesters/A2020
/semesters/A2020/courses
/semesters/A2020/courses/420-0Q7-SW
/semesters/A2020/courses/420-0Q7-SW/groups
/semesters/A2020/courses/420-0Q7-SW/groups/2

/orders/202201012314
/orders/202201012314/invoice
</code></pre>

---

<h1 class="menu">Verbe</h1>

<p>Les verbes HTTP permettent de rendre explicite l'<strong>action</strong> à appliquer sur une ressource</p>

<ul>
<li><strong>GET</strong> Récupérer</li>
<li><strong>POST</strong> Créer, soumettre</li>
<li><strong>PUT</strong> Remplacer <em>sinon créer</em></li>
<li><strong>PATCH</strong> Modifier partiellement</li>
<li><strong>DELETE</strong> Supprimer</li>
</ul>

</div>

<pre><code class="language-md">GET /conversations

GET /conversations/9812
GET /conversations/9812/messages

POST /conversations/9812/messages
{ "text": ... }

PATCH /messages/987123654
{ "text" : ... }

PATCH /messages/987123654
{ "reaction" : ... }

DELETE /messages/456192837
</code></pre>

</div>

<p><a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods" target="_blank">Verbes</a></p>

---

<h1 class="menu">Status</h1>

<ul>
<li><strong>1XX</strong> Information</li>
<li><strong>2XX</strong> Succès <code>200, 201, 202, 204</code></li>
<li><strong>3XX</strong> Redirection</li>
<li><strong>4XX</strong> Erreur du client <code>400, 401, 403, 404, 405, 429</code></li>
<li><strong>5XX</strong> Erreur du serveur</li>
</ul>

<p><a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status" target="_blank">Status Codes</a></p>

<p><strong><em>ATTENTION</em></strong></p>

<p>Il est aussi possible de TOUJOURS retourner un code 200 et d'indiquer l'erreur dans le <em>body</em> de la réponse.</p>

---

<h1 class="menu"><i>Headers</i></h1>

<p>Les <em>headers</em> permettent d'ajouter des informations complémentaires à la communication HTTP, <strong>requête <em>ou</em> réponse</strong>, identifiés par la structure <code>Clé: Valeur</code></p>

<ul>
<li><strong>Contenu</strong></li>
<li><strong>Authentification</strong></li>
<li>Contexte requête/réponse</li>
<li>Cookies</li>
<li>Cache</li>
</ul>

</div>

<pre><code class="language-md">Content-Length: 742

Content-Type: application/json
Content-Type: text/html

Content-Disposition: attachment; filename="cat.jpg"

Accept: */*
Accept: image/*
Accept: text/html
</code></pre>

</div>

<p><a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers" target="_blank">Headers</a></p>

---

<p>Le mécanisme principal de transfert de données en HTTP est le <strong>body</strong> des requêtes et réponses. Outre les fichiers bruts (images, zip, etc.), il est judicieux d'uniformiser le format de donnée utilisé.</p>

<ul>
<li>JSON</li>
<li>XML</li>
<li>Protobuf</li>
<li>...</li>
</ul>

---
class: section-title

<h1>Exemple RPC -> REST</h1>

---

<h1 class="menu">Authentification</h1>

<p>Il est fréquent de vouloir restreindre l'accès à certaines ressources d'un service web, donc il faut être en mesure d'authentifier qui effectue la requête. On peut mettre en place une technique personnalisée pour la gestion des identifiants, mais le protocole HTTP offre un mécanisme standard qui facilite l'implémentation via les <em>headers</em>.</p>

<p><strong>Réponse</strong> initiale</p>

<pre><code class="language-md">WWW-Authenticate: Basic realm="Zone restreinte!!!"
</code></pre>

</div>

<p><strong>Requête</strong> subséquente</p>

<pre><code class="language-md">Authorization: Basic ZXRkOnNoYXdp
</code></pre>

<p>Les identifiants sont joints par <code>:</code> et encodé en Base64, ex: <code>etd:shawi</code> devient <code>ZXRkOnNoYXdp</code></p>

</div>