Services web

Services web

Plusieurs services web sont mis à la disposition des usagers pour permettre à intégrer Constellio à des systèmes externes et de faciliter l'automatisation de certains processus. Les APIs offertes permettent de recevoir les appels entrants en provenance de systèmes externes afin d'effectuer des opérations dans Constellio, autant en lecture qu'en écriture. Un système de webhooks permet également d'effectuer des appels sortants, de Constellio vers un système externe, lorsque certaines actions préconfigurées par l'utilisateur sont effectuées dans l'environnement Constellio.

Cette page présente un aperçu des différents services web disponibles. Des pages d'information détaillées sont disponibles pour chacun d'entre eux.

Authentification et sécurité

L'authentification aux différents API est effectuée à partir d'URL signées ou de jetons d'autorisation fournis par Constellio (dépendamment des APIs). Les jetons générés qui sont utilisés pour autoriser l'accès sont basés sur le protocole OAuth2.

Les jetons peuvent être générés pour un utilisateur directement dans Constellio à partir de la page "Gérer la sécurité" ou bien en à l'aide d'une requête GET à l'URL suivante en fournissant le nom d'utilisateur, le mot de passe, et la durée du token en en-tête à la requête.

/constellio/generateToken

Une fois authentifiées, les mêmes validations de sécurité qui existent dans Constellio seront appliquées aux requêtes par API.  Par exemple, un utilisateur qui ne dispose pas des permissions nécessaires pour consulter un dossier recevra un message d'erreur en réponse s'il tente d'y accéder à partir d'un des services web.

Services web disponibles

API REST 

L'API Rest est un API permettant d'effectuer des manipulations sur différents types d'enregistrement dans Constellio à partir de requêtes HTTP avec un corps en format JSON. Cet API est conforme aux critères architecturaux d'API "RESTful" et permet des opérations de consultation, modification, création et suppression (GET, PATCH, POST, DELETE) sur la plupart des types d'enregistrements supportés.

L'URL /records permet quand à lui d'effectuer des recherches pour consulter les métadonnées de n'importe quel type d'enregistrement, pourvu que l'utilisateur possède les accès en lecture sur ceux-ci.

L'API Rest V2 est disponible depuis la version 11 de Constellio. Cette nouvelle version de l'API simplifie l'authentification en utilisant le standard OAuth2 au lieu d'URL signées et permet des opérations sur de nouveaux types d'enregistrements.

Consultation (GET)

Les opérations de consultation permettent d'obtenir des informations sur un enregistrement spécifique. L'ID Constellio de l'enregistrement à consulter doit être fourni en paramètre, puis L'API retourne l'information demandée sous la forme d'un fichier JSON. L'information contenue dans la réponse dépend du type d'information demandée. Par exemple, une requête GET pour un document permettra d'obtenir la liste des métadonnées du document en question, un GET à l'URL /collections renverra la liste des collections qui existent dans l'environnement, etc.

Modification(PATCH)

Les opérations de modification permettent de modifier les métadonnées d'une ressource existante dans Constellio. On fournit l'ID de l'enregistrement à modifier ainsi qu'un corps en JSON des métadonnées à modifier avec leurs valeurs.

Un JSON avec les valeurs de toutes les valeurs des métadonnées à jour de l'enregistrement est envoyé en réponse.

Création (POST)

Les opérations de création permettent de créer de nouveaux enregistrements dans Constellio. La requête doit inclure un JSON qui définit les valeurs de chacune des métadonnées de l'enregistrement à créer.

Un JSON avec les valeurs de toutes les valeurs des métadonnées à du nouvel enregistrement est envoyé en réponse.

Suppression (DELETE)

Les opérations de suppression permettent de supprimer un enregistrement existant dans Constellio en lui fournissant l'ID de l'enregistrement à supprimer. Lorsque supporté, on peut définir si la suppression doit être définitive ou non.

Téléversement/Téléchargement de fichiers

Il est également possible de télécharger les fichiers des métadonnées de type "Contenu" d'un enregistrement Constellio à partir de l'URL /records/{id}/content, où le paramètre ID fait référence à l'ID Constellio de l'enregistrement dans lequel le fichier que l'on veut récupérer se trouve. On doit fournir le code de la métadonnée de type "Contenu" dans laquelle on veut récupérer le fichier.

Opérations supportées (API Rest V2)

* La méthode POST sur l'URL /records ne permet pas de créer un nouvel enregistrement, mais plutôt de lancer une nouvelle recherche avancée

Documentation technique de l'API Rest

Rest API v2

Interface de recherche SOLR

L'API de recherche permet de rechercher des enregistrements de Constellio en effectuant directement des requêtes SOLR à partir de l'URL /select. Les paramètres de la recherche ainsi que le jeton d'authentification et la clé de service doivent être fournis en paramètres.

Exemple:

http://localhost:7070/constellio/select?token=token-autjentification&serviceKey=cle_de_service&q=schema_s:document* AND title_s:Abeille*

 Cet API permet également d'effectuer des recherches dans les audits du système afin de trouver des évènements en particulier en fournissant le paramètre searchEvent = true à la requête. Cependant, la recherche dans les audits peut uniquement être effectuée par un utilisateur qui possède la permission "Consulter les audits".

Recherche REST

Interface de recherche de métadonnées en cache

L'API de recherche sert à retourner la liste des objets non sécurisés de l'application, par exemple les domaines de valeurs, une liste des utilisateurs/groupes, etc. L'identification se fait par la mécanique de jeton de Constellio.

API de recherche en cache

APIs de consultation de documents avec l'agent

Ces deux services web permettent de rapidement ouvrir un document Constellio en consultation ou en téléchargement. L'ouverture du document est effectuée via l'agent Constellio qui doit être installé sur le poste de l'utilisateur qui envoie la requête.

Ouverture de document

Téléchargement d'un document

CMIS

L'API CMIS est un API qui permet d'effectuer des opérations de base (Création, Consulation, Mise à jour, Suppression)  sur les dossiers et documents dans Constellio en utilisant les standards CMIS (Content Management Interoperability Services). Pour utiliser cet API, l'utilisateur authentifié doit posséder la permission "Utiliser les interfaces de programmation applicatives (API CMIS)" dans Constellio.
CMIS

Webhooks

Un système de webhooks permet d'automatiquement effectuer des appels HTTP vers un système externe à partir de Constellio lorsqu'un utilisateur effectue des modifications sur les documents, dossiers ou sur les tâches dans Constellio. Des critères spécifiques peuvent être définis afin d'envoyer les notifications dans des cas spécifiques.

Les appels effectués sont des requêtes HTTP de type "POST" qui contiennent les informations sur l'utilisateur ayant effectué l'action, ainsi que les valeurs des métadonnées de l'enregistrement modifié, telles que définies dans la liste de métadonnées à transmettre du webhook.
Webhooks