les bonnes

pratiques pour concevoir une API

professionnelle
Share Skill Session

Présenté par Dimitri

Chef Département d’Innovation Digitale
Au programme de cette session

01 Qu'est-ce qu'une API ?

La définition et pourquoi ça compte

Qu'est-ce que l'API Design ?

02 Le processus de conception intentionnelle

Protocoles & Styles

03 REST, GraphQL, SOAP, gRPC…

Les 4 étapes clés

04 Plan → Develop → Test → Deploy

Bonnes pratiques
05 Nommage, versioning, erreurs, sécurité…

Q&R & Recap

06 Questions, synthèse et ressources
Au programme de cette session

01 Qu'est-ce qu'une API ?

La définition et pourquoi ça compte

Qu'est-ce que l'API Design ?

02 Le processus de conception intentionnelle

Protocoles & Styles

03 REST, GraphQL, SOAP, gRPC…

Les 4 étapes clés

04 Plan → Develop → Test → Deploy

Bonnes pratiques
05 Nommage, versioning, erreurs, sécurité…

Q&R & Recap

06 Questions, synthèse et ressources
Objectifs de cette session
 Définir ce qu’une API n’est pas ?

Un logiciel : un logiciel n’est pas une API (même s’il peut se présenter sous la
forme d’une API pour faciliter l’utilisation de ses fonctionnalités).

Une interface utilisateur : une interface utilisateur n’est pas une API (mais
elle peut s’exécuter sur une interface utilisateur)

Un serveur : un serveur n’est pas une API (mais il peut héberger une ou plusieurs
API qui fournissent les données et fonctions mises à disposition par le serveur).
Qu’est ce qu’une API ?

Une API (Application Programming

Interface ou « interface de
programmation d'application ») est une
interface logicielle qui permet de «
connecter » un logiciel ou un service à un
autre logiciel ou service afin d'échanger
des données et des fonctionnalités.
Une API comme un produit

Comme une API est un produit, avant d’en développer une,

posez vous ces questions clés :

✓ Quels consommateurs visez-vous ?

✓ Comment allez-vous toucher ces consommateurs ?

✓ Dans quelles conditions ces consommateurs peuvent-ils

utiliser cette API ?
Pourquoi nous avons besoin d’une API ?

Les API sont essentielles à la création de systèmes évolutifs, flexibles et connectés. Voici
pourquoi les développeurs
s'appuient sur elles :
Réutilisabilité : Évitez de réinventer la roue en tirant parti des API existantes (par
exemple, l'API Google Maps,
l'API Stripe Payments).
Efficacité : Gagnez du temps de développement en intégrant des fonctionnalités prêtes à
l'emploi.
Évolutivité : Permettre la mise en place de systèmes modulaires et distribués, capables de
s'étendre facilement.
Intégration : Connectez plusieurs plateformes web, mobiles, IoT ou analytiques.
Automatisation : les API permettent aux machines de communiquer entre elles sans
intervention manuelle.
Exemple quotidien d’une API

 Bibliothèque logicielle

 Pilote de matériel

 API web
 Exemple quotidien d’une API
API de bibliothèque logicielle
Un programme qui utilise l’API de la bibliothèque json pour
• Bibliothèque écrire un fichier
logicielle .json

• Pilote de matériel import json

data = {
• API web "nom": "John",
"age": 30,
"ville": "Paris"
}
# Écriture du dictionnaire dans un fichier JSON
with open("[Link]", "w") as f:
[Link](data, f)
 Exemple quotidien d’une API

API d’un matériel

• Bibliothèque Un programme qui utilise une API pour activer un
logicielle signal sur un port GPIO

• Pilote de matériel
import [Link] as GPIO
• API web [Link]([Link])
[Link](17, [Link])
# On envoie un signal de force maximale
sur le pin 17
[Link](17, [Link])
 Exemple quotidien d’une API

API WEB
• Bibliothèque Un programme qui utilise l’API de la BAN pour faire
logicielle du géocodage

• Pilote de matériel Curl'https [Link]/geocodage/se

arch?q=Refuge%20 c
• API web du%20pelvoux&limit=1&index=poi&returntr
uegeometry='
 Les différentes types d’API

Les APIs sont classées selon leurs modèles d'utilisation et leurs architectures.
Types d'API selon leur finalité
API interne : Ce type d’API est utilisé uniquement par certaines personnes et reste
invisible aux utilisateurs externes. Définie pour des services spécifiques de
l’entreprise, elle est généralement réservée à la réutilisation et à la production.
API ouvertes : API accessibles aux développeurs et à tous. Elles sont également
appelées API publiques. On distingue deux types d’API : payantes et gratuites.
API partenaires : Les API qui permettent aux systèmes d’entreprises partenaires de
coordonner leurs opérations communes sont appelées API partenaires. Elles ne
sont pas accessibles à tous. Par exemple, la communication entre un site de
commerce électronique et une entreprise de transport de marchandises s’effectue
via une API partenaire.
API composite : Les API composites sont des API qui combinent plusieurs API de
données ou de services, permettant aux développeurs d’accéder à plusieurs points
de terminaison en un seul appel
Les styles d'architecture API

REST GraphQL gRPC SOAP

Le plus répandu Flexible Haute perf. Legacy

✓ Avantages ✓ Avantages ✓ Avantages ✓ Avantages

• Simple & stateless • Requêtes précises • Très performant • Standard strict

• Streaming
• HTTP natif • Typage fort • WS-Security
bidirectionnel
• Large adoption • Introspection • Code généré

✗ Limites ✗ Limites ✗ Limites ✗ Limites

• Over/Under-
• Complexité serveur • Moins lisible • Verbeux XML
fetching
• Lourd à
• Versioning • Caching difficile • Outils limités
implémenter
complexe
Fonctionnement d’une API en générale
Pourquoi un bon design API est cruciale ?

80% 3× 30%
des développeurs abandonnent plus rapide avec une des tickets support liés
une API mal documentée bonne API que sans à une API mal conçue

Accélère le Favorise la
Ouvre l'écosystème Sécurise les échanges
développement modularité
Réutilisation des services Découplage des Intégrations partenaires et
Contrôle d'accès centralisé
entre équipes composants système third-party
Qu'est-ce que l'API Design ?
Concevoir intentionnellement avant de coder

L'API Design est le processus de prise de décisions intentionnelles sur la façon

dont une API expose ses données et fonctionnalités à ses consommateurs.

Meilleure qualité Alignement des équipes

Des APIs bien conçues dès le départ sont plus Design = langage commun entre développeurs,
stables, plus simples à utiliser et moins product managers et consommateurs de l'API.
coûteuses à maintenir.

Gouvernance & Standards Time-to-market réduit

IBM et Postman insistent : le design est la base En définissant le contrat en amont, les équipes
de toute stratégie de gouvernance API à front et back peuvent travailler en parallèle —
l'échelle de l'organisation. les mocks remplacent le vrai serveur.
Les 4 étapes clés du processus
un processus collaboratif de bout en bout

01 02 03 04

PLAN DEVELOP TEST DEPLOY

Aligner toutes les

Définir les endpoints, Créer des mock Déployer avec une
parties prenantes sur
le modèle de données, servers pour valider le documentation
le cas d'usage, les
les méthodes HTTP, la comportement. Tester finalisée. Avoir une
objectifs business et
sécurité, les codes : contrats, unitaire, stratégie de
les contraintes.
d'erreur. Écrire la charge, end-to-end. versioning claire avant
Répondre à : Pourquoi
spécification Identifier les bugs le lancement pour
cette API ? Pour qui ?
OpenAPI/AsyncAPI. avant la prod. gérer les futures
Quelles données ?
évolutions.
→ Livrable : Description → Livrable : Fichier de
→ Livrable : Rapport de → Livrable : API en prod +
en langage naturel du spécification (contrat
tests + mock servers documentation publique
comportement attendu API)
validés
 Les principes fondamentaux du REST API

Client-Serveur Sans état (Stateless) Cache

Séparation des Chaque requête est Les réponses doivent

responsabilités. Le frontend indépendante. Pas de indiquer si elles sont
ne doit pas connaître la DB. session serveur. Le client cachables. Réduit la charge.
envoie tout le contexte.

Interface Uniforme Système en couches Code à la demande

URIs logiques, verbes HTTP Le client ne sait pas s'il parle (Optionnel) Le serveur peut
standards, format JSON à un proxy, un CDN ou envoyer du code exécutable
cohérent partout. directement au serveur. au client (scripts JS).
Les Verbes HTTP CRUD → REST
Verbe CRUD Description Exemple Idempotent / Safe
Idempotent
GET Read Récupérer une ressource GET /api/v1/products
Safe

Non idempotent
POST Create Créer une nouvelle ressource POST /api/v1/products
Non safe

Idempotent
Remplacer entièrement une
PUT Update (total)
ressource
PUT /api/v1/products/5
Non safe

Selon impl.
Modifier partiellement une
PATCH Update (partiel)
ressource
PATCH /api/v1/products/5
Non safe

Idempotent
DELETE Delete Supprimer une ressource DELETE /api/v1/products/5
Non safe
 Nommage des Endpoints : Les Règles d'Or
Noms pluriels pour les collections Les collec ons con ennent plusieurs items → pluriel
1 GET /api/v1/users GET /api/v1/user

Hiérarchie logique pour les sous-ressources L'URL reflète la rela on parent → enfant
2
GET /orders/12/items/3 GET /getOrderItem?orderId=12&itemId=3

Kebab-case pour les URLs URLs en lowercase, tirets pour la lisibilité

3 GET /product-categories GET /productCategories ou /Product_Categories

Jamais de verbes dans les URLs Le verbe HTTP FAIT le travail, pas l'URL
4 DELETE /users/42 GET /deleteUser?id=42

Versioning dès le départ Permet de faire évoluer l'API sans casser les clients existants
5 GET /api/v1/products GET /products (sans version)
Codes de Statut HTTP : Parlez le bon langage
2xx — Succès

200 OK Réponse standard GET, PUT, PATCH réussie

201 Created POST réussi — ressource créée (+ header Location)
204 No Content DELETE réussi — rien à retourner

4xx — Erreur Client

400 Bad Request Requête malformée, données invalides

401 Unauthorized Non authentifié (pas de token / token expiré)
403 Forbidden Authentifié mais pas autorisé (rôle insuffisant)
404 Not Found La ressource demandée n'existe pas
422 Unprocessable Données comprises mais échouent la validation
429 Too Many Req. Rate limiting dépassé

5xx — Erreur Serveur

500 Internal Error Erreur inattendue côté serveur (bug, crash)

503 Unavailable Service temporairement indisponible (maintenance)
Structure des Réponses JSON & Pagination
Structure Recommandée (collection) À éviter

{ // Tableau brut sans enveloppe

"data": [ [
{ { "id": 1, "name": "Alice" },
"id": 1, { "id": 2, "name": "Bob" }
"name": "Alice", ]
"email": "alice@[Link]" // Pas de meta, pas de pagination → impossible
} // d'ajouter des infos sans casser les clients
],
"meta": {
"total": 150,
"page": 2,
Stratégies de Pagination
"per_page": 20,
Offset/Limit
"total_pages": 8
}, /users?page=2&per_page=20
"links": { → Simple, courant, adapté aux UIs classiques
"self": "/api/v1/users?page=2", Cursor
"next": "/api/v1/users?page=3", /users?cursor=eyJpZCI6MjB9&limit=20
"prev": "/api/v1/users?page=1" → Haute perf, pour flux infinis (feeds)
} Keyset
} /users?after_id=20&limit=20
→ Stable, évite les doublons sur données qui changent
Sécurité de l'API : Les Indispensables
Authentification JWT HTTPS Obligatoire Rate Limiting
Toujours TLS/SSL en production. Jamais
Header: Authorization: Bearer <token>
HTTP. Limiter le nb de requêtes par IP / par user
JWT = [Link] (base64)
→ Protège contre les attaques man-in- Ex: 100 requêtes / 15 minutes
→ Apatride, signé, non modifiable sans la
the-middle Réponse : HTTP 429 Too Many Requests
clé secrète
→ Redirect 301 automatique HTTP → Headers: X-RateLimit-Limit: 100 / X-
→ Expira on courte recommandée :
HTTPS RateLimit-Remaining: 42
15min (+ refresh token)
→ HSTS header pour forcer HTTPS

CORS Validation des Entrées Ne jamais exposer

TOUJOURS valider et sanitiser les données
Cross-Origin Resource Sharing Passwords en clair dans les réponses
reçues
Définir quels domaines peuvent appeler Stack traces en production (500 →
→ Injec on SQL : jamais de requête SQL
votre API message générique)
concaténée
Ne jamais mettre Access-Control-Allow- Clés API, secrets dans les URLs (dans
→ Schemas de valida on (Joi, Zod,
Origin: * en prod! le body !)
Pydantic...)
→ Whitelist explicite des domaines IDs séquentiels prévisibles (utiliser
→ Limiter la taille des payloads (ex: max
autorisés UUID)
5MB)
Documentation & Bonnes Pratiques Avancées
 OpenAPI / Swagger Filtrage, Tri, Recherche

Le standard de documentation d'API

→ Fichier YAML/JSON qui décrit chaque endpoint Filtrer : /products?category=phones&price_min=100
→ Swagger UI génère une doc interac ve
→ Testez directement dans le browser
→ Génère des SDKs automa quement Trier : /products?sort=price&order=asc

Exemple : GET /users/{id}: Champs :

summary: Get a user by ID /users?fields=id,name,email
parameters:
- in: path Recherche : /products?q=iphone+pro
name: id
required: true /products?category=phones&sort=price
Combiner :
&page=1&per_page=20&fields=id,name,price

HATEOAS (niveau expert) Checklist Pro avant déploiement

HTTPS ac vé + redirect HTTP→HTTPS

{
"id": 42, Authentication + Authorization en place
"status": "pending",
"_links": { Rate limiting configuré
"self": "/orders/42", Validation des inputs sur tous les endpoints
"cancel": "/orders/42/cancel",
"payment": "/orders/42/pay" Logs structurés (request ID, timestamp, status)
}
Documentation OpenAPI à jour
}
Tests d'intégration sur les endpoints critiques
 Récapitulatif
Les 6 piliers d'une API bien conçue
Cohérence des ressources et
1 2 Verbes HTTP sémantiques
URIs

3 Codes de réponse appropriés 4 Versioning dès le départ

Sécurité & authentification Documentation vivante

5 6
robuste (OpenAPI)

Ressources recommandées :

→ REST API Design Rulebook (Masse) → OpenAPI Spec 3.1 — [Link] → API Security Checklist (github) → [Link] — Docs officielles
Merci pour votre aimable attention!
Introduction au API Design
Des questions ?

Bonne chance dans vos projets API !