Préambule

Ce document présente l’ensemble des APIs (Application Programming Interface) mises à disposition par Project Monitor.

Convention de rédaction / Glossaire

Principe d’architecture

Ces APIs sont basées sur :

• le principe d’architecture REST (Representational State Transfer),
• le protocole HTTP (hyper text transfer protocol),
• le format de données JSON (JavaScript Object Notation).

Outils de test

Pour tester les API de manière interactive, il est recommandé d’utiliser l’un des plug-ins suivants :

• Postman recommandé par Virage Group : https://www.postman.com/downloads/
• Firefox REST Client : https://addons.mozilla.org/fr/firefox/addon/restclient/
• Chrome Advanced REST Client : https://chrome.google.com/webstore/detail/advanced-rest-client/
🚨
Attention, concernant les fichiers xls renvoyés, le plug-in « restclient » essaye d’afficher directement les fichiers téléchargés plutôt que de proposer de les ouvrir avec l’application dédiée.

Pour obtenir le bon format de date, il est possible d’utiliser un des convertisseurs suivants :

• http://www.ruddwire.com/handy-code/date-to-millisecond-calculators/
• www.timestamp.fr qui permet de traduire une date en seconde ou inversement

Informations générales

Syntaxe

Principe

Conformément au protocole HTTP, chaque API est une requête HTTP composée des éléments suivants :

• une URL, ex : https://monprojectmonitor/MonitorMakerWeb/api/projects
• un verbe HTTP, ex : POST
• des informations dans le header HTTP, ex : X-PM-LOGIN : monLogin

La requête peut être complétée d’élément au format JSON (JavaScript Object Notation), http://www.json.org/, ex : {"libelle":"monProjet","code":"mon_projet"...} L’API retourne par défaut des données au format JSON.

Certains appels peuvent retourner des fichiers de type ms-excel ou csv.

Format de date lisible

Les dates peuvent être fournies avec un format lisible : AAAA-MM-JJT00:00:00 (RFC-1123, ISO-8601 : http://wiki.fasterxml.com/JacksonFAQDateHandling)

Exemple : "dateDebut": "2016-12-31T00:00:00" est accepté mais "attributs": { "ATT_IMPLEMENTATION_END_DATE": "2018-12-31T00:00:00"} ne l’est pas.

Paramètres des requêtes

Les paramètres des requêtes peuvent être passés selon plusieurs syntaxes.

Les deux premières syntaxes s’appuient sur le standard des URLs : http://fr.wikipedia.org/wiki/Uniform_Resource_Locator#URL_absolue

1. Paramètre intégré dans le « chemin ». Exemple : /projects/2012/germany L’ordre est important puisque l’API attend, implicitement, tel paramètre à telle place. Les paramètres ne sont pas nommés.
2. Paramètres HTTP. Exemple : /projects?country=Germany&year=2012 Les paramètres sont nommés (clé = valeur). Ils sont séparés du “chemin” par ? et séparé entre eux par &. L’ordre des paramètres n’est pas important.
3. “Matrix parameter”. Exemple : /projects/;year=2012;country=germany Les paramètres sont nommés (clé = valeur). Ils ne sont pas séparés du “chemin” et sont préfixés par ;. L’ordre des paramètres n’est pas important. Cette notation n’est pas liée au standard URL.

Enfin, ces différentes syntaxes ne sont pas incompatibles dans une même requête. Il est possible d’avoir des paramètres dans une syntaxe et d’autres dans une autre. Par contre, un paramètre est bien attendu dans une syntaxe particulière par l’API.

Si la requête suivante est possible : /projects/closed;year=2012?country=Germany&login=mdupont

La requête ci-après n’est pas son équivalent : /projects/2012;country=Germany?status=closed&login=mdupont

Racine des URLS

Tous les Webservices sont disponibles à partir de l’URL suivante : https://{UrlProjectMonitor}/MonitorMakerWeb/api où UrlProjectMonitor est le nom DNS de l’installation de Project Monitor Exemple : https://projectmonitor/MonitorMakerWeb/api

Authentification

Jeton JWT

• Acquisition

À la différence de l’api key, le jeton JWT se génère directement par un web service d’acquisition (api/auth/jwt/token). Ce web service prend en paramètre le login et le mot de passe avec lequel on souhaite s’authentifier.

• Exemple avec cURL
Copy

curl --location '' --header 'X-PM-LOGIN: monlogin' --header 'X-PM-PASSWORD: monmotdepasse'

• Désactivation de l’API Key

Des propriétés permettent de désactiver le fonctionnement par api key, le mode token sera donc le seul autorisé. Si la propriété est non définie, alors on utilisera l’api key ou le token, les 2 modes peuvent cohabiter. Contrairement à l’api key, le token possède une date d’expiration, il est donc possible de changer la durée de vie par defaut du token (24h).

API Key (Déprécié)

Chaque appel aux webservices doit être accompagné d'une apikey. Une apikey est une grande suite de caractères sans signification qui authentifie le service appelant. L'apikey peut être générée dans l'écran d'administration de la plateforme ou bien indiquée dans le fichier de paramétrage <XXX>.monitormaker.properties via la propriété com.vc.mm.webservice.apikey

Exemple :

#/ com.vc.mm.webservice.apikey (remplace com.vc.mm.commande.exec.auth)
#/ chaine d'authentification (api key) pour executer des web services
# depuis 5.4.1
#/ obligatoire : non
#/ defaut : rien (execution impossible)
com.vc.mm.webservice.apikey= BkBUlBLMl4y66kW10M1aRdrGiGn1yO3S

Ou bien via l’écran d’administration :

L’écran d’administration permet de définir plusieurs apikey, de les nommer et surtout d’en restreindre l’usage à une adresse IP donnée. Dans l’exemple ci-dessus, la clé ne pourra être utilisée que dans des requêtes provenant de l’adresse IP 192.168.0.80. L’apikey doit ensuite être envoyée à chaque appel de web service selon un des moyens suivants par ordre de vérification :

1. Dans le header HTTP spécifique via la clé : X-PM-API-KEY
2. Dans le header HTTP Authorization de type ‘BASIC’ : l’apikey remplace le login et le champ mot de passe peut être rempli avec n’importe quelle valeur.
3. Dans les paramètres (query parameter) de la requête avec le paramètre : apikey

Exemple : https://projectmonitor/MonitorMakerWeb/api/templates?apikey=BkBUlBLMl4y66kW10M1aRdrGiGn1yO3S

Cette dernière méthode est non sécurisée (l’apikey apparait en clair dans l’URL et donc peut apparaître typiquement dans des fichiers de logs eux-mêmes non sécurisés).

Elle ne devrait être utilisée que dans un contexte interne (derrière une DMZ par exemple).

Headers

Header Http des requêtes

En plus des éléments d’authentification vus ci-avant, il est nécessaire de rajouter l’header suivant :

Accept: application/json

Header Http des réponses

Les web services renvoient systématiquement du json encodé en UTF-8 :

Content-Type: application/json;charset=UTF-8

Accès cross domain

Il est possible d’accéder aux webservices de Project Monitor à partir de page HTML + javascript d’un autre domaine que celui de Project Monitor. Pour cela, Project Monitor propose deux techniques.

JSON-P

Project Monitor implémente la technique json-p (http://en.wikipedia.org/wiki/JSONP) et propose un paramètre global pour chaque webservice : jsoncallback.

Ce paramètre doit être fourni sous forme de paramètre de requête (query parameter). Exemple :

<!—requête envoyée par une balise ‘script’ -->
<script src="<http://projectmonitor/MonitorMakerWeb/api/templates?login=jdupont&jsoncallback=myCallBack>"></script>
<!— résultat du web service reçues en paramètre de la fonction callback. -->
<script>function myCallBack(data) {console.log(data.value);}</script>

Cross-Origin Resource Sharing

Cross-Origin Resource Sharing (ou CORS, http://en.wikipedia.org/wiki/Cross-origin_resource_sharing) est un mécanisme standard permettant le partage d’information entre sites web. Project Monitor prend en charge ce mécanisme côté serveur. Ce mécanisme dépend du navigateur exécutant la page html appelante : http://en.wikipedia.org/wiki/Cross-origin_resource_sharing#Browser_support

Erreurs

Les erreurs sont remontées via un statut HTTP

Méthode import par cURL

Présentation

Ces Webservices permettent d'envoyer des fichiers d'import ou de synchronisation. Leur syntaxe est spécifique et ne s'appuie pas sur ce qui a été vu précédemment. L’outil cURL est fourni dans le répertoire « install » de p-monitor. Il permet d’appeler p-monitor en HTTP et de transmettre un fichier CSV à importer. Si la plateforme doit importer des données via son interface HTTP, un utilisateur spécifique à la plateforme doit exister et posséder les bons droits pour exécuter l’import.

Identifiant d’import

Nouvelle méthode de lancement cURL

Pour lancer un import cURL, utilisez la syntaxe suivante dans un batch : curl -H "Accept:application/json" -H “Authorization: montoken” -silent -F

Pour attendre la fin de la commande afin de continuer le traitement dans votre fichier batch une fois que l’import est terminé, utilisez l’option wait :

curl -H "Accept:application/json" -H “Authorization: montoken” -silent -F wait=true -F attachment=@fichierAEnvoyer.txt
"http://url.de.projectmonitor/MonitorMakerWeb/api/import/IDENTIFIANT_IMPORT?login=LOGINUSERPM"

Pour connaitre si un import cURL est en cours, utiliser l’option isrunning :

curl -H "Accept:application/json" -H “Authorization: montoken” -silent -F isrunning=true -F attachment=@fichierAEnvoyer.txt
"http://url.de.projectmonitor/MonitorMakerWeb/api/import/IDENTIFIANT_IMPORT?login=LOGINUSERPM"

Pour préciser le type de la pièce financière lors de l’import SYNCHROFINANCIERE, utiliser l’option obligatoire importType :

curl -H "Accept:application/json" -H “Authorization: montoken” -silent -F attachment=@fichierAEnvoyer.txt
"http://url.de.projectmonitor/MonitorMakerWeb/api/import/SYNCHROFINANCIERE/importType/TYPE_PIECE_FINANC_REALISE?login=LOGINUSERPM"

$headersToken = New- Object "System.Collections.Generic.Dictionary[[String],[String]]"
$headersToken.Add('X-PM-LOGIN',$login)
$headersToken.Add('X-PM-PASSWORD',$password)
echo "Tentative d'authentification pour l'utilisateur $login et son mot de passe est $password"
try{$response = Invoke-WebRequest -Headers $headersToken - URI "" | ConvertFrom-Json} 
catch [System.Net.WebException] {echo "Impossible d'obtenir le token (verifiez votre login/mot de passe)"
return} echo "Appel du web service d'export projet"
$token = $response.token
curl.exe -X POST -k -H Authorization:$token -H Accept:application/json -F attachment=@ImportPF.csv 
"https://pmdemo.p-monitor.com/MonitorMakerWeb/api/import/SYNCHROFINANCIERE/importType/TYPE_PIECE_FINANC_REALISE/"

L’utilisateur spécifié par le paramètre login reçoit un mail résumant le déroulement de cet import.

Les codes retours http visibles par curl sont :