GETLire une ressource | Oui | GET /users/123
POST | Créer une ressource | Non | POST /users
PUT | Remplacer entièrement | Oui | PUT /users/123
PATCH | Modifier partiellement | Non | PATCH /users/123
DELETE | Supprimer | Oui | DELETE /users/123
Statuts HTTP
- Codes standardisés indiquant le résultat du traitement de la requête :
- 2xx (Succès):
200 OK, 201 Created, 204 No Content
- 3xx (Redirection):
301 Moved Permanently, 304 Not Modified (cache)
- 4xx (Erreur client):
400 Bad Request, 401 Unauthorized, 403 Forbidden, 404 Not Found, 429 Too Many Requests
- 5xx (Erreur serveur):
500 Internal Server Error, 502 Bad Gateway, 503 Service Unavailable
Authentification & Autorisation
Bonnes pratiques de conception
- Versionner explicitement les endpoints (
/v1/, /v2/)
- Forcer HTTPS et valider/sanitizer toutes les entrées
- Implémenter la pagination, le filtrage et le tri cohérents
- Appliquer du Rate Limiting et retourner les headers
X-RateLimit-*
- Documenter avec OpenAPI/Swagger et fournir un bac à sable (sandbox)
- Retourner des erreurs structurées :
{ "error": { "code": "INVALID_INPUT", "message": "...", "details": [] } }
API REST
Principes REST
- Architecture client-serveur : séparation des responsabilités.
- REST sépare les tâches du client et du serveur, offrant ainsi une répartition claire des responsabilités.
- Le client est responsable de l'interface et de l'expérience utilisateur, tandis que le serveur gère le stockage, le traitement et la logique applicative des données.
- Cette séparation améliore l'évolutivité et la flexibilité.
- Communication sans état: chaque requête contient toutes les infos nécessaires.
- REST suit un modèle de communication sans état où chaque requête d'un client vers un serveur contient toutes les informations nécessaires à sa compréhension et à son exécution. Cette absence d'état simplifie l'implémentation du serveur et améliore l'évolutivité.
- Cacheable : possibilité de mettre en cache.
- REST favorise l'utilisation de mécanismes de mise en cache pour améliorer les performances et réduire la charge des serveurs. Les réponses du serveur peuvent être explicitement marquées comme pouvant être mises en cache ou non, ce qui permet aux clients d'optimiser la récupération des données.
- Interface uniforme : méthodes HTTP standardisées.
- REST utilise une interface uniforme et cohérente, mettant l'accent sur les conventions standard pour l'identification et la manipulation des ressources, simplifiant l'interaction entre les clients et les serveurs, offrant une expérience de développement plus simple et plus stable.
- Architecture basée sur les ressources :
REST est centré sur les ressources, qui peuvent être n'importe quelle entité ou concept doté d'un identifiant unique. Chaque ressource est identifiée par un identifiant de ressource uniforme (URI), et les interactions reposent sur les méthodes HTTP standard de manipulation des ressources.
Méthodes HTTP courantes
| Méthode | Action | Description |
|---|
| GET | Read | Récupérer des données |
| POST | Create | Créer une ressource |
| PUT | Update | Modifier une ressource |
| DELETE | Delete | Supprimer une ressource |
| PATCH | Partial Update | Modifier partiellement |
Structure des endpoints
GET /users # Récupérer tous les utilisateurs
GET /users/1 # Récupérer l’utilisateur ID=1
POST /users # Créer un nouvel utilisateur
PUT /users/1 # Modifier l’utilisateur ID=1
DELETE /users/1 # Supprimer l’utilisateur ID=1
Formats de données
- JSON (le plus courant)
- XML
- Form Data (pour les formulaires)
Exemple de consommation avec JavaScript
// GET - Récupérer des données
async function fetchUsers() {
const response = await fetch('https://api.example.com/users');
const users = await response.json();
console.log(users);
}
// POST - Créer un utilisateur
async function createUser(userData) {
const response = await fetch('https://api.example.com/users', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify(userData)
});
const newUser = await response.json();
console.log('Utilisateur créé:', newUser);
}
API GraphQL
Qu’est ce que GraphQL ?
- Selon la définition officielle, GraphQL est un langage de requêtes pour API ainsi qu’un environnement pour exécuter ces requêtes. Il est défini par une spécification indépendante des langages de programmation et des protocoles de transport, dans le but de s’inscrire comme un nouveau standard dans le développement d’API.
Concepts fondamentaux
- Query : lire des données.
- Les requêtes GraphQL permettent aux clients de définir précisément les données dont ils ont besoin, éliminant ainsi les problèmes courants de récupération excessive ou insuffisante des API REST. Cette récupération précise des données garantit l'efficacité et optimise les performances du réseau.
- Mutation : écrire/modifier.
- Alors que les requêtes visent à récupérer des données, les mutations visent à les modifier. Leur fonctionnement est similaire à celui des requêtes, mais elles permettent de créer, de mettre à jour ou de supprimer des ressources, permettant ainsi une interaction dynamique avec les données.
- Subscription : mises à jour temps réel.
- Schema : définition des types.
- Le Schema définit les types de données interrogeables et sert de contrat entre le client et le serveur, garantissant que les clients ne peuvent demander que les données que le serveur est capable de fournir. Cette approche basée sur le schéma garantit la cohérence et la clarté du processus d'échange de données.
- Resolver : exécution des requêtes.
- Les résolveurs sont des fonctions spécialisées chargées de récupérer les données demandées dans chaque champ d'une requête. Ils peuvent extraire des données de diverses sources, notamment des bases de données, d'autres API ou tout autre stockage de données externe, garantissant ainsi que les informations demandées sont fournies avec exactitude au client.
Exemple de requête
Exemple de consommation en Flutter/dart
- Voici un petit exemple avec le package
graphql_flutter
import 'package:flutter/material.dart';
import 'package:graphql_flutter/graphql_flutter.dart';
void main() async {
await initHiveForFlutter(); // nécessaire pour le cache de graphql_flutter
runApp(const MyApp());
}
class MyApp extends StatelessWidget {
const MyApp({super.key});
@override
Widget build(BuildContext context) {
final HttpLink httpLink = HttpLink("https://api.example.com/graphql");
ValueNotifier<GraphQLClient> client = ValueNotifier(
GraphQLClient(
link: httpLink,
cache: GraphQLCache(store: HiveStore()),
),
);
return GraphQLProvider(
client: client,
child: const MaterialApp(
debugShowCheckedModeBanner: false,
home: UsersPage(),
),
);
}
}
class UsersPage extends StatelessWidget {
const UsersPage({super.key});
final String query = """
query GetUsers {
users {
id
name
email
}
}
""";
@override
Widget build(BuildContext context) {
return Scaffold(
appBar: AppBar(title: const Text("Liste des utilisateurs")),
body: Query(
options: QueryOptions(document: gql(query)),
builder: (QueryResult result, {fetchMore, refetch}) {
if (result.isLoading) {
return const Center(child: CircularProgressIndicator());
}
if (result.hasException) {
return Center(child: Text("Erreur: ${result.exception.toString()}"));
}
final users = result.data?['users'] ?? [];
return ListView.builder(
itemCount: users.length,
itemBuilder: (context, index) {
final user = users[index];
return ListTile(
leading: CircleAvatar(child: Text(user['id'].toString())),
title: Text(user['name']),
subtitle: Text(user['email']),
);
},
);
},
),
);
}
}
Comparaison REST vs GraphQL
| Aspect | REST | GraphQL |
|---|
| Structure | Multiples endpoints | Un seul point d’entrée |
| Données | Fixes (overfetch/underfetch) | Précises (seulement ce qu’il faut) |
| Versioning | URL ou headers | Évolution naturelle |
| Documentation | Swagger/OpenAPI | Introspection du schema |
- Si votre application nécessite des mises à jour de données en temps réel (par exemple, une application de chat en direct) ou implique des systèmes complexes nécessitant des requêtes d'ensembles de données spécifiques, GraphQL pourrait être le meilleur choix. Pour les applications plus simples où les opérations CRUD (Création, Lecture, Mise à jour, Suppression) standard suffisent, REST pourrait être plus approprié.
Outils et bibliothèques
REST
- Fetch API
- Axios
- Postman
- Swagger/OpenAPI
GraphQL
- Apollo Client
- Relay
- GraphiQL
- Hasura
Bonnes pratiques
REST
- Bien utiliser les méthodes HTTP.
- Versionner l’API.
- Mettre en place pagination, filtres, tri.
- Gestion correcte des erreurs.
GraphQL
- Utiliser des fragments pour réutiliser du code.
- Pagination basée sur des curseurs.
- Optimistic UI pour améliorer l’expérience.
- Utiliser des directives conditionnelles.
Sécurité
Méthodes d’authentification
- API Keys
- JWT
- OAuth 2.0
- Basic Auth
Bonnes pratiques
- Validation des entrées côté client et serveur.
- Rate limiting.
- HTTPS obligatoire.
Exercices pratiques
Exercice 1 : Consommation d’API REST- Utiliser
JSONPlaceholder pour afficher, créer, modifier et supprimer des utilisateurs.
- JSONPlaceholder est une API REST gratuite et publique utilisée principalement pour l’apprentissage, les tests et le prototypage.
- Utile pour tester des requêtes HTTP sans avoir besoin de créer sa propre API.
- Supporte les principales méthodes HTTP :
GET → Lire des donnéesPOST → Créer une ressourcePUT → Modifier une ressourcePATCH → Modifier partiellement une ressourceDELETE → Supprimer une ressource
- L’API propose plusieurs collections :
/posts → articles de blog/comments → commentaires/albums → albums/photos → photos/todos → tâches/users → utilisateurs
Exercice 2 : Migration vers GraphQL- Reprendre l’exercice 1 et le migrer en GraphQL.
Exercice 3 : Application complète- Application de gestion de tâches avec API REST ou GraphQL + Authentification JWT.
Conclusion
- La consommation d’API REST et GraphQL est une compétence incontournable.
- REST est simple et bien établi, GraphQL est flexible et efficace.
- Le choix dépend des besoins et de la complexité de l’application.
|