Skip to main content

Guide API

Introduction

Shadline met à disposition de ses clients une Interface de Programmation Applicative (API) qui permet de gérer de façon automatisée les fichiers de son instance de Stockage dédiée.

La technologie Shadline assure la protection des données et renforce notamment la conformité au RGPD (Règlement général sur la protection des données) entré en vigueur en mai 2018.

Notre solution se distingue des autres services de stockage par de multiples mécanismes de chiffrement des données (« in motion » et « at rest »), couplés à une fragmentation des fichiers.

Grâce à cette API, Shadline permet de déployer rapidement des conteneurs, c’est-à-dire des zones de stockage sécurisées et étanches pour garantir la confidentialité, l’intégrité, la disponibilité et l’isolation des données critiques de votre entreprise.

Préambule technique

Une API RESTful

L’API proposée par Shadline respecte la norme RESTful (REpresentative State Transfert).

Tous les flux échangés avec l’API sont chiffrés en HTTPS au moyen du protocole TLS. Seules les connexions sécurisées par TLS sont acceptées par l’infrastructure Shadline.

Les deux formats retournés par l’API sont le binaire (retour lors de la demande d’un fichier) et le JSON (JavaScript Objet Notation).

Fonctions exposées par l’API

Les web services exposés par Shadline permettent aux utilisateurs de l’API de bénéficier d’un stockage sécurisé de fichiers. Les fonctionnalités majeures disponibles pour gérer les documents sont les suivantes :

  • Stockage de fichiers dans Shadline (envoi)
  • Récupération de fichiers stockés sur Shadline (téléchargement)
  • Suppression de fichiers stockés sur Shadline (effacement)

L’opération de stockage doit être effectuée fichier par fichier. L’API n’intègre pas de stockage de fichiers par lot à ce jour.

Des fonctions permettant de lister les documents, de les organiser en arborescence (visible depuis l’application web et mobile Shadline), d’en obtenir les métadonnées ainsi que des statistiques liées à l’usage du service sont disponibles. Il est également possible d’attribuer une date d’expiration à chaque fichier à l’issue de laquelle il sera automatiquement effacé.

Ces fonctionnalités sont détaillées dans la suite de ce document en décrivant les requêtes associées, les paramètres nécessaires et les codes de retours possibles.

API_Description_FR

Limites d’usage

Chaque client peut exploiter son espace de stockage pour y déposer les fichiers de son choix. L’API Shadline est compatible avec tous les formats de fichiers : Word / Excel / PowerPoint, PDF, TXT, CSV, images, vidéos, archives, binaire, etc.

La taille maximale autorisée par fichier est définie selon le contrat.

Authentification

Mécanismes d’authentification pour accéder à l’API

L’API Shadline implémente différents mécanismes de contrôle d’accès complémentaires.

1. Une authentification par certificat du client (entreprise) du produit

    • L’utilisateur doit disposer du certificat remis par Shadline afin que les échanges avec la solution soient autorisés. Le serveur de l’API contrôle la validité de l’empreinte du certificat présenté par l’utilisateur à chaque requête effectuée.
    • Ce certificat client doit être utilisé pour toutes les requêtes à l’API.

2. Une identification globale à l’API

    • L’utilisateur doit disposer d’un identifiant API (appelé x-api-key) remis par Shadline afin que les échanges avec la solution soit autorisés. Le serveur de l’API contrôle la validité de cet identifiant présenté par l’utilisateur à chaque requête effectuée. L’identifiant est le même pour tous les utilisateurs d’une même entreprise, il est commun à l’ensemble des conteneurs utilisés.
    • Cette clé doit être utilisée pour toutes les requêtes à l’API.

3. Une identification par conteneur

    • L’utilisateur doit disposer d’une identification « conteneur » (appelée x-user-key car un conteneur équivaut à un compte API) afin de pouvoir interagir avec le contenu du conteneur souhaité. Le serveur de l’API contrôle la validité de cet identifiant présentée par l’utilisateur à chaque requête effectuée.
    • Cet identifiant est généré lors de la création du conteneur par l’entreprise. Il peut être obtenu depuis l’interface d’administration web Shadline. Il est différent pour chaque conteneur. Il s’agit d’un élément secret qui protège l’accès aux données du conteneur.
    • Cette clé doit être utilisée pour toutes les requêtes à l’API.

4. Une authentification par mot de passe de conteneur

    • L’utilisateur doit disposer d’un identifiant appelé hPassword correspondant à la dérivée du mot de passe choisi lors de l’initialisation du conteneur. Le serveur de l’API renvoie, lors de cette initialisation, un localPassword afin de pouvoir interagir avec le contenu du conteneur souhaité. Le serveur de l’API contrôle la validité de cette chaîne de caractères présentée par l’utilisateur à chaque requête effectuée.
    • Cette valeur doit être utilisée pour toutes les requêtes à l’API impliquant un accès aux documents (envoi, téléchargement ou suppression).

En complément, un jeton à usage unique (token JWT) est inséré dans chaque requête applicative afin de renforcer le contrôle des autorisations. Toute requête est donc effectuée en 2 temps :

  • Une demande de token
  • Puis l’appel à la fonction désirée avec le token obtenu

Le token a une durée de validité de 5 minutes.

Note : Lors de la première connexion avec un conteneur API, il vous sera demandé de fournir la dérivée de votre mot de passe en SHA512 (hpassword) afin d’obtenir le localPassword associé.

Le schéma suivant présente les principaux éléments d’authentification utilisés :

API_Authentification_FR

Séquencement des actions d’authentification et d’autorisation

L’enchaînement des étapes se fait conformément au schéma ci-dessous :

API_Séquencement_FR

Les premiers échanges servent à initialiser l’environnement. Ils ne sont réalisés qu’une seule fois.

1. Le serveur Shadline vérifie l’identité du client (à l’aide du certificat client délivré en amont et de la clé API). Le client reçoit un token en retour.

2. Le client définit son mot de passe. Il reçoit en retour la valeur localPassword.

Le client peut ensuite utiliser l’un des services de l’API pour exécuter la fonctionnalité souhaitée.

3. Le client redemande un token préalablement à chaque appel applicatif

4. Le client peut appeler la fonction de son choix à l’aide des éléments d’authentification en sa possession.

Format des requêtes et retours

L’ensemble des actions est effectué grâce aux types de requêtes HTTP (telles que GET, POST, PUT, DELETE, HEAD, etc.) suivi du point d’entrée, ou URL, qui impactera la ressource demandée.

Globalement, les requêtes sont formulées de la façon suivante :

ACTION /api/[ressource_impactee]/{identifiant_ressource}

La réponse HTTP comporte un code représentant l’état de l’opération (ex : 200 pour une opération effectuée avec succès) ainsi qu’une partie data en JSON ou en binaire pour le renvoi de fichier.

Le JSON retourné respecte systématiquement le format suivant :

"data": {}, // Données demandées: objet ou tableau selon la ressource

Le champ « data » est présent même sans données particulières, il sera alors vide.

En cas d’erreur, on obtient un retour de la forme suivante :

{
"type": "TYPE_ERROR",
"message": "description longue, Human-readable",
"data": [],
"uri": "URI vers description détaillée de l’erreur dans api/doc si disponible"
}

« data » peut par exemple être présent dans le cas d’une erreur de validation de paramètres d’entrée. Il précise alors les paramètres en cause et les raisons.

Tous les codes de retour possibles (et les éventuels types d’erreur associés) sont décrits au paragraphe Codes de retours et types d’erreur.

Gestion des versions

Plusieurs versions d’API peuvent être disponibles dans une instance client.

La version utilisée doit être précisée dans chaque URI, après le terme « /api » :

/api/vx/[...]

vx représente la version de l’API utilisée (« x » est le numéro de version) et […] l’appel à la ressource. Exemple :

/api/v2/storage

Si cette valeur n’est pas précisée, la dernière version de l’API sera automatiquement utilisée. Nous vous conseillons donc d’indiquer le numéro de version dans toutes les URI afin d’assurer le fonctionnement de vos applications en cas de mise à jour de l’API.

La version d’API utilisable vous sera précisée par l’équipe technique Shadline.

Note : Le cycle de vie des versions est maintenu par l’équipe technique Shadline. Lors du déploiement en Production d’une version « n », la version « n-1 » reste active et maintenue pendant plusieurs mois afin de permettre la transition des applications de nos clients vers cette dernière release. Outre l’ajout de nouvelles routes, des modifications techniques aux paramètres d’entrée et sortie peuvent en effet être apportés aux routes existantes lors de ces évolutions. La date de passage d’une version de l’API en statut « non supporté » (unsupported, ie « end-of-life ») sera communiquée en amont par Shadline.

Description technique des requêtes (liste des endpoints)

La liste des endpoints est accessible depuis l’URL suivante :

https://documenter.getpostman.com/view/14673366/TzsWuqXw

Collection Postman

Une collection Postman regroupant l’ensemble des endpoints peut être téléchargée via le lien suivant pour faciliter les travaux de développement afin de se raccorder à notre API :

https://doc.shadline.com/wp-content/uploads/2022/04/Shadline-API-Public-Edition.postman_collection.json_.zip

La configuration de l’outil Postman est détaillée dans le document suivant :

https://doc.shadline.com/wp-content/uploads/2022/04/SHADLINE_Postman_Configuration.pdf

Codes de retour et types d'erreur

Code Type Signification
200 OK Requête exécutée avec succès
201 CREATED Fichier stocké avec succès
400 BAD_PARAMETER
BAD REQUEST
Les paramètres fournis ne respectent pas les types attendus
400 ERR_INVALID_TOKEN Token mal formaté
400 ERR_NO_APIKEY Pas de header « x-api-key » identifié
400 ERR_NO_TOKEN Pas de champ « Authorization : Bearer » identifié
400 ERR_UNABLE_DECODE_PARAM Le payload du token est corrompu
401 UNAUTHORIZED Token expiré ou invalide
ou x-api-key non présente ou invalide
ou x-user-key non présente ou invalide
403 ERR_ORIGIN_NOT_ALLOWED Mauvais serveur d’authentification
403 FORBIDDEN Accès interdit car l’initialisation du conteneur a déjà été effectuée
404 ERR_ORIGIN_NOT_FOUND Le serveur d’authentification est inconnu
404 FOLDER_NOT_FOUND Pas de répertoire trouvé
404 ITEM_NOT_FOUND Pas de document trouvé
404 FILE_NOT_FOUND Pas de fichier trouvé
404 NOT FOUND Document demandé introuvable
404 USER_NOT_FOUND Pas de conteneur trouvé
413 PAYLOAD TOO LARGE Le fichier est trop volumineux
422 UNPROCESSABLE ENTITY Problème de format de fichier ou paramètres attendus invalides
500 ERROR Erreur générique (interne aux services)
509 LIMITATION_REACHED Limitations de l’API atteintes
524 REQUEST_TIMEOUT La requête a duré trop longtemps