Précision dans la définition des APIs REST – PEEPS

L'architecture REST est l'approche la plus populaire pour construire des APIs qui exposent des services web. Aujourd'hui, APIs.guru recense plus de 2500 API REST. Cependant, le développement et l'utilisation d'une API REST ne sont pas des tâches simples. Lors du développement de l'API, les parties prenantes, comme les propriétaires de produits (PO) et les développeurs, collaborent pour définir 1) les "Exigences", les besoins métiers formulés par les PO ; 2) le "Code", une représentation formelle de l'API par ses développeurs ; et 3) la "Documentation", une description compréhensible du code pour les consommateurs de l'API (développeurs externes). Malgré qu'ils se réfèrent à la même API REST, les parties prenantes utilisent des termes et des concepts hétérogènes qui sont sémantiquement et syntaxiquement différents. Cette imprécision est nuisible car elle conduit à l'ambiguïté, c.à.d., que les développeurs rencontrent des difficultés à comprendre les besoins métiers d'une API web. Elle entraîne également des utilisations ou des configurations incorrectes qui ont un impact sur la productivité. Les consommateurs d'API REST peuvent utiliser des types de données incorrects en raison de l'imprécision de la documentation textuelle ou en raison de l'évolution de l'API, qui rend la documentation obsolète. Environ 65,5 % des exemples d'utilisation dans la documentation des API web sont inappropriés. Cette situation peut entraîner des problèmes de sécurité dramatiques. En fait, les API web mal configurées représentent les deux tiers des violations de sécurité dans le cloud. Par conséquent, le développement d'API REST précises, utilisables et sécurisées, nécessite une cohérence entre les trois facettes que j'ai identifiées : les exigences, le code et la documentation. L'objectif du projet PEEPS est de garantir cette cohérence, que je désigne sous le nom de "Précision dans les API REST", en montant en abstraction et en créant des ponts entre les trois facettes.