La description de votre API est la troisième des six étapes à effectuer pour exposer une offre sur la Plateforme. Elle se fait dans Mes offres, au niveau de l’onglet API.

Pour décrire votre API, rendez-vous dans Mes offres, dans l’onglet Présentation.

Pour créer une offre par API vous êtes amené à décrire chacune des URLs qui seront disponibles dans cette offre. Pour valider cette étape vous devez indiquer :

  • Un nom : Information purement indicative permettant à vos acquéreurs de comprendre la logique de votre API et les données qui seront disponibles pour cette url
  • URL : URL précise
  • Type de requête : GET ou POST (manière dont sont transmises les informations, en fonction de leur sensibilité)
  • Format de sortie des données : Information indicative, informez vos acquéreurs du format de sortie des données (csv, json, xml, etc.)
  • Paramètres : quatre modes d'envoi sont disponibles : dans l'URL, dans le chemin, dans les headers ou dans le corps de la requête. Chaque paramètre peut être facultatif. Les paramètres dans l’URL et dans le chemin sont détectés automatiquement lorsque votre URL est enregistrée. Vous pouvez les modifier, en ajouter ou en supprimer.
  • Documentation et statut de l’API
  • Définir les conditions d’accès à l’API


PAS à PAS

Les paramètres d’une URL  

 


Pour illustrer cette partie nous allons exposer pour notre exemple une API avec deux URLs.

La connexion du futur acquéreur à l’API se fera uniquement via la Plateforme, les URLs renseignées ne seront jamais visibles en tant que tel, la Plateforme agissant comme un proxy.



Exemple1: exposition d’une requête GET

L’URL que nous souhaitons exposer est la suivante :

https://hubeau.eaufrance.fr/api/v0/etat_piscicole/code_espece_poisson?size=20

Elle permet de récupérer le lexique des codes espèce des poissons et prend un paramètre “size” dans l’URL qui limite le nombre de résultats par page. 

Une fois l’URL saisie, la Plateforme détecte le paramètre “size” et l’ajoute aux paramètres disponibles.



Un paramètre obligatoire devra être obligatoirement renseigné par l’acquéreur, s’il peut prendre plusieurs valeurs il devra être modifiable.

Il est possible de renseigner les champs Paramètres disponibles (A) et Description des paramètres disponibles (B) pour aider à la compréhension de l’acquéreur (valeurs minimales, maximales, noms des valeurs possibles...).

Vous pouvez ajouter d’autre paramètres (Ajouter un paramètre).

Remarques :

  • Pour décrire un paramètre dans le chemin, il est nécessaire d’indiquer sa position dans l’URL.
  • Les paramètres dans les headers ne sont pas détectés automatiquement et sont à décrire manuellement.




Exemple2: Exposition d’une requête POST

La seconde URL de cette offre est la suivante :

https://xxxxxxxx.fr/api/recensement_poissons

Elle permet à l’utilisateur d’entrer dans une base de données la liste des poissons qu’il a recensés.

Cette URL accepte les paramètres dans le corps de la requête, au format JSON.



 

Remarque :

  • Les formats XML et x-www-form-url-encoded sont également disponibles sur la Plateforme.

Documentation et statut de l’API

Pour mettre à disposition la page d’état du service (A) ou la documentation (B), il est possible de renseigner l’adresse de celles-ci.



Définir les conditions d’accès à l’API


Dans notre exemple, l’API ne nécessite pas d’authentification particulière donc nous passons à l’étape suivante.

Remarque :

  • Si votre API nécessite une authentification, deux modes sont pris en charges : par clé d’identification et par oAuth2. (cf. Fiche Gérer son authentification à la Plateforme)

La Plateforme gère l’accès aux données de l'API pour chacun des acquéreurs.

Elle a donc besoin d'un accès à l’API dont les seuils seront adaptés pour permettre à l'ensemble des acquéreurs d'accéder à vos données.

Les seuils de requête pour les acquéreurs seront appliqués par la Plateforme pour limiter l'accès aux données pour chacun de vos acquéreurs.

Quand le nombre d'acquéreurs actifs pour l'API atteint les limites d'accès à vos données appliquées pour la Plateforme, elle notifie le référent de l’offre.



Pour finaliser cette étape, un test d’accès à votre API est réalisé pour valider les informations que vous avez saisies.

Il est possible d’indiquer un contact technique qui sera notifié en plus du référent de l’offre en cas d’imprévu (problème d’accès à l’API, aux données...).



Vous pouvez ensuite passer à l’étape de Prélèvement de vos données dans l’onglet suivant.