wikinotes

Cette page est en lecture seule. Vous pouvez afficher le texte source, mais ne pourrez pas le modifier. Contactez votre administrateur si vous pensez qu'il s'agit d'une erreur.
{{tag>dev web api rest}}


====== S'entrainer avec l'API de Github ======

Notes et transcriptions du cours "[[000_start|Adoptez les API REST pour vos projets web]]" disponible sur la plateforme [[https://openclassrooms.com|Openclassrooms]]


===== Manipulez des données avec l’API GitHub =====

On avance, on avance ! Maintenant que vous avez un token d’authentification, vous pouvez utiliser l’API pour mettre à jour votre profil GitHub !

Dans ce chapitre, nous allons pratiquer et utiliser le reste des opérations CRUD – Create (créer), Update (mettre à jour) et Delete (supprimer) – et leurs verbes HTTP équivalents – POST  (publier),  PUT (mettre) et DELETE (supprimer).

Je vous invite vivement à suivre pas à pas les étapes suivantes et à pratiquer afin de maximiser votre apprentissage.

===== Créez un repo GitHub avec la méthode POST =====

Pour **créer** quelque chose de nouveau, ou une nouvelle ressource, on utilise le verbe HTTP **POST** (publier). Qu’il s’agisse d’un nouveau tweet, d’une nouvelle photo ou d’une nouvelle publication. Par exemple, dès que vous remplissez un formulaire en ligne ou que vous en utilisez un pour vous inscrire et vous créer un nouveau compte, le verbe associé par défaut est POST.

Comment l’API sait-elle ce qu’on essaie de **créer** quelque chose ? 

C’est là qu’intervient le **body**  ! Vous vous souvenez ? On l’a vu dans les chapitres précédents. Le body accompagne les requêtes POST et PUT pour contenir des informations supplémentaires. Vous pouvez intégrer les données que vous voulez créer dans le body de votre requête en utilisant du **JSON**.

Mettons tout ça en pratique ; je vous assure que ça fera sens !

On veut créer un nouveau repo sur GitHub pour notre API. Super, mais comment faire ? 1re étape : la documentation !

Regardons ce que nous dit la documentation GitHub au sujet des repositories : https://developer.github.com/v3/repos


Houlà, on a beaucoup de choix ! Nous, ce qu’on veut, c’est créer un nouveau repo.

Cliquez en bas à droite sur [[https://docs.github.com/en/rest/reference/repos#create-a-repository-for-the-authenticated-user|Create a repository for the authenticated user]].


Pour créer un nouveau repository, il faut faire une requête **POST** vers ''/user/repos''.

Parfait, on avance ! Maintenant, scrollez un peu et vous tomberez sur les paramètres.

La documentation indique que le paramètre **name** est obligatoire.

Mais ce n’est pas tout ! La documentation nous donne un exemple de requête et de réponse réussies.


Nous avons notre endpoint, notre verbe http, nos paramètres et même un exemple ! Allons faire cette requête. Lancez Postman !

Sélectionnez POST dans le menu déroulant puis tapez l’endpoint pour créer un nouveau repo via l’API GitHub: https://api.github.com/user/repos ; et appuyez sur Send.

Un message d'erreur est affiché.

Arf, mais on a une erreur. Qu’est-ce que c’est ? 🤔

Le message nous indique qu’une authentification est nécessaire. Le code de réponse HTTP est 401 : Unauthorized (401 Non autorisé). Eh oui, notre token !

Reprenez votre token d’authentification API GitHub, celui que vous avez précieusement gardé. Ajoutez-le, comme sur l’image suivante, dans l’onglet Headers sous forme de clé-valeur où la clé sera ''Authorization'' et la valeur sera votre token. Si mon token est abcde, alors la valeur sera : token abcde.

Ensuite, appuyez sur Send et regardez la réponse. 

{{postman_ajout_token.png|Statut de la requête avec le token : à droite}}
Statut de la requête avec le token


Encore une erreur ?! Mmmh... on a le bon endpoint, le token. Cette fois-ci, le code de réponse HTTP est : 400 Bad Request. Mais oui ! Il nous manque les paramètres 🙄. Eh oui, on demande à GitHub de nous créer un repo, mais on ne lui donne pas les informations.

Cliquez sur l'onglet ''Body'', puis sur Raw, binary et sélectionnez JSON.

{{postman_ajout_body.png|Interface affichée depuis l'onglet Body. JSON est affiché et encadré dans une liste déroulante.}}
Interface affichée depuis l'onglet Body. JSON est affiché et encadré dans une liste déroulante.


Maintenant, on peut ajouter nos paramètres sous forme de clé-valeur. Il nous faut un nom de repo qui est obligatoire, et ajoutons une description.


<code json>
{
   "name": "OpenClassrooms API",
   "description": "Nouveau repo !"
}
</code>

Appuyez sur Send et observez la réponse.


Wooohooo, notre repository a été créé. Le code de réponse HTTP est bien 201 Created. L’API nous renvoie les informations du nouveau repo crée. On peut aussi vérifier sur GitHub si le repo apparaît bien dans notre liste, et c’est le cas !


Pour **créer** un repo GitHub en utilisant l’API GitHub, nous avons :

  * consulté la documentation GitHub pour trouver l'endpoint adapté : POST user/repos ;
  * ajouté notre token d’authentification à nos paramètres dans le header avec Postman ;
  * ajouté les détails de notre repo à notre body en JSON avec Postman ;
  * vu qu’une fois que nous avons effectué une requête réussie avec notre API, le repo est apparu sur l’UI de notre profil GitHub !

Et voilà ! Vous avez un nouveau repo ! Et si maintenant on essayait de le modifier avec l’API GitHub ?

===== Mettez à jour un repo GitHub avec les méthodes PUT/PATCH =====

Vous avez **créé** votre repo GitHub, mais la description ne vous plaît plus trop, vous changez d’avis et vous voulez la modifier ! Vous pouvez utiliser **PUT** pour **mettre à jour** une ressource déjà existante dans votre API.

Sur Internet, on croise souvent PUT avec PATCH ? Les deux signifient la même chose ou est-ce qu’ils sont différents ?

  * PUT : met à jour la ressource complète (c’est-à-dire, remplace tout).
  * PATCH : met à jour uniquement la partie de la ressource qui a été envoyée.

On ne va pas s’attarder ici sur la différence entre les deux. Mais si vous ne savez pas lequel utiliser et pour quelle situation : consultez la documentation de l’API !

Et c’est ce que nous allons faire ! Reprenons la documentation des repos GitHub mais cette fois-ci cliquons sur [[https://docs.github.com/en/rest/reference/repos#update-a-repository|Update a repository]].

Pour mettre à jour un repo, il nous faut utiliser la méthode PATCH sur l’endpoint ''/repos/:Owner/:repo''.

Les deux points ( : ) devant owner et repo signifient qu’il nous faut l’identifiant unique du repository que vous voulez modifier, et celui du owner (propriétaire) du repo : vous, en l'occurrence.

Changez le verbe par PATCH. Puis entrez l’endpoint correspondant. Mon username est Kadaaran et mon repo se nomme OpenClassrooms-API. Changez Kadaaran par votre username et OpenClassrooms-API par votre nom de repo s’il est différent. Dans la section Body, tapez une nouvelle description. Dans mon cas, j’ai mis : Paragraphe ci-dessus à revoir.

<code json>
{
   "description": "Ceci est une nouvelle description plus cool que la précédente ☀️"
}
</code>

Appuyez sur Send et regardez la réponse.

Notre repo a été mis à jour ! Nous obtenons la réponse avec le body : le code de réponse HTTP est bien 200 OK.

Vous pouvez vérifier sur GitHub et vous devriez voir votre nouvelle description apparaître.

Pour mettre à jour un repo GitHub, nous avons :

  * vérifié la documentation GitHub pour l’URI approprié : PATCH /repos/wner/:repo 
  * utilisé Postman, changé notre verbe HTTP en PATCH, et saisi le propriétaire et le nom de repository que nous voulons modifier, ainsi que changé la description dans le body ;
  * vu la nouvelle description de notre repository dans notre UI GitHub

Bravo ! Vous avez créé un repo, puis vous l’avez modifié. Essayons à présent de le supprimer !

===== Supprimez votre repo GitHub avec la méthode DELETE =====

Vous décidez à présent que vous n’avez pas réellement besoin de votre repo GitHub – alors allez-y et supprimez-le avec DELETE !

Allez hop ! On reprend la même gymnastique que pour les requêtes précédentes. Tout d’abord : la documentation ! Comment supprime-t-on un repository GitHub ?

Dans la liste des méthodes disponibles, nous trouvons : Delete a repository. Cliquez dessus !


Selon la documentation, pour supprimer un repository GitHub, il nous faut utiliser le verbe DELETE sur l’endpoint ''/repos/Owner/:repo''. Si la requête est un succès, alors nous devrions avoir 204 No Content (204 Aucun contenu) comme réponse. Essayons avec Postman.


Tapez les informations nécessaires : votre username et le nom du repo que vous souhaitez supprimer. Pas besoin de body pour DELETE, cliquez sur none. Puis cliquez sur Send et regardez la réponse obtenue.

Le repo est supprimé : status : 204 no content est retourné.


Et voilà ! Votre repository est supprimé à tout jamais ! Nous obtenons un body vide et un statut 204 No Content comme l’a indiqué la documentation.

Vérifiez sur GitHub que votre repo a bien été supprimé.


Vous avez vu comment fonctionnent POST, PUT et DELETE et vous les avez vous-même utilisés avec l’API GitHub et Postman. Félicitations !

Vous les avez utilisés dans le contexte d’un repo GitHub, mais vous pouvez utiliser ces verbes HTTP pour tout type de fonctionnalité, en fonction de l’API.

  * Vous avez vu dans la documentation GitHub que l’URI correct est le même que pour Update, mais avec un nouveau verbe HTTP : DELETE /repos/:Owner/:repo.
  * Vous avez vu que notre repo est supprimé et ne se trouve plus dans notre UI GitHub !


===== En résumé =====

  * Vous pouvez utiliser POST pour créer des ressources.
  * PUT ou PATCH vous permet de mettre à jour des ressources.
  * DELETE vous permet de supprimer des ressources !

Dans la prochaine partie, nous allons étudier les meilleures pratiques lorsque vous concevez vous-même une API  ! Mais avant, il est temps de réviser ce que vous venez d’apprendre avec le quiz de fin de partie !



[[330_authentifier_une_api|◁ Précédent]] | ⌂ [[000_start|Retour au sommaire]] |  [[350_quizz|Suivant ▷]]
wikinotes

Outils pour utilisateurs

Outils du site

Outils de la page
