API Rest Qu'est-ce que c'est - étape par étape avec des exemples

Voulez-vous construire une API REST, mais ne trouvez que de la théorie abstraite sur le « transfert d'état » et les « protocoles » ? Changeons cela. Cet article est un tutoriel pratique. Concevons, sur papier, une véritable [API REST] pour un Gestionnaire de tâches (To-Do List).

À la fin de ce guide, vous comprendrez exactement comment structurer les URL, utiliser les verbes HTTP corrects et concevoir des réponses JSON professionnelles.

Le scénario

Créons une API pour gérer les tâches. Une tâche a : id, titulo, descricao et concluida (vrai/faux).

Étape 1 : Définir les ressources (noms)

En REST, on pense « Ressources ». La ressource principale ici est la Tâche. Les URL (Endpoints) doivent représenter ces ressources à l'aide de noms au pluriel.

✅À droite : /tarefas
❌ Faux : /pegarTarefas, /criarNovaTarefa

L'URL identifie CE que vous manipulez. Le verbe HTTP identifie L'ACTION.

Étape 2 : Répertorier et créer (La collection)

Comment interagissons-nous avec la liste complète des tâches ?

Lister toutes les tâches

Demande : GET /tarefas
Signification : "Hé serveur, donne-moi la liste complète."
Réponse (200 OK) :

[
  { "id": 1, "titulo": "Comprar leite", "concluida": false },
  { "id": 2, "titulo": "Lavar o carro", "concluida": true }
]

Créer une nouvelle tâche

Réquisition : POST /tarefas
Corps envoyé :

{ "titulo": "Estudar REST", "descricao": "Ler o tutorial completo" }

Signification : "Hé serveur, ajoute ceci à la collection."
Réponse (201 créé) : Le serveur doit renvoyer l'objet créé, maintenant avec l'ID généré.

{ "id": 3, "titulo": "Estudar REST", "descricao": "Ler o tutorial completo", "concluida": false }

Étape 3 : Gérer un élément spécifique

Nous voulons maintenant modifier la tâche ID 3.

Lire une tâche spécifique

Réquisition : GET /tarefas/3
Réponse (200 OK) : renvoie uniquement l'objet de la tâche 3.
Et s'il n'existe pas ? : Réponse 404 Not Found. (Très important d'utiliser le bon code d'erreur !).

Mettre à jour une tâche (édition complète)

Réquisition : PUT /tarefas/3
Corps :

{ "titulo": "Estudar API REST", "descricao": "Atualizado", "concluida": true }

Remarque : PUT remplace généralement l'objet entier. Si vous envoyez uniquement le titre, le reste peut être supprimé (cela dépend de l'implémentation, mais c'est la règle PUT).

Mettre à jour partiellement (PATCH)

Pour juste changer le statut en terminé, sans renvoyer le titre.

Réquisition : PATCH /tarefas/3
Corps : { "concluida": true }
Signification : "Modifier ce champ uniquement".

Supprimer une tâche

Réquisition : DELETE /tarefas/3
Réponse (204 sans contenu) : succès, mais n'a rien à montrer en retour.

Étape 4 : Filtrage et pagination

Et si nous avions 10 000 tâches ? GET /tarefas ferait planter l'application. Nous utilisons les Paramètres de requête (ce qui suit ?) pour filtrer. Cela ne change pas l'URL de la ressource, cela filtre simplement sa vue.

Pagination : GET /tarefas?pagina=2&limite=10
Filtre : GET /tarefas?concluida=true (Donnez-moi simplement ceux complétés).
Recherche : GET /tarefas?busca=leite

Codes d'état HTTP (Commentaires)

Une API RESTful doit utiliser des codes HTTP pour vous indiquer ce qui s'est passé. Ne renvoyez pas toujours 200 avec {"erro": "deu ruim"} en JSON. Cela casse les outils de surveillance.

200 OK : Cela a fonctionné.
201 Créé : J'ai créé avec succès la ressource (utilisée dans le POST).
204 No Content : Cela a fonctionné, mais je n'ai rien à vous montrer (utilisé dans DELETE).
400 Bad Request : Vous avez envoyé des données erronées (par exemple, le titre manquait).
401 Non autorisé : Qui êtes-vous ? (Jeton manquant).
403 Forbidden : Je sais qui vous êtes, mais vous n'avez pas le droit de jouer avec ça.
404 Not Found : je ne l'ai pas trouvé.
Erreur interne du serveur 500 : Le serveur a explosé (erreur du développeur backend).

Conclusion

Concevoir une API REST est une question d'organisation et de standardisation. En suivant ce modèle (noms dans l'URL, verbes HTTP dans l'action, codes de statut corrects), vous créez une API que tout développeur dans le monde comprend intuitivement, sans avoir à lire un manuel de 500 pages.

C'est maintenant votre tour : prenez ce modèle et appliquez-le à votre prochain projet !