guide utilisateur - Emploi Store Développeurs

GUIDE UTILISATEUR
Version
Date
V1.5
V1.5
13/07/2016
Page 1 sur 10
13/07/2016
Guide utilisateur
HISTORIQUE DES VERSIONS
Version
0.1
1.0
1.1
1.2
1.3
1.4
1.5
V1.5
Date
22/06/2015
08/09/2015
13/10/2015
23/11/2015
03/02/2016
01/03/2016
13/07/2016
Objet modification
Création du document
Mise à jour du document
Mise à jour du document
Mise à jour du lien vers la documentation CKAN
Ajout de la notion de limitation d’affichage des ressources
Modification de la procédure de fabrication d’un jeton
Evolution des écrans d’ajout d’application
Page 2 sur 10
13/07/2016
Guide utilisateur
SOMMAIRE
1.
PRESENTATION ........................................................................................ 4
1.1. OBJECTIFS DU DOCUMENT ................................................................................ 4
1.2. GENERALITES .............................................................................................. 4
2.
OBTENIR UNE ACCREDITATION ................................................................ 5
3.
FORGER UN JETON .................................................................................... 7
4.
APPELER L’API.......................................................................................... 8
4.1. REQUETE TYPE ............................................................................................. 8
4.2. EXEMPLE DE REQUETES CKAN ........................................................................... 8
4.2.1 Récupérer la liste des jeux de données .................................................... 8
4.2.2 Lire un jeu de données .......................................................................... 8
4.2.3 Lire les informations d’une ressource ....................................................... 9
4.2.4 Lire le contenu d’une ressource .............................................................. 9
4.3. PARTICULARITES POLE EMPLOI ........................................................................... 9
4.3.1 Types de ressource ............................................................................... 9
4.3.2 Versionning .........................................................................................10
V1.5
Page 3 sur 10
13/07/2016
Guide utilisateur
1. Présentation
1.1. Objectifs du document
Ce document a pour objectif de décrire la manière de :
Obtenir une accréditation
Forger un jeton
Appeler l’API
1.2. Généralités
L’API Pôle emploi s’appuie sur la solution d’API management CKAN dont la
documentation est disponible à cette adresse : http://docs.ckan.org/en/ckan2.3/api/
Elle respecte une architecture REST.
Les ressources sont distribuées au format JSON.
L’API est sécurisée via le protocole OAuth 2.0, client credentials.
Tous les appels doivent être passés en HTTPS.
V1.5
Page 4 sur 10
13/07/2016
Guide utilisateur
2. Obtenir une accréditation
Récupérer une accréditation est primordial pour utiliser l’API car permet de vous
authentifier auprès de Pôle emploi. Elle est constituée d’un identifiant client et d’une clé
secrète (client ID et secrey key au sens OAuth 2).
Une accréditation est délivrée suite à l’ajout d’une application depuis votre tableau de
bord seulement si vous avez indiqué souhaiter utiliser au moins une API Pôle emploi.
La création d’une application nécessite simplement de renseigner un nom d’application et
de sélectionner les API que vous souhaitez utiliser.
V1.5
Page 5 sur 10
13/07/2016
Guide utilisateur
Une page de confirmation d’action vous indique votre accréditation unique correspondant
aux API que vous avez contractualisées.
Notez bien ces informations.
Vous pourrez les retrouver dans l’onglet Configuration de votre application.
V1.5
Page 6 sur 10
13/07/2016
Guide utilisateur
3. Forger un jeton
Le jeton ou « access token » doit être passé en en-tête de tous vos appels.
Sa durée de vie est fixée à 10 minutes. Au-delà de ce temps, vous devrez en récupérer
un nouveau.
La requête suivante vous permet de forger un jeton :
POST /identite/oauth2/access_token
Host: www.emploi-store-dev.fr
Content-Type: multipart/form-data; boundary=----WebKitFormBoundary7MA4YWxkTrZu0gW
Cache-Control: no-cache
En-tête
Valeur
Content-Type
application/x-www-form-urlencoded
Body
realm=/developpeur&grant_type=client_credentials&client_id=[identifiantclient]&client_secret=[clé-secrète]
Paramètre
Valeur
realm
developpeur
grant_type
client_credentials
client_id
Saisir votre identifiant client
client_secret
Saisir votre clé secrète
Vous obtiendrez en retour les informations suivantes :
{
"scope": "[identifiant-client] digidata",
"expires_in": 599,
"token_type": "Bearer",
"access_token": "[jeton-généré]"
}
Paramètre
Valeur
scope
Portée du jeton
expires_in
Durée de vie du jeton
token_type
Type de jeton
access_token
Jeton généré
Si l’identifiant client ou la clé secrète est incorrecte, vous obtiendrez un code de retour
400 / bad request :
{
"error": "invalid_client",
"error_description": "Client authentication failed"
}
V1.5
Page 7 sur 10
13/07/2016
Guide utilisateur
4. Appeler l’API
4.1. Requête type
Lors de chaque appel à l’API, vous devez passer en en-tête un jeton valide. Si aucun
jeton n’est passé, s’il est incorrect ou expiré, vous obtiendrez un code de retour 401 /
unauthorized.
Votre requête doit être constituée de la façon suivante :
GET /api/action/[requête] HTTP/1.1
Host: api.emploi-store.fr
Authorization: Bearer [jeton]
En-tête
Valeur
Authorization
Bearer [jeton]
Paramètre
Valeur
requête
Votre requête (cf. 4.2 - Présentation)
4.2. Exemple de requêtes CKAN
4.2.1 Récupérer la liste des jeux de données
La requête suivante vous permettra de récupérer la liste des jeux de données
disponibles :
GET /api/action/organization_show?id=digidata HTTP/1.1
Host: api.emploi-store.fr
Authorization: Bearer [jeton]
Paramètre
Valeur
id
digidata
4.2.2 Lire un jeu de données
La requête suivante vous permettra de récupérer les informations d’un jeu de données :
GET /api/action/package_show?id=[identifiant-dataset] HTTP/1.1
Host: api.emploi-store.fr
Authorization: Bearer [jeton]
Paramètre
Valeur
id
Identifiant du jeu de données
V1.5
Page 8 sur 10
13/07/2016
Guide utilisateur
4.2.3 Lire les informations d’une ressource
La requête suivante vous permettra de récupérer les informations d’une ressource d’un
jeu de données :
GET /api/action/resource_show?id=[identifiant-resource] HTTP/1.1
Host: api.emploi-store.fr
Authorization: Bearer [jeton]
Paramètre
Valeur
id
Identifiant de la ressource
4.2.4 Lire le contenu d’une ressource
La requête suivante vous permettra de lire le contenu d’une ressource :
GET /api/action/datastore_search?resource_id=[identifiant-resource]
HTTP/1.1
Host: api.emploi-store.fr
Authorization: Bearer [jeton]
Paramètre
Valeur
id
Identifiant de la ressource
Si la ressource est trop lourde pour être affichée intégralement, une erreur 500
s’affichera.
Afin de consulter les données, il sera alors nécessaire de limiter l’affichage grâce aux
paramètres LIMIT et OFFSET.
GET /api/action/datastore_search?resource_id=[identifiant-resource]
&limit=XX&offset=XX HTTP/1.1
Exemple : la requête suivante permet de retourner une liste de 10 éléments à partir du
10ème élément (de 11 à 20).
GET /api/action/datastore_search?resource_id=[identifiant-resource]
&limit=10&offset=10 HTTP/1.1
NB : Le paramètre « limit » prend par défaut la valeur 100.
4.3. Particularités Pôle emploi
4.3.1 Types de ressource
Le champ pe_source contient la codification de la ressource pour Pôle emploi.
V1.5
Page 9 sur 10
13/07/2016
Guide utilisateur
Le champ pe_type permet de distinguer le type de ressource.
L’API gère 3 types de ressources :
api
fichier principal des données
documentation
documentation associée au jeu de données
referentiel
contient une partie de la nomenclature Pôle emploi
resources": [
{
"cache_last_updated": null,
"package_id": "445b746a-bbe0-456a-8bee-ea24498242d3",
"webstore_last_updated": null,
"datastore_active": true,
"id": "3424cdfd-45e5-414d-b19f-477a24c443a8",
"size": null,
"state": "active",
"pe_source": "AGENCE_LISTE",
"pe_type": "api",
"hash": "",
"description": "Liste des agences pôles emploi ouvertes au
public",
"format": "CSV",
"tracking_summary": {
"total": 0,
"recent": 0
}
4.3.2 Versionning
Les ressources d’un jeu de données sont versionnées. Le champ pe_version contient le
numéro de version de la ressource pour Pôle emploi.
…
"webstore_url": null,
"mimetype_inner": null,
"pe_version": "1",
"position": 0,
"revision_id": "5eb5108f-834b-4047-ab78-7cb9fc46d81b",
…
Sur un dataset, le champ archivable permet de définir si certaines ressources du jeu de
données sont archivables ou non. Actuellement, c’est le cas uniquement pour le jeu de
données « Statistiques sur le marché du travail ».
...
"update_frequency": "monthly",
"id": "47dbbaba-c983-47df-bd9c-eaeec14bd834",
"metadata_created": "2015-06-19T15:31:52.272501",
"archivable": "true",
"metadata_modified": "2015-06-24T15:42:23.051099",
"author": "Pôle Emploi",
"author_email": "",
…
Le champ pe_status prend 2 valeurs : current (dernière version) ou archive (ancienne
version).
V1.5
Page 10 sur 10
13/07/2016