4 Règles communes à toutes les routes API

4 Règles communes à toutes les routes API

4 Règles communes à toutes les routes API

4.1 Respect des SWAGGERS

4.1 Respect des SWAGGERS L’API publiéepar leFournisseurAPI doitêtre compatible avec le SWAGGER (contrat API en REST) en annexe de la norme. Cette API doit respecter le versioning indiqué dans l’URLde la route API du Swagger. Dans un objectif de simplification le versioning des routes n’estpas affichédans le présentdocument; Dans cette API publiée par le Fournisseur API ce dernier peut : • Avoir une URL spécifique en amont du versioning • Ajouter des propriétés aux objets dans les requêtes. • Ajouter des paramètres aux routes dans les requêtes. • Ajouter des propriétés aux objets dans les réponses. • Ajouter des codes erreurs dans les réponses.

4.2 Authentification

4.2 Authentification L’API publiée par le Fournisseur API doit être compatible avec le protocole d’authentification OAUTH2 et utiliser un Jeton (bearer) au sens de la RFC 6750. Le Fournisseur API doit permettre au Client API de renseigner un Client Id et un Client Secret et a minima de publier la route « token URL ». Il est recommandé au fournisseur API de mettre en place une sécurisation du Client Id / Client Secret avec l’un des systèmes ci-dessous : • Un filtrage IP • Un mécanisme d’expirationdu secret. Ilestrecommandéd’avoir un Client Secret quirépondauxrecommandations de l’ANSSIsur la sécurisation des mots de passe. Une fois connecté avec son Compte API, le Client API utilise le jeton (bearer) pour accéder àl’API publiée par le Fournisseur API. Si un même compte est utilisé pour accéder à plusieurs entreprises ou organisations, le paramètre d’entête ‘Organisation-Id’ dansle header http permet de le préciser.

4.3 Pagination

4.3 Pagination L’API publiée par le Fournisseur APIdoit utiliser un système de pagination basé sur les propriétés ‘limit’et ‘offset’lorsde l’appel et retourner ‘total’, ‘offset’et ‘limit’dans la réponse. Lorsque le jeu de donnée est dynamique (route POST / Search), le paramètre ‘offset’ n’estpas disponible. LeFournisseur API doitaccepter une valeur ‘limit’inférieure ou égale à 100 et peut refuser des appels avec une valeur supérieure.

4.4 Route GET / healthcheck

4.4 Route GET / healthcheck L’API publiée par le Fournisseur API doit avoir une route GET / healthcheck permettant au Client API de vérifier si le service API est opérationnel.

4.5 Taille maximale d’un flux

4.5 Taille maximale d’un flux Le Fournisseur API peut refuser des flux supérieurs à 100 mega octets.