README Package API-alpha

Pré-requis

• Un environnement d'exécution Java 8 (Java Runtime Environment) doit être installé et configuré dans la variable système PATH.

• Un OS Windows ou Linux

Description

L'archive contient :

• la documentation html des API Vitam

• la documentation RAML des API Vitam

• un serveur contenant les bouchons des API Vitam et l'outil RAML Console (https://github.com/mulesoft/api-console)

• les Javadoc de quelques modules Vitam

Utilisation

Exécution du serveur

Pour exécuter le serveur, lancer l'exécutable correspondant à votre OS :

• run.sh (Linux)

• run.bat (Windows)

Pour s'assurer que le serveur s'est bien démarré, vérifier les pages suivantes :

• la RAML Console

  • URL : http://localhost:8082/doc/api-console.html

  • résultat attendu : l'outil RAML Console est chargé

• les bouchons des API Vitam :

  • URL : http://localhost:8082/external/v1/status

  • résultat attendu : une réponse 200 est envoyée

Utilisation de la RAML Console

Les fichiers RAML de documentation de l'API Vitam sont chargés dans la RAML Console en les renseignant dans le champ "INITIALIZE FROM THE URL OF A RAML FILE" l'un des chemins suivants :

• raml/access.raml

• raml/ingest.raml

• raml/logbook.raml

Les fichiers RAML de documentation de l'API Vitam sont dans le dossier console/raml. Toute modification d'un de ces fichiers nécessite de redémarrage du serveur.

Utilisation de la fonctionnalité TRY-IT de la RAML Console

Une fonctionalité TRY-IT permettant de tester les API est fournie par la RAML Console. Pour des raisons de manque de stabilité de la fonctionnalité offerte par cet outil externe au Programme Vitam, elle est désactivée par défaut.

Elle reste accessible sur l'URL http://localhost:8082/doc/api-console-try-it.html

Pour utiliser la fonctionnalité TRY-IT de la RAML Console, il est préférable d'utiliser les chemins suivants :

• raml/access-nosecurity.raml

• raml/ingest-nosecurity.raml

• raml/logbook-nosecurity.raml

La fonctionnalité TRY-IT de la RAML Console utilise par défaut les bouchons fournis par le serveur. Pour utiliser un autre serveur, il faut modifier la valeur de l'attribut baseUri des fichiers RAML utilisés.

Utilisation des bouchons de l'API VITAM

Les bouchons sont déployés sur l'URL http://localhost:8082/external/v1

Documentation html de l'API VITAM

La documentation html de l'API VITAM se trouve dans le dossier html et peut être consultée directement en se rendant à l'adresse http://localhost:8082/doc/html

Elle inclut les Javadoc des modules suivants :

• Query Builder (builder DSL pour Access)

• Access Client (dont la factory)

• Ingest Client (dont la factory)

• Logbook Client (dont la factory)

Ainsi que ce présent fichier et la licence globale du logiciel Vitam.

Configuration

Changer le port HTTP du serveur

La valeur du port HTTP sur lequel s'exécute le serveur est 8082 par défaut.

Pour modifier cette valeur, il faut l'ajouter en argument de l'exécutable :

• run.sh 8088 (Linux)

• run.bat 8088 (Windows)

Configuration des logs

Les logs utilisent la bibliothèque LOGBack (http://logback.qos.ch/).

Le fichier de configuration des logs est : config/logback.xml. Toute modification de ce fichier nécessite le redémarrage du serveur.

Exemples de codes clients

Le répertoire « samples » contient des exemples de codes Java (avec un modèle de pom.xml) pour illustrer l'usage des API Java proposées :

• AccessSamples.java

• IngestSamples.java

• LogbookSamples.java

Il propose également des exemples de commandes Curl pour utiliser les API :

• access_curl.txt

• logbook_curl.txt