API JSON et services REST : Guide complet du développeur
Maîtrisez les API REST avec JSON. Apprenez les méthodes HTTP, l'authentification, la gestion des erreurs et les meilleures pratiques pour créer des API modernes.
Big JSON Team
• Technical WriterExpert in JSON data manipulation, API development, and web technologies. Passionate about creating tools that make developers' lives easier.
# API JSON et services REST : Guide complet du développeur
Les API REST avec JSON sont au cœur du développement web moderne. Ce guide complet vous apprend à créer, consommer et optimiser des services REST.
Qu'est-ce qu'une API REST ?
REST (Representational State Transfer) est un style d'architecture pour les services web utilisant HTTP et JSON comme format d'échange de données principal.
Principes REST
Méthodes HTTP
GET - Récupérer des données
\\\javascript
// Récupérer tous les utilisateurs
fetch('https://api.exemple.com/users')
.then(res => res.json())
.then(data => console.log(data));
// Réponse JSON
{
"users": [
{"id": 1, "nom": "Alice"},
{"id": 2, "nom": "Bob"}
]
}
// Récupérer un utilisateur spécifique
fetch('https://api.exemple.com/users/1')
.then(res => res.json())
.then(user => console.log(user));
// Réponse
{"id": 1, "nom": "Alice", "email": "alice@ex.com"}
\\\
POST - Créer une ressource
\\\javascript
const nouveauUtilisateur = {
nom: "Charlie",
email: "charlie@exemple.com",
age: 28
};
fetch('https://api.exemple.com/users', {
method: 'POST',
headers: {
'Content-Type': 'application/json'
},
body: JSON.stringify(nouveauUtilisateur)
})
.then(res => res.json())
.then(data => console.log(data));
// Réponse (201 Created)
{
"id": 3,
"nom": "Charlie",
"email": "charlie@exemple.com",
"age": 28,
"createdAt": "2026-01-16T10:00:00Z"
}
\\\
PUT - Mettre à jour (remplacement complet)
\\\javascript
const utilisateurMisAJour = {
nom: "Alice Dupont",
email: "alice.dupont@exemple.com",
age: 31
};
fetch('https://api.exemple.com/users/1', {
method: 'PUT',
headers: {'Content-Type': 'application/json'},
body: JSON.stringify(utilisateurMisAJour)
})
.then(res => res.json())
.then(data => console.log(data));
\\\
PATCH - Mise à jour partielle
\\\javascript
const modification = {
age: 32
};
fetch('https://api.exemple.com/users/1', {
method: 'PATCH',
headers: {'Content-Type': 'application/json'},
body: JSON.stringify(modification)
})
.then(res => res.json())
.then(data => console.log(data));
\\\
DELETE - Supprimer
\\\javascript
fetch('https://api.exemple.com/users/1', {
method: 'DELETE'
})
.then(res => {
if (res.status === 204) {
console.log('Utilisateur supprimé');
}
});
// Réponse (204 No Content) ou
{
"message": "Utilisateur supprimé avec succès"
}
\\\
Structure des réponses API
Format standard
\\\json
{
"status": "success",
"data": {
"user": {
"id": 1,
"nom": "Alice"
}
},
"meta": {
"timestamp": "2026-01-16T10:00:00Z",
"version": "1.0"
}
}
\\\
Pagination
\\\json
{
"data": [...],
"pagination": {
"page": 1,
"perPage": 20,
"total": 100,
"totalPages": 5,
"links": {
"first": "/users?page=1",
"prev": null,
"next": "/users?page=2",
"last": "/users?page=5"
}
}
}
\\\
Gestion des erreurs
\\\json
{
"status": "error",
"error": {
"code": "VALIDATION_ERROR",
"message": "Données invalides",
"details": [
{
"field": "email",
"message": "Format email invalide"
},
{
"field": "age",
"message": "L'âge doit être positif"
}
]
}
}
\\\
Codes de statut HTTP
2xx Succès
- 200 OK : Requête réussie
- 201 Created : Ressource créée
- 204 No Content : Succès sans contenu
4xx Erreurs client
- 400 Bad Request : Requête malformée
- 401 Unauthorized : Non authentifié
- 403 Forbidden : Non autorisé
- 404 Not Found : Ressource introuvable
- 422 Unprocessable Entity : Validation échouée
5xx Erreurs serveur
- 500 Internal Server Error : Erreur serveur
- 503 Service Unavailable : Service indisponible
Authentification
API Key
\\\javascript
fetch('https://api.exemple.com/users', {
headers: {
'X-API-Key': 'votre_cle_api_ici'
}
})
.then(res => res.json());
\\\
Bearer Token (JWT)
\\\javascript
const token = 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...';
fetch('https://api.exemple.com/users', {
headers: {
'Authorization': \Bearer ${token}\
}
})
.then(res => res.json());
\\\
OAuth 2.0
\\\javascript
// 1. Obtenir token
const tokenResponse = await fetch('https://api.exemple.com/oauth/token', {
method: 'POST',
headers: {'Content-Type': 'application/json'},
body: JSON.stringify({
grant_type: 'client_credentials',
client_id: 'votre_client_id',
client_secret: 'votre_secret'
})
});
const {access_token} = await tokenResponse.json();
// 2. Utiliser token
fetch('https://api.exemple.com/users', {
headers: {
'Authorization': \Bearer ${access_token}\
}
});
\\\
Créer une API REST (Node.js/Express)
\\\javascript
const express = require('express');
const app = express();
app.use(express.json());
let users = [
{id: 1, nom: "Alice", email: "alice@ex.com"},
{id: 2, nom: "Bob", email: "bob@ex.com"}
];
// GET tous les utilisateurs
app.get('/api/users', (req, res) => {
res.json({
status: 'success',
data: {users}
});
});
// GET un utilisateur
app.get('/api/users/:id', (req, res) => {
const user = users.find(u => u.id === parseInt(req.params.id));
if (!user) {
return res.status(404).json({
status: 'error',
error: {message: 'Utilisateur non trouvé'}
});
}
res.json({
status: 'success',
data: {user}
});
});
// POST créer utilisateur
app.post('/api/users', (req, res) => {
const {nom, email} = req.body;
// Validation
if (!nom || !email) {
return res.status(400).json({
status: 'error',
error: {message: 'Nom et email requis'}
});
}
const newUser = {
id: users.length + 1,
nom,
};
users.push(newUser);
res.status(201).json({
status: 'success',
data: {user: newUser}
});
});
// PUT mettre à jour
app.put('/api/users/:id', (req, res) => {
const user = users.find(u => u.id === parseInt(req.params.id));
if (!user) {
return res.status(404).json({
status: 'error',
error: {message: 'Utilisateur non trouvé'}
});
}
user.nom = req.body.nom;
user.email = req.body.email;
res.json({
status: 'success',
data: {user}
});
});
// DELETE supprimer
app.delete('/api/users/:id', (req, res) => {
const index = users.findIndex(u => u.id === parseInt(req.params.id));
if (index === -1) {
return res.status(404).json({
status: 'error',
error: {message: 'Utilisateur non trouvé'}
});
}
users.splice(index, 1);
res.status(204).send();
});
app.listen(3000, () => {
console.log('API running on port 3000');
});
\\\
Créer une API REST (Python/Flask)
\\\python
from flask import Flask, jsonify, request
from datetime import datetime
app = Flask(__name__)
users = [
{"id": 1, "nom": "Alice", "email": "alice@ex.com"},
{"id": 2, "nom": "Bob", "email": "bob@ex.com"}
]
@app.route('/api/users', methods=['GET'])
def get_users():
return jsonify({
"status": "success",
"data": {"users": users}
})
@app.route('/api/users/
def get_user(user_id):
user = next((u for u in users if u['id'] == user_id), None)
if not user:
return jsonify({
"status": "error",
"error": {"message": "Utilisateur non trouvé"}
}), 404
return jsonify({
"status": "success",
"data": {"user": user}
})
@app.route('/api/users', methods=['POST'])
def create_user():
data = request.get_json()
if not data.get('nom') or not data.get('email'):
return jsonify({
"status": "error",
"error": {"message": "Nom et email requis"}
}), 400
new_user = {
"id": len(users) + 1,
"nom": data['nom'],
"email": data['email']
}
users.append(new_user)
return jsonify({
"status": "success",
"data": {"user": new_user}
}), 201
if __name__ == '__main__':
app.run(debug=True, port=3000)
\\\
Meilleures pratiques
1. Versionnage
\\\
/api/v1/users
/api/v2/users
\\\
2. Nommage des endpoints
\\\
✓ /api/users (pluriel)
✓ /api/users/1
✓ /api/users/1/posts
✗ /api/getUsers
✗ /api/user
✗ /api/users/deleteUser
\\\
3. Filtrage et recherche
\\\
/api/users?age=30
/api/users?role=admin
/api/users?search=jean
/api/users?sort=nom&order=desc
\\\
4. Rate Limiting
\\\javascript
{
"error": {
"code": "RATE_LIMIT_EXCEEDED",
"message": "Trop de requêtes",
"retryAfter": 60
}
}
// Headers
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1642345200
\\\
5. CORS
\\\javascript
app.use((req, res, next) => {
res.header('Access-Control-Allow-Origin', '*');
res.header('Access-Control-Allow-Methods', 'GET, POST, PUT, DELETE');
res.header('Access-Control-Allow-Headers', 'Content-Type, Authorization');
next();
});
\\\
Tester les API
Avec cURL
\\\bash
# GET
curl https://api.exemple.com/users
# POST
curl -X POST https://api.exemple.com/users \
-H "Content-Type: application/json" \
-d '{"nom":"Charlie","email":"charlie@ex.com"}'
# PUT
curl -X PUT https://api.exemple.com/users/1 \
-H "Content-Type: application/json" \
-d '{"nom":"Alice Updated"}'
# DELETE
curl -X DELETE https://api.exemple.com/users/1
\\\
Avec Postman/Insomnia
Interface graphique pour tester les API facilement.
Conclusion
Points clés API REST :- Utiliser méthodes HTTP appropriées
- Structurer réponses JSON cohérentes
- Gérer erreurs explicitement
- Implémenter authentification
- Documenter l'API
Maîtrisez ces concepts pour créer des API REST modernes et robustes !
Articles Connexes
Python et JSON : Guide complet pour manipuler des données JSON
Maîtrisez la manipulation JSON en Python avec le module json. Apprenez à lire, écrire, parser et convertir des données JSON avec des exemples pratiques.
JavaScript et JSON : Guide complet de manipulation des données
Maîtrisez JSON en JavaScript avec JSON.parse(), JSON.stringify(), et techniques avancées. Guide pratique avec exemples pour le développement web moderne.
Comprendre JSON Schema : Validation et documentation des données
Maîtrisez JSON Schema pour valider vos données JSON. Guide complet avec exemples pratiques, types, validations et outils pour créer des schémas robustes.