Développement d'API personnalisées : le processus et son coût

Pourquoi la conception d'une API survit au code

Une fois qu'une API est utilisée, sa structure est figée. Vous pouvez tout réécrire derrière elle ; vous ne pouvez pas renommer un champ dont une application mobile en production dépend, car les anciennes versions restent sur les téléphones des utilisateurs pendant des années.

Cette asymétrie explique pourquoi le travail sur une API doit être axé sur la conception dès le départ. Une semaine passée à valider le contrat avant l'implémentation permet d'économiser bien plus de temps par la suite, car l'alternative consiste à gérer des versions pour corriger des décisions prises en une après-midi.

Le processus qui fonctionne

1. Inventaire des consommateurs

Qui appelle cette API, et de quoi ont-ils réellement besoin ? Une interface web, une application mobile, une intégration partenaire et un tableau de bord interne ont des exigences genuinely différentes. Les clients mobiles se soucient de la taille des charges utiles et des allers-retours, contrairement à un client web sur une connexion haut débit.

2. Contrat en premier

Rédigez la spécification — OpenAPI pour REST, un schéma pour GraphQL — et validez-la avant l'implémentation. Cela offre deux avantages immédiats : le travail front-end et back-end peut avancer en parallèle sur une version simulée, et les désaccords apparaissent lors de la revue du document plutôt qu'en phase de tests d'intégration.

3. Modélisation des ressources

Les points de terminaison doivent refléter votre domaine métier, et non vos tables de base de données. Exposer directement la structure des tables est pratique au début, mais devient une prison : chaque modification du schéma devient une modification cassante de l'API.

4. Authentification et autorisation

Décidez tôt, car les modifications ultérieures sont coûteuses :

• Clés API pour les accès serveur-à-serveur avec des partenaires
• OAuth 2.0 / OIDC lorsque les utilisateurs accordent l'accès à leurs propres données
• JWT à courte durée de vie avec jetons de rafraîchissement pour les applications tierces

Et gardez l'autorisation distincte de l'authentification. Savoir qui est un utilisateur ne vous indique pas quels enregistrements il peut consulter, et confondre les deux est une source fréquente de failles d'exposition de données.

5. Erreurs, pagination, versioning

Les aspects peu glamour qui déterminent si l'API est agréable à utiliser :

• Forme cohérente des erreurs avec un code lisible par machine et un message lisible par l'homme
• Pagination par curseur plutôt que par décalage, afin que les résultats restent stables malgré les modifications des données
• Versioning dès le premier jour — /v1/ ne coûte rien maintenant et évite une migration plus tard
• Limitation de débit avec des en-têtes clairs, pour que les consommateurs puissent ralentir plutôt que d'être coupés silencieusement

6. Documentation comme livrable

Référence générée plus des exemples concrets, incluant comment s'authentifier et ce que signifient les erreurs courantes. Si un développeur compétent ne peut pas effectuer un appel réussi dans les vingt minutes qui suivent la lecture, la documentation n'est pas terminée.

REST ou GraphQL

REST pour la grande majorité des projets. La mise en cache HTTP fonctionne, le débogage est simple, chaque développeur la connaît déjà, et les outils sont universels.

GraphQL lorsque vous avez plusieurs clients différents nécessitant des formes différentes des mêmes données, ou lorsque le surchargement sur les connexions mobiles représente un coût mesurable. Cela introduit une complexité réelle — mise en cache, limitation du coût des requêtes, protection contre les requêtes profondément imbriquées — qui doit être gérée activement.

Choisir GraphQL pour un seul client web revient généralement à ajouter de la complexité sans retour sur investissement. Choisir REST lorsque vous avez quatre clients chacun récupérant un sous-ensemble différent signifie soit de nombreux points de terminaison, soit beaucoup de données inutiles dans les charges utiles.

Ce que cela coûte réellement au Royaume-Uni

Périmètre	Fourchette typique
API ciblée, quelques ressources, authentification	£6,000 – £15,000
Intégration avec une API tierce documentée	£2,500 – £6,000
Intégration avec des systèmes hérités ou non documentés	£10,000 – £30,000
Passerelle API, limitation de débit, portail développeur	£8,000 – £20,000

Le schéma à retenir : le coût d'intégration dépend du système tiers, et non du vôtre. Une API moderne documentée prend une semaine. Un système hérité non documenté avec des données incohérentes et aucun environnement de test peut absorber un mois. C'est pourquoi nous évaluons ces cas sous forme de test limité dans le temps plutôt que de proposer un devis à l'aveugle — un prix fixe sur un système inconnu est une estimation que quelqu'un paiera tôt ou tard.

Intégration de systèmes hérités

La plupart des projets réels ne sont pas des projets neufs. Ils impliquent quelque chose d’ancien qui fait pourtant tourner l’activité.

S’il dispose d’une API, attendez-vous à ce qu’elle soit incohérente, lente et qu’elle limite les requêtes de manière non documentée. Protégez-vous : utilisez des relances avec exponentiation, des disjoncteurs et une file d’attente pour qu’une dépendance lente n’entraîne pas votre application dans sa chute.

S’il n’a pas d’API, les options par ordre décroissant de robustesse sont : un échange de fichiers planifié (CSV ou XML via SFTP), une intégration en lecture seule de la base de données si le fournisseur l’autorise, ou — dans des cas contraints — l’automatisation de processus robotisés (RPA) pilotant l’interface. Cette dernière est véritablement fragile et se brise dès que le fournisseur modifie un écran. Nous la mettrons en place si c’est la seule solution, tout en étant clairs sur ce que vous acceptez.

Ajoutez toujours une couche anti-corruption. Traduisez le modèle du système hérité dans le vôtre à la frontière plutôt que de laisser ses particularités se propager dans votre codebase. Cette seule décision détermine si le remplacement du système hérité plus tard sera un projet ou une épreuve.

Erreurs courantes

1. Exposer des tables de base de données comme des points de terminaison — lie définitivement votre API à votre schéma
2. Pas de versionnage — la première modification incompatible devient une urgence
3. Authentification ajoutée a posteriori — entraîne invariablement une réécriture de chaque point de terminaison
4. Pas de limitation de débit — un consommateur mal écrit met le service hors service pour tout le monde
5. Erreurs incohérentes — chaque consommateur écrit une gestion sur mesure par point de terminaison
6. Documentation rédigée en dernier — donc mal écrite ou inexistante

Ce à quoi ressemble une bonne livraison

• Spécification OpenAPI validée avant le début de l’implémentation
• Tests automatisés couvrant le contrat documenté
• Authentification et autorisation comme des préoccupations distinctes et testées
• Limitation de débit avec en-têtes informatifs
• Journalisation structurée et suivi des erreurs
• Documentation avec exemples concrets
• Un environnement de staging surveillé accessible aux consommateurs pour le développement

Prochaines étapes

Si vous prévoyez une intégration et que le système à l’autre bout est inconnu, l’étape initiale judicieuse est une courte étude payante pour établir ce qui est réellement possible. Elle coûte généralement une fraction du projet et révèle parfois que l’intégration que vous pensiez pouvoir réaliser ne peut pas l’être comme décrit dans le devis.