Concevoir une API REST : architecture et bonnes pratiques

Les principes fondamentaux REST

REST (Representational State Transfer) est un style d’architecture pour les API web. Ses principes fondamentaux garantissent des API prévisibles, scalables et maintenables.

Chez Lueur Externe, nous concevons des API REST pour les applications web et mobiles de nos clients.

Conventions d’URL

Nommage des ressources

GET    /api/v1/articles          → Liste des articles
GET    /api/v1/articles/42       → Article #42
POST   /api/v1/articles          → Créer un article
PUT    /api/v1/articles/42       → Remplacer l'article #42
PATCH  /api/v1/articles/42       → Modifier partiellement
DELETE /api/v1/articles/42       → Supprimer l'article #42

Règles de nommage

Noms au pluriel pour les collections (/articles, pas /article)
Minuscules et tirets (/blog-posts, pas /blogPosts)
Pas de verbes dans l’URL (le verbe HTTP suffit)
Relations imbriquées : /articles/42/comments

Codes de réponse HTTP

Code	Signification	Usage
200	OK	Requête réussie
201	Created	Ressource créée
204	No Content	Suppression réussie
400	Bad Request	Données invalides
401	Unauthorized	Non authentifié
403	Forbidden	Non autorisé
404	Not Found	Ressource inexistante
422	Unprocessable	Validation échouée
429	Too Many Requests	Rate limiting
500	Server Error	Erreur interne

Pagination

Pour les collections volumineuses, implémentez la pagination :

{
  "data": [...],
  "meta": {
    "total": 150,
    "page": 2,
    "per_page": 20,
    "last_page": 8
  },
  "links": {
    "first": "/api/v1/articles?page=1",
    "prev": "/api/v1/articles?page=1",
    "next": "/api/v1/articles?page=3",
    "last": "/api/v1/articles?page=8"
  }
}

Authentification

JWT (JSON Web Tokens)

Le standard pour les API stateless :

Authorization: Bearer eyJhbGciOiJIUzI1NiIs...

Bonnes pratiques

Tokens à durée de vie courte (15 min) + refresh tokens
HTTPS obligatoire
Rate limiting par utilisateur
Rotation des clés de signature

Gestion des erreurs

Retournez des erreurs structurées et exploitables :

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Les données fournies sont invalides",
    "details": [
      {
        "field": "email",
        "message": "Format d'email invalide"
      }
    ]
  }
}

Versioning

Préfixez vos URL avec la version majeure :

/api/v1/articles
/api/v2/articles

Maintenez la rétrocompatibilité au sein d’une version majeure. Les changements cassants nécessitent une nouvelle version.

Documentation OpenAPI

Documentez votre API avec la spécification OpenAPI (Swagger) :

openapi: 3.0.3
info:
  title: API Blog
  version: 1.0.0
paths:
  /articles:
    get:
      summary: Liste des articles
      parameters:
        - name: page
          in: query
          schema:
            type: integer
      responses:
        '200':
          description: Liste paginée d'articles

Performance

Cache HTTP : Cache-Control, ETag, Last-Modified
Compression : Gzip/Brotli sur les réponses
Champs sélectifs : ?fields=title,date,author
Inclusion : ?include=comments,author pour réduire les requêtes

Conclusion

Une API REST bien conçue est un investissement durable. Elle facilite l’intégration, la maintenance et l’évolution de votre application. Lueur Externe conçoit des API robustes et documentées pour ses clients.