Talk sur les bonnes pratiques de conception d'API pour le HumanTalks Paris du 12/01/2016.

1. HumanTalks Paris
Pourquoi est-ce si difficile de concevoir une API ?
12 Janvier 2016 @Deezer
Alexandre ESTELA
aestela@palo-it.com
@alx_estela

2. 22
A propos du talk
API : API RESTful basée sur HTTP
Concevoir une API : Définir l’interface
d’échange avec le consommateur

3. 33
A propos du speaker
Consultant Senior chez Palo IT
Evangélisateur et Architecte SOA & API
Souvent surpris par les (mauvaises)
pratiques de conception autour des API

4. 44
A propos des API mal conçues
L’API nostalgique de SOAP L’API miroir du Système d’Information
L’API à rétro-engineerer soi-mêmeL’API taillée pour 1 consommateur

5. 5
API mal conçues :
Est-ce un problème de
technologie ?

6. 66
La technologie n’est pas un problème
La stack technologique est standardisée et largement éprouvée
Transport HTTP
Enveloppes quasi-exclusivement au format JSON
Les techniques de sécurisation sont à peu près standardisées
HTTPS / TLS
HTTP Basic Auth
OAuth 2.0
OpenID Connect
Il n’y a pas a priori d’évolution prévue ayant un impact significatif
HTTP 2

7. 7
API mal conçues :
Est-ce un problème de
concept ?

8. 88
L’appropriation des concepts est un point d’attention
REST n’est hélas pas un standard « out of the box »
Il faut comprendre les concepts théoriques
URI, Ressources et Représentations
Méthodes protocolaires explicites (e.g. GET, PUT, …)
Hypertext / Hypermedia / HATEOAS
Transfert d’état
Il faut choisir les (bonnes) pratiques adaptées au contexte
Granularité des ressources
Headers HTTP
Gestion de session
Versioning

9. 9
API mal conçues :
Est-ce un problème
d’outillage ?

10. 1010
Le choix de l’outillage est un point d’attention
3 formats principaux de spécification
Swagger 2.0
RAML 1.0
Blueprint
Chaque format a ses forces et faiblesses
Capacités de spécification d’API
Parseurs et éditeurs
Générateurs de code et de documentation
Intégration avec d’autres langages et technologies
L’écosystème des formats tend à s’harmoniser
Convergence des capacités des 3 formats
Open API Initiative

11. 11
API mal conçues :
Est-ce un problème de
méthodologie ?

12. 1212
Le choix de la méthodologie est critique
Plusieurs approches méthodologiques sont possibles
« Top-Down », « Bottom-Up », « Test-Driven » …
Il importe d’identifier les facteurs de succès pour le contexte
Priorisation des fonctionnalités à plus forte valeur ajoutée
Fédération ou formation d’une communauté de développeurs (« DX »)
Anticipation des contraintes amenées par les SI / organisation / partenaires
Dans tous les cas, il faut recourir au prototypage, puis itérer
Plateformes cibles
Jeux de données concrets
Vrais consommateurs (dont « early adopters »)
Vrais cas de test

13. 13
API mal conçues :
Est-ce un problème de
collaboration ?

14. 1414
La dynamique collaborative est critique
La conception d’une API implique toujours de la collaboration
Entre fournisseur et consommateurs
Entre fournisseur et partenaires / référentiels
Il faut nécessairement cumuler outils et rituels de collaboration
Pour récolter de nouvelles idées et demandes
Pour arbitrer et prioriser les fonctionnalités à plus forte valeur ajoutée
Pour fournir des démonstrations et récolter du feedback
Pour former et accompagner les équipes
La documentation est clé pour populariser une API
En particulier une API ouverte
HATEOAS est une forme de documentation

15. 15
Conclusion

16. 1616
Une API amène quelques spécificités, mais reste un logiciel
Il est vrai que l’univers des API présente quelques spécificités…
Nécessité de fixer un nouveau vocabulaire avec les équipes
Compréhension et exploitation plus poussée du protocole HTTP
Choix d’un outillage dédié
Mais fondamentalement une API est un logiciel comme un autre !
Les clés du succès sont les mêmes que pour la majorité des logiciels
Il faut rester proche des consommateurs
Il faut tester ses idées en prototypant
Il faut appliquer les concepts théoriques de manière pragmatique
Il faut employer un outillage moderne et éprouvé
Il faut apprendre de ses erreurs et itérer
Il faut mettre en œuvre une collaboration forte entre tous les acteurs

17. Merci pour
votre attention !
Des questions ?