Introduction

Ce document a pour vocation de recenser les lignes directrices et bonnes pratiques de la BNum s'agissant de la conception d'APIs RESTful pragmatiques.

Nouveau venu dans le monde des APIs ? → An Introduction to API’s

Préambule

Aucun standard absolu n'existe réellement concernant la façon de concevoir une API web moderne.

Néanmoins de nombreuses ressources plus ou moins riches sont disponibles en ligne sous la forme de white papers ou simples articles qui visent à faire un retour d'expérience ou des préconisations de la part d'acteurs souvent légitimes.

Faire le tri parmi la foultitude de ressources disponibles est une tâche ardue; c'est pourquoi il est apparu nécessaire pour la Direction Technique de la Branche Grand Public et Numérique avec l'ensemble des forces vives concernées par le sujet un corpus minimum établissant et décrivant les règles essentielles à suivre pour obtenir un design API efficient et pragmatique.

Se doter d'APIs efficientes est devenu un objectif vital pour fluidifier l'intégration des services de la BGPN, et donc pour la transformation numérique du Groupe.

Liminaire

Dans la suite de ce document, aucune distinction n'est faite entre une API ayant vocation à être publiée publiquement et une API exclusivement interne, afin d'éviter de sacrifier des bonnes pratiques pour des mauvaises raisons (syndrôme de l'intranet).

Pour l'ensemble des pratiques et préconisations recensées on distinguera ce qui est "non arbitrable" de ce qui est "dépendant du contexte" afin de ne pas sombrer dans la sur-qualité tout en garantissant un minimum d'intéropérabilité.

Signalétique	Signification
doit	doit être respecté, non arbitrable
devrait	devrait être respecté si le sujet est concerné
option	optionnel, proposition de bonne pratique qui peut faire débat

Cela signifie aussi qu'un standard est suivi s'il apporte une valeur, et non pas simplement "à priori".

Postulats

Les recommandations énoncées dans ce document sont basées sur les principes suivants :

• Les standards du web sont suivis lorsqu'ils font sens
• Les ressources exposées sont simples à comprendre pour un développeur et explorables avec une barre d'adresse de navigateur
• Dans la mesure du possible le contact avec l'API doit être agréable, simple et consistant
• L'API doit être suffisamment flexible pour pouvoir subvenir à tous les besoins des consommateurs (applis web, applis mobiles, objets connectés)
• L'API ne doit pas préjuger de l'usage, mais le servir; l'API représente le SI, c'est-à-dire les processus métiers qui sont exposés au monde