Commit f8f10493 authored by Matthieu Guionnet's avatar Matthieu Guionnet
Browse files

exemple de json.dumps avec le paramètre ensure_ascii=False pour afficher les...

exemple de json.dumps avec le paramètre ensure_ascii=False pour afficher les unicodes dans le print() qui l'appelle.
Attention ce n'est pas une bonne idée de le faire systèmatiquement. Je pense que c'est True par défaut pour éviter les mauvaises blagues avec les systèmes (OS, DB) qui ne supportent pas l'unicode.
parent 3280ea6d
%% Cell type:markdown id: tags:
# Présentation de l'API de NAKALA
%% Cell type:markdown id: tags:
## 1-À quoi sert NAKALA ?
%% Cell type:markdown id: tags:
NAKALA est un service d'Huma-Num permettant à des chercheurs, enseignants-chercheurs ou équipes de recherche de partager, publier et valoriser tous types de données numériques documentées (fichiers textes, sons, images, vidéos, objets 3D, etc.) dans un entrepôt sécurisé afin de les publier en accord avec les principes du _FAIR data_ (Facile à trouver, Accessible, Interopérable et Réutilisable).
Pour en savoir plus : https://documentation.huma-num.fr/nakala
%% Cell type:markdown id: tags:
## 2-Objectif de la présentation
%% Cell type:markdown id: tags:
Le projet NAKALA se compose des briques suivantes :
- une API au coeur du projet : https://api.nakala.fr/doc
- une interface web de dépôt et de consultation : https://nakala.fr
- un module de création de sites web appelé NAKALA_PRESS
Nous allons présenter ici les principes et le fonctionnement de l'API de NAKALA à travers quelques exemples.
La présentation s'achèvera par la mise en place d'un petit script en [Python](https://fr.wikipedia.org/wiki/Python_(langage)) permettant d'effectuer un dépôt par lots dans NAKALA à partir d'un fichier de métadonnées en [CSV](https://fr.wikipedia.org/wiki/Comma-separated_values) et d'un ensemble de fichiers images.
Cette présentation est destinée à la fois aux personnes souhaitant prendre en main l'API afin de développer une chaîne de traitement ou une application web sur mesure s'appuyant sur NAKALA, mais aussi aux personnes souhaitant simplement comprendre plus concrètement ce que pourrait offrir cette API dans le cadre de leur projet.
Pour suivre cette présentation, les prérequis sont les suivants :
- Connaître le fonctionnement d'un notebook Jupyter : https://youtu.be/6YBsHr10qjc
%% Cell type:markdown id: tags:
## 3-Qu'est-ce qu'une API et à quoi peut servir l'API de NAKALA ?
%% Cell type:markdown id: tags:
Une API (_Application Programming Interface_) permet d'utiliser les données ou fonctionnalités d'une application web depuis une autre application.
Dans le cas de NAKALA, cela peut par exemple permettre à un site web présentant des données de s'appuyer sur l'entrepôt de données de NAKALA afin de bénéficier des services suivants :
- Copie sécurisée des données et des métadonnées sur l'infrastructure d'HUMA-NUM
- Attribution d'un [identifiant pérenne](https://fr.wikipedia.org/wiki/Identifiant_p%C3%A9renne) ([DOI](https://www.doi.org/)) pour permettre leur citation
- Mise à disposition de manière interopérable des métadonnées basée sur les technologies du [Web de données](https://fr.wikipedia.org/wiki/Web_des_donn%C3%A9es)
- Exposition des métadonnées des données par le protocole documentaire [OAI-PMH](https://www.bnf.fr/fr/protocole-oai-pmh)
- Mise à disposition de visionneuses pour différents formats de fichier (image, pdf, csv, audio, vidéo...)
- Moteur de recherche avancé sur les métadonnées et le contenu des fichiers textuels
À titre d'exemple, l'interface web de dépôt et de consultation de NAKALA est elle-même entièrement basée sur l'API de NAKALA.
Cette interface web ne propose pas encore de fonctionnalité de dépôt par lots, mais l'API de NAKALA met à disposition toutes les fonctionnalités nécessaires au développement d'une telle chaîne de traitement sur mesure. C'est ce que nous illustrerons à la fin de cette présentation.
Voici quelques liens vers des projets faisait appel à l'API de NAKALA :
- http://nenufar.huma-num.fr : *Nénufar* (pour Nouvelle édition numérique de fac-similés de référence) vise à publier l'intégralité des premières éditions du Petit Larousse illustré constituant ainsi un nouveau corpus à destination des scientifiques (linguistes, historiens, sociologues…) et du grand public pour améliorer la connaissance et favoriser l'étude de l'histoire et des évolutions récentes de la langue, de la culture, des techniques. Pour ce projet, les scans des pages du dictionnaire sont stockés directement dans NAKALA. Le site web de Nénufar interroge l'[API IIIF Image](https://iiif.io/api/image/3.0/) que propose NAKALA pour gérer différentes résolutions de ces images.
- http://fontegaia.huma-num.fr : Le projet *Fonte Gaia* se décline en un blog (Fonte Gaia Blog, ou FGBlog) et une Bibliothèque Numérique Scientifique 2.0. (Fonte Gaia Bib ou FGBib). Objet de recherche en même temps qu'outil, l'ensemble formé par les « objets numériques » développés dans le cadre du projet a pour vocation de proposer aux italianistes de tous les pays de devenir autant lecteurs que producteurs et commentateurs des éditions numériques publiées sur FGBib et des articles publiés sur FGBlog. Pour ce projet, les images sont stockées directement dans NAKALA. L'[API IIIF Image](https://iiif.io/api/image/3.0/) que propose NAKALA permet à la bibliothèque numérique d'intégrer leurs images dans des [manifests](https://doc.biblissima.fr/iiif-api-presentation) composant les « objets numériques » des manuscrits.
%% Cell type:markdown id: tags:
## 4-Fonctionnement de base d'une API
%% Cell type:markdown id: tags:
Un client (un site web, une application de bureau...) communique avec l'API via de simples requêtes [HTTP](https://fr.wikipedia.org/wiki/Hypertext_Transfer_Protocol).
Ces requêtes sont composées de :
- une URL :
- `https://api.nakala.fr/datas` (pour la gestion des données de NAKALA)
- `https://api.nakala.fr/collections` (pour la gestion des collections de NAKALA)
- ...
- une entête (header) :
- il s'agit de métadonnées sur la requête (Qui fait la requête ? Quel format de réponse est attendu ? ...)
- un verbe :
- `GET` : pour obtenir des informations sur une ressource (une donnée, une collection, un groupe d'utilisateurs, une métadonnée...)
- `POST` : pour créer une ressource
- `PUT` : pour mettre à jour de manière globale une ressource (remplacer la totalité des informations sur une donnée)
- `PATCH` : pour mettre à jour de manière partielle une ressource (modifier que les droits d'accès à une donnée)
- `DELETE` : pour supprimer une ressource
- ...
- un contenu (body) :
- cette information n'est pas toujours nécessaire. Dans le cas de la création d'une ressource, il s'agit par exemple de l'ensemble des informations constituant la ressource.
En fonction de tous ces paramètres, l'API est en mesure de retourner à son tour une réponse HTTP composée de :
- un code de réponse à 3 chiffres ayant chacun une signification :
- `200` : la demande a pu être satisfaite
- `201` : la demande de création a bien été effectuée
- `401` : vous devez vous authentifier pour effectuer cette requête
- `403` : vous n'avez pas les droits pour effectuer cette requête
- `404` : la ressource demandée n'existe pas
- `500` : une erreur s'est produite sur le serveur de l'API
- ...
- une entête (header) :
- il s'agit de métadonnées sur la réponse (Quel est le format de la réponse ? À quelle heure a eu lieu la réponse ? ...)
- un contenu (body)
- cette information peut être vide. Lorsqu'on demande l'ensemble des métadonnées sur une ressource, il s'agit des métadonnées en question.
%% Cell type:markdown id: tags:
## 5-Le format JSON
%% Cell type:markdown id: tags:
Que ce soit pour le contenu d'une requête ou d'une réponse, l'API de NAKALA privilégie comme format d'échange le format [JSON](https://fr.wikipedia.org/wiki/JavaScript_Object_Notation).
Voici un exemple de métadonnées exprimées en JSON. Il s'agit d'un titre (selon le vocabulaire NAKALA) dont la valeur textuelle est en français :
```
{
"value": "Nomenclature 3D du bâtiment C1-C5",
"lang": "fr",
"typeUri": "http://www.w3.org/2001/XMLSchema#string",
"propertyUri": "http://nakala.fr/terms#title"
}
```
%% Cell type:markdown id: tags:
## 6-Exemple d'une requête simple à l'API de NAKALA
%% Cell type:markdown id: tags:
Voici un exemple pour illustrer les principes de base que nous venons de présenter.
Nous allons depuis ce notebook envoyer une requête à l'API pour connaître les informations disponibles sur une donnée publiée dans NAKALA.
La requête sera composée uniquement des paramètres suivants :
- l'URL d'accès à la donnée en question : `https://api.nakala.fr/datas/10.34847/nkl.863cxt5l`
- le verbe `GET` pour demander les informations sur cette donnée
Il ne sera pas nécessaire pour cet exemple de spécifier un entête (header) ou un contenu (body).
Pour effectuer cette requête, nous allons utiliser le langage de programmation [Python](https://fr.wikipedia.org/wiki/Python_(langage)) :
%% Cell type:code id: tags:
``` python
import requests
url = 'https://api.nakala.fr/datas/10.34847/nkl.863cxt5l'
verb = 'GET'
response = requests.request(verb, url)
```
%% Cell type:markdown id: tags:
Affichons quel est le code de réponse de l'API :
%% Cell type:code id: tags:
``` python
print(response.status_code)
```
%%%% Output: stream
200
%% Cell type:markdown id: tags:
Si ce code vaut 200, nous pouvons alors afficher le contenu (body) de la réponse afin de consulter les informations disponibles sur la donnée :
%% Cell type:code id: tags:
``` python
print(response.text)
```
%%%% Output: stream
{"version":1,"collectionsIds":[],"files":[{"name":"Nomenclature3D_C5.csv","extension":"csv","size":562,"mime_type":"text\/csv","sha1":"e66a02e71c57883cf3bf9520022f308f57d141d3","embargoed":"2020-12-22T00:00:00+01:00","description":null,"humanReadableEmbargoedDelay":[]},{"name":"Nomenclature3D_U3D-C5_v0.2.xml","extension":"xml","size":1766,"mime_type":"text\/xml","sha1":"6899d071ee45f87aeb959f15d2a34b85d2723b96","embargoed":"2020-12-22T00:00:00+01:00","description":null,"humanReadableEmbargoedDelay":[]},{"name":"Nomenclature3D_U3D-C5.xml","extension":"xml","size":1769,"mime_type":"text\/xml","sha1":"0303869135ead7b5a76437acc1ac36ce9330312b","embargoed":"2020-12-22T00:00:00+01:00","description":null,"humanReadableEmbargoedDelay":[]}],"status":"published","fileEmbargoed":false,"citation":"Pouyllau, St\u00e9phane et al. (2007) \u00abNomenclature 3D du b\u00e2timent C1-C5\u00bb [Dataset] NAKALA. https:\/\/doi.org\/10.34847\/nkl.863cxt5l","uri":"https:\/\/doi.org\/10.34847\/nkl.863cxt5l","identifier":"10.34847\/nkl.863cxt5l","metas":[{"value":"Nomenclature 3D du b\u00e2timent C1-C5","lang":null,"typeUri":"http:\/\/www.w3.org\/2001\/XMLSchema#string","propertyUri":"http:\/\/nakala.fr\/terms#title"},{"value":"2007","lang":null,"typeUri":"http:\/\/www.w3.org\/2001\/XMLSchema#string","propertyUri":"http:\/\/nakala.fr\/terms#created"},{"value":"CC-BY-NC-ND-4.0","lang":null,"typeUri":"http:\/\/www.w3.org\/2001\/XMLSchema#string","propertyUri":"http:\/\/nakala.fr\/terms#license"},{"value":"http:\/\/purl.org\/coar\/resource_type\/c_ddb1","lang":null,"typeUri":"http:\/\/www.w3.org\/2001\/XMLSchema#anyURI","propertyUri":"http:\/\/nakala.fr\/terms#type"},{"value":"3D","lang":"fr","typeUri":"http:\/\/www.w3.org\/2001\/XMLSchema#string","propertyUri":"http:\/\/purl.org\/dc\/terms\/subject"},{"value":"Renault (automobiles)","lang":"fr","typeUri":"http:\/\/www.w3.org\/2001\/XMLSchema#string","propertyUri":"http:\/\/purl.org\/dc\/terms\/subject"},{"value":"Boulogne-Billancourt","lang":"fr","typeUri":"http:\/\/www.w3.org\/2001\/XMLSchema#string","propertyUri":"http:\/\/purl.org\/dc\/terms\/subject"},{"value":"Fichiers de la nomenclature 2D et 3D du bat. C1-C5 de Renault \u00e0 Boulogne-Billancourt.","lang":"fr","typeUri":"http:\/\/www.w3.org\/2001\/XMLSchema#string","propertyUri":"http:\/\/purl.org\/dc\/terms\/description"},{"value":"fr","lang":null,"typeUri":"http:\/\/www.w3.org\/2001\/XMLSchema#string","propertyUri":"http:\/\/purl.org\/dc\/terms\/language"},{"value":{"givenname":"St\u00e9phane","surname":"Pouyllau","orcid":null,"authorId":"80c4b151-6b74-48f6-b7ce-3a6d0704399d"},"propertyUri":"http:\/\/nakala.fr\/terms#creator"},{"value":{"givenname":"Shadia","surname":"Kilouchi","orcid":null,"authorId":"34397721-6cf4-4e8d-8cf9-f9a6ad6e2a2c"},"propertyUri":"http:\/\/nakala.fr\/terms#creator"}],"creDate":"2020-12-22T07:42:50+01:00","owner":{"username":"spouyllau","givenname":"St\u00e9phane","surname":"Pouyllau","photo":"https:\/\/annuaire.huma-num.fr\/white-pages\/photo.php?id=dWlkPXNwb3V5bGxhdSxvdT1wZW9wbGUsb3U9aHVtYS1udW0sZGM9aHVtYS1udW0sZGM9ZnI=","fullname":"St\u00e9phane Pouyllau"},"isOwner":false,"isAdmin":false,"isEditor":false,"modDate":"2020-12-22T08:14:50+01:00"}
%% Cell type:markdown id: tags:
Mettons un peu en forme ce contenu en JSON afin d'y voir plus clair :
%% Cell type:code id: tags:
``` python
import json
parsed = json.loads(response.text)
print(json.dumps(parsed, indent=4))
print(json.dumps(parsed, indent=4, ensure_ascii=False))
```
%%%% Output: stream
{
"version": 1,
"collectionsIds": [],
"files": [
{
"name": "Nomenclature3D_C5.csv",
"extension": "csv",
"size": 562,
"mime_type": "text/csv",
"sha1": "e66a02e71c57883cf3bf9520022f308f57d141d3",
"embargoed": "2020-12-22T00:00:00+01:00",
"description": null,
"humanReadableEmbargoedDelay": []
},
{
"name": "Nomenclature3D_U3D-C5_v0.2.xml",
"extension": "xml",
"size": 1766,
"mime_type": "text/xml",
"sha1": "6899d071ee45f87aeb959f15d2a34b85d2723b96",
"embargoed": "2020-12-22T00:00:00+01:00",
"description": null,
"humanReadableEmbargoedDelay": []
},
{
"name": "Nomenclature3D_U3D-C5.xml",
"extension": "xml",
"size": 1769,
"mime_type": "text/xml",
"sha1": "0303869135ead7b5a76437acc1ac36ce9330312b",
"embargoed": "2020-12-22T00:00:00+01:00",
"description": null,
"humanReadableEmbargoedDelay": []
}
],
"status": "published",
"fileEmbargoed": false,
"citation": "Pouyllau, St\u00e9phane et al. (2007) \u00abNomenclature 3D du b\u00e2timent C1-C5\u00bb [Dataset] NAKALA. https://doi.org/10.34847/nkl.863cxt5l",
"citation": "Pouyllau, Stéphane et al. (2007) «Nomenclature 3D du bâtiment C1-C5» [Dataset] NAKALA. https://doi.org/10.34847/nkl.863cxt5l",
"uri": "https://doi.org/10.34847/nkl.863cxt5l",
"identifier": "10.34847/nkl.863cxt5l",
"metas": [
{
"value": "Nomenclature 3D du b\u00e2timent C1-C5",
"value": "Nomenclature 3D du bâtiment C1-C5",
"lang": null,
"typeUri": "http://www.w3.org/2001/XMLSchema#string",
"propertyUri": "http://nakala.fr/terms#title"
},
{
"value": "2007",
"lang": null,
"typeUri": "http://www.w3.org/2001/XMLSchema#string",
"propertyUri": "http://nakala.fr/terms#created"
},
{
"value": "CC-BY-NC-ND-4.0",
"lang": null,
"typeUri": "http://www.w3.org/2001/XMLSchema#string",
"propertyUri": "http://nakala.fr/terms#license"
},
{
"value": "http://purl.org/coar/resource_type/c_ddb1",
"lang": null,
"typeUri": "http://www.w3.org/2001/XMLSchema#anyURI",
"propertyUri": "http://nakala.fr/terms#type"
},
{
"value": "3D",
"lang": "fr",
"typeUri": "http://www.w3.org/2001/XMLSchema#string",
"propertyUri": "http://purl.org/dc/terms/subject"
},
{
"value": "Renault (automobiles)",
"lang": "fr",
"typeUri": "http://www.w3.org/2001/XMLSchema#string",
"propertyUri": "http://purl.org/dc/terms/subject"
},
{
"value": "Boulogne-Billancourt",
"lang": "fr",
"typeUri": "http://www.w3.org/2001/XMLSchema#string",
"propertyUri": "http://purl.org/dc/terms/subject"
},
{
"value": "Fichiers de la nomenclature 2D et 3D du bat. C1-C5 de Renault \u00e0 Boulogne-Billancourt.",
"value": "Fichiers de la nomenclature 2D et 3D du bat. C1-C5 de Renault à Boulogne-Billancourt.",
"lang": "fr",
"typeUri": "http://www.w3.org/2001/XMLSchema#string",
"propertyUri": "http://purl.org/dc/terms/description"
},
{
"value": "fr",
"lang": null,
"typeUri": "http://www.w3.org/2001/XMLSchema#string",
"propertyUri": "http://purl.org/dc/terms/language"
},
{
"value": {
"givenname": "St\u00e9phane",
"givenname": "Stéphane",
"surname": "Pouyllau",
"orcid": null,
"authorId": "80c4b151-6b74-48f6-b7ce-3a6d0704399d"
},
"propertyUri": "http://nakala.fr/terms#creator"
},
{
"value": {
"givenname": "Shadia",
"surname": "Kilouchi",
"orcid": null,
"authorId": "34397721-6cf4-4e8d-8cf9-f9a6ad6e2a2c"
},
"propertyUri": "http://nakala.fr/terms#creator"
}
],
"creDate": "2020-12-22T07:42:50+01:00",
"owner": {
"username": "spouyllau",
"givenname": "St\u00e9phane",
"givenname": "Stéphane",
"surname": "Pouyllau",
"photo": "https://annuaire.huma-num.fr/white-pages/photo.php?id=dWlkPXNwb3V5bGxhdSxvdT1wZW9wbGUsb3U9aHVtYS1udW0sZGM9aHVtYS1udW0sZGM9ZnI=",
"fullname": "St\u00e9phane Pouyllau"
"fullname": "Stéphane Pouyllau"
},
"isOwner": false,
"isAdmin": false,
"isEditor": false,
"modDate": "2020-12-22T08:14:50+01:00"
}
%% Cell type:markdown id: tags:
Vous pouvez retrouver dans ce contenu en JSON la version de la donnée, la liste des fichiers qu'elle contient, la liste de ses métadonnées et d'autres informations utiles pouvant être à leur tour exploitées par un programme informatique afin de construire une vue lisible par les humains ou pour d'autres usages.
%% Cell type:markdown id: tags:
## 7-Documentation de l'API
%% Cell type:markdown id: tags:
La documentation de l'API de NAKALA est disponible à cette adresse : https://api.nakala.fr/doc
%% Cell type:markdown id: tags:
Cette documentation décrit l'ensemble des actions possibles à travers l'API de NAKALA. Elle est structurée en 6 grandes parties :
- `search` : le moteur de recherche sur les données et les collections de NAKALA
- `datas` : la gestion des données
- `collections` : la gestion des collections
- `groups` : la gestion des groupes d'utilisateurs
- `users` : la gestion des utilisateurs, de leurs données et de leurs collections
- `vocabularies` : accès aux vocabulaires utilisés dans NAKALA (les langues, les licences, les champs de métadonnées disponibles)
%% Cell type:markdown id: tags:
Dans chacune de ces sections est détaillé une liste de requêtes pour lesquelles il est proposé :
- une description de ce que permet la requête
- le verbe à utiliser pour effectuer cette requête
- l'URL de la requête
- une description des paramètres de requête à prendre en compte
- le modèle du contenu (body) attendu lorsque celui-ci est requis ainsi qu'un exemple
- les codes de réponse possibles et leur signification plus précise dans le contexte de la requête
- le modèle du contenu (body) de la réponse lorsque celui-ci est présent ainsi qu'un exemple
- un formulaire permettant de tester la requête
%% Cell type:markdown id: tags:
Puisque nous parlions du format JSON, sachez que cette documentation est aussi disponible au format JSON : https://api.nakala.fr/doc.json
%% Cell type:markdown id: tags:
Cette documentation suit les spécifications [OpenAPI](https://swagger.io/specification/v2/) (version 2) qui permettent par exemple à d'autres applications de construire "à la volée" des formulaires en accord avec la description que l'API fournie d'elle-même. La page web de documentation de l'API de NAKALA est par exemple générée automatiquement à partir de cette documentation au format JSON. C'est ce qui permet de proposer un espace de démonstration avec des formulaires en permanence à jour avec la dernière version de l'API.
%% Cell type:markdown id: tags:
## 8-Authentification
%% Cell type:markdown id: tags:
Puisque l'API de NAKALA permet à un utilisateur de modifier ou de supprimer des données, il est nécessaire pour ce genre d'action de s'assurer de l'identité de l'utilisateur !
Pour cela, il est possible de soumettre dans l'entête d'une requête à l'API un code secret propre à chaque utilisateur. Il s'agit d'une clé d'API que chaque utilisateur peut obtenir ou mettre à jour depuis son compte dans l'interface web de NAKALA.
Pour cela, vous devez disposer d'un compte [HumanID](https://HumanID.huma-num.fr) et avoir demandé l'accès au service NAKALA depuis le menu "Mes services" :
![Se connecter à HumanID](./illustrations/HumanID.png)
![Ouverture du service NAKALA](./illustrations/service-nakala.png)
Une fois que vous avez accès au service [NAKALA](https://nakala.fr), vous pouvez vous y connecter avec votre compte HumanID.
Depuis l'onglet "Mon profil", vous pouvez alors générer ou mettre à jour votre clé d'API :
![Menu Mon Profil](./illustrations/mon-profil.png)
![Ma clé d'API](./illustrations/ma-cle-d-api.png)
Attention ! Cette clé d'API ne doit pas être partagée avec une autre personne. En cas de doute, n'hésitez pas à la mettre à jour régulièrement. Il n'est pas nécessaire d'obtenir une clé d'API pour utiliser uniquement l'interface web de NAKALA ou le module de création de sites web NAKALA_PRESS.
%% Cell type:markdown id: tags:
Vous pouvez tester votre clé d'API en demandant à l'API de NAKALA de vous fournir les informations principales vous concernant (nom, prénom, mail...).
La requête sera composée des paramètres suivants :
- l'URL d'accès à ces informations : `https://api.nakala.fr/users/me`
- le verbe `GET` pour demander de récupérer ces informations
- Un entête `X-API-KEY` contenant la valeur de votre clé d'API
Voici ce que cela donne depuis un script Python :
%% Cell type:code id: tags:
``` python
# Utilisation dans ce script de l'URL de test avec un compte de démo !
url = "https://apitest.nakala.fr/users/me"
verb = "GET"
headers = {
'X-API-KEY': '01234567-89ab-cdef-0123-456789abcdef'
}
response = requests.request(verb, url, headers=headers)
print(response.text)
```
%%%% Output: stream
{"username":"tnakala","givenname":"Test","surname":"Nakala","mail":"nakala@huma-num.fr","photo":null,"firstLogin":"2020-03-18T11:20:00+01:00","lastLogin":"2021-05-20T15:11:00+02:00","roles":["ROLE_USER"],"apiKey":"01234567-89ab-cdef-0123-456789abcdef","fullname":"Test Nakala"}
%% Cell type:markdown id: tags:
Vous pouvez tester votre clé d'API de la même manière depuis la page de documentation de l'API : https://api.nakala.fr/doc
Rendez-vous dans la section "Users" au niveau de la requête `GET /users/me` :
![GET users/me](./illustrations/get-users-me.png)
Cliquez sur le cadenas pour vos authentifiez :
![Authentification](./illustrations/authentification-apiKey.png)
Une fois que vous avez renseigné votre clé d'API et validé, cliquez sur `close` puis lancez le test en cliquant sur `Try it out` puis `Execute`.
Vous pouvez alors visualiser le résultat de la réponse :
![Réponse de l'API GET users/me](./illustrations/response-get-users-me.png)
%% Cell type:markdown id: tags:
## 9-Mise en pratique de quelques requêtes
%% Cell type:markdown id: tags:
### 9.1-Utilisation de l'espace de test de NAKALA
%% Cell type:markdown id: tags:
Nous allons approfondir l'utilisation de l'API à travers quelques requêtes supplémentaires. Pour cela, nous allons nous appuyer sur la version de test de NAKALA :
- https://test.nakala.fr : Interface web de dépôt et de consultation
- https://apitest.nakala.fr/doc : Documentation de l'API
Cette version de test est toujours à jour par rapport à la version de production de NAKALA. Elle permet aux utilisateurs de tester les fonctionnalités de NAKALA sans risque. Les données et les collections créées dans cette version de test sont supprimées régulièrement. Vous ne devez pas y déposer de données sensibles ou destinées à y être conservées.
Plusieurs comptes de démonstration sont fournis pour vous authentifier à la version de test. Voici le login HumanID, le mot de passe HumanID et la clé d'API NAKALA associés à chacun de ces comptes :
| login HumanID | Mot de passe HumanID | Clé d'API NAKALA |
| ------------- |: ------------------: | :-----------------------------------: |
| tnakala | IamTesting2020 | 01234567-89ab-cdef-0123-456789abcdef |
| unakala1 | IamTesting2020 | 33170cfe-f53c-550b-5fb6-4814ce981293 |
| unakala2 | IamTesting2020 | f41f5957-d396-3bb9-ce35-a4692773f636 |
| unakala3 | IamTesting2020 | aae99aba-476e-4ff2-2886-0aaf1bfa6fd2 |
Note : Vous ne pouvez pas vous authentifier avec d'autres comptes. Même avec votre compte HumanID personnel, cela ne fonctionnera pas dans la version de test.
À partir de maintenant, nous ferons nos requêtes à l'API en utilisant la clé d'API de l'utilisateur *unakala3* :
%% Cell type:code id: tags:
``` python
apiKey = 'aae99aba-476e-4ff2-2886-0aaf1bfa6fd2'
```
%% Cell type:markdown id: tags:
### 9.2-Création d'une collection
%% Cell type:markdown id: tags:
#### 9.2.1-Paramètres de la requête
Pour créer une collection, la requête à l'API de NAKALA sera composée des paramètres suivants :
- URL : `https://apitest.nakala.fr/collections` (il s'agit de l'URL dédiée à la gestion des collections)
- Verbe : `POST` (il s'agit d'une création)
- Contenu (body) : les informations sur la collection à créer (cf. 9.2.2). Elles sont exprimées au format JSON.
- Entêtes (headers) :
- `X-API-KEY: ...` (votre clé d'API)
- `Content-Type: application/json` (pour indiquer que le contenu de la requête est au format JSON)
%% Cell type:markdown id: tags:
#### 9.2.2-Contenu de la requête
Les informations pouvant être transmises dans le contenu de la requête pour la création d'une collection sont les suivantes :
- `status`: le statut de la collection. Les valeurs possibles sont :
- `private` : la collection sera privée et accessible uniquement par les utilisateurs ayant les droits d'accès.
- `public` : la collection sera publique et accessible par tous. Un set OAI sera associé à la collection qui pourra alors être moissonnée par un moteur de recherche comme ISIDORE
- `datas` (facultatif) : liste des identifiants des données à ajouter à la collection. Attention, une collection publique ne peut contenir que des données publiées.
- `metas` : les métadonnées descriptives de la collection. Une métadonnée est composée à son tour des informations suivantes :
- `propertyUri` : chaque métadonnée est exprimée via un champ issu d'un vocabulaire de métadonnées normées. Il peut s'agir d'un vocabulaire interne à NAKALA ou encore du vocabulaire [DublinCore](https://fr.wikipedia.org/wiki/Dublin_Core). La liste des valeurs acceptées est disponible via `GET /vocabularies/properties`.
- `value` : la valeur de la métadonnée (ex: le contenu d'un titre ou d'une date)
- `typeUri` : chaque valeur peut-être typée, c'est-à-dire qu'on peut indiquer si la valeur renseignée est une chaîne de caractères, une URL, un nombre... La liste des valeurs acceptées est disponible via une requête `GET /vocabularies/metadatatypes` à l'API.
- `lang` : lorsque la valeur de la métadonnée est de type textuel, vous pouvez préciser sa langue. Les valeurs acceptées sont issues de la norme ISO-639-1 (ex: 'fr' pour le français) ou ISO-639-3 pour les langues plus rares ('way' pour le wayana). La liste des valeurs acceptées est disponible via `GET /vocabularies/languages`.
- `rights` (facultatif) : la liste des droits associés à la collection. Un droit est composé des informations suivantes :
- `id` : chaque utilisateur ou groupe d'utilisateurs dispose d'un identifiant interne qui lui est propre pour la gestion des droits. Pour connaître l'identifiant d'un utilisateur ou d'un groupe utilisateur, il est possible de faire une requête à `GET /groups/search`.
- `role` : le droit associé à l'utilisateur ou à un groupe d'utilisateurs. Les valeurs possibles sont :
- `ROLE_OWNER` : le propriétaire de la collection. Ce droit est attribué par défaut et il n'est pas nécessaire de le renseigner et il ne peut pas être modifié.
- `ROLE_ADMIN` : l'administrateur de la collection
- `ROLE_EDITOR` : l'éditeur de la collection
- `ROLE_READER` : le lecteur de la collection
Voici un exemple de métadonnée exprimée au format JSON. Il s'agit d'un titre (selon le vocabulaire interne à NAKALA) dont la valeur textuelle est en français :
```
{
"propertyUri": "http://nakala.fr/terms#title",
"value": "La ferme des animaux",
"typeUri": "http://www.w3.org/2001/XMLSchema#string",
"lang": "fr,
}
```
Attention ! Pour qu'une collection puisse être créée, la présence d'une métadonnée `http://nakala.fr/terms#title` est obligatoire !
Voici le contenu minimum à fournir pour créer une collection privée avec un titre en français :
```
{
"status": "private",
"metas" : [
{
"propertyUri": "http://nakala.fr/terms#title",
"value": "La ferme des animaux",
"typeUri": "http://www.w3.org/2001/XMLSchema#string",
"lang": "fr"
}
]
}
```
%% Cell type:markdown id: tags:
#### 9.2.3-Paramètres de la réponse
En fonction des paramètres envoyés dans la requête de création d'une nouvelle collection, l'API sera en mesure de retourner à son tour une réponse HTTP dont les informations les plus importantes seront composées de :
- le code de réponse :
- `201` : la collection a bien été créée (cf. 9.2.4)
- `401` : vous devez vous authentifier pour créer la collection
- `403` : vous n'avez pas les droits pour créer la collection
- `422` : les informations soumises pour la création de la collection ne sont pas valides (cf. 9.2.5)
- `500` : une erreur s'est produite lors de la création de la collection
- le contenu (body) avec des informations plus précises comme l'identifiant attribué à la collection nouvellement créée ou encore un message d'erreur détaillé.
Voici un exemple de contenu de la réponse lorsque la demande de création de collection a bien pu être réalisée :
```
{
"code": 201,
"message": "Collection created",
"payload": {
"id": "10.34847/nkl.b4e1c560"
}
}
```
%% Cell type:markdown id: tags:
#### 9.2.4-Exemple de création d'une nouvelle collection
Voici un exemple complet de création d'une collection :
%% Cell type:code id: tags:
``` python
url = 'https://apitest.nakala.fr/collections'
verb = 'POST'
headers = {
'X-API-KEY': apiKey,
'Content-Type': 'application/json'
}
content = {
"status": "private",
"metas" : [
{
"propertyUri": "http://nakala.fr/terms#title",
"value": "La ferme des animaux",
"typeUri": "http://www.w3.org/2001/XMLSchema#string",
"lang": "fr"
}
]
}
createCollectionResponse = requests.request(verb, url, headers=headers, data=json.dumps(content))
```
%% Cell type:markdown id: tags:
Vérifions le code de réponse de l'API :
%% Cell type:code id: tags:
``` python
print(createCollectionResponse.status_code)
```
%%%% Output: stream
201
%% Cell type:markdown id: tags:
Affichons le contenu de la réponse mis en forme :
%% Cell type:code id: tags:
``` python
parsedcreateCollectionResponse = json.loads(createCollectionResponse.text)
print(json.dumps(parsedcreateCollectionResponse, indent=4))
```
%%%% Output: stream
{
"code": 201,
"message": "Collection created",
"payload": {
"id": "10.34847/nkl.bd7e9p3x"
}
}