HumanTalks Paris

Pourquoi est-ce si difficile de concevoir une API ?

12 Janvier 2016 @Deezer

Alexandre ESTELA

aestela@palo-it.com

@alx_estela

22

A propos du talk

API : API RESTful basée sur HTTP

Concevoir une API : Définir l’interface

d’échange avec le consommateur

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

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

API mal conçues :

Est-ce un problème de

technologie ?

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

API mal conçues :

Est-ce un problème de

concept ?

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

API mal conçues :

Est-ce un problème

d’outillage ?

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

API mal conçues :

Est-ce un problème de

méthodologie ?

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

API mal conçues :

Est-ce un problème de

collaboration ?

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

Conclusion

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

Merci pour

votre attention !

Des questions ?