Services Web spécifiques¶
Authentification¶
L’authentification est effectuée en envoyant des requêtes signées à CubicWeb. Il faut commencer par créer un jeton d’authentification pour l’utilisateur en question, et sauvegarder l’identifiant et le secret du jeton quelque-part.
La création du jeton se fait via l’action « profil » du menu utilisateur, puis en cliquant sur l’action « add token » du sous-menu « ajouter » de la boite d’actions.
Sur la base de cet identifiant et secret du jeton, on authentifie une requête HTTP en ajoutant dans les en-têtes :
Content-MD5
: le hash MD5 du corps de la requêteDate
: la date d’émission de la requête au format “%a, %d %b %Y %H:%M:%S GMT” (heure GMT donc)Authorization
: “Cubicweb <token-id>:<signature>” avec <token-id> l’identifiant du jeton et <signature> une signature HMAC (RFC 2104) de la concaténation :- du verbe HTTP (“GET”, “POST”, etc),
- de l’URL,
- des en-têtes HTTP
Content-MD5
,Content-Type
etDate
,
en utilisant le secret.
À noter qu’il est important que l’heure du client et serveur soient synchronisées. Il est donc recommandé d’utiliser un serveur NTP sur chaque machine.
Listes des services¶
Pour obtenir les données au format RDF XML, il convient de positionner l’en-tête HTTP Accept
pour la négociation de contenu.
Description des vocabulaires¶
Liste des jeux de données au format RDF SKOS (XML)
GET /conceptscheme
Accept: application/rdf+xml
Description complète du jeu de données au format RDF SKOS (XML)
GET /conceptscheme/<eid>
Accept: application/rdf+xml
Description des services archives¶
Liste des services d’archives avec leur services versants
GET /archival-units
Accept: application/json
Exemple de réponse :
[
{
"ark": "23578/ou000190053",
"name": "Gironde. Archives départementales",
"state": "published",
"url": "http://orion.tls.logilab.fr:8080/ark:/0/ou000117240",
"authority": {
"ark": "XXX/o20",
"name": "Test saem",
"url": "http://orion.tls.logilab.fr:8080/ark:/XXX/o20"
},
"deposit-units": [
{
"ark": "75548/ou000117317",
"name": "Cenon. service de la Commande publique",
"state": "published",
"url": "http://orion.tls.logilab.fr:8080/ark:/75548/ou000117317",
"authority": {
"ark": "XXX/o13",
"name": "Ville de Cenon",
"url": "http://orion.tls.logilab.fr:8080/ark:/XXX/o13"
}
},
{
"ark": "75548/ou000117342",
"name": "Direction du Patrimoine",
"state": "published",
"url": "http://orion.tls.logilab.fr:8080/ark:/75548/ou000117342",
"authority": {
"ark": "XXX/o19",
"name": "Conseil départemental",
"url": "http://orion.tls.logilab.fr:8080/ark:/XXX/o19"
}
}
]
}
]
Allocation d’identifiants ARK¶
Le point d’accès /ark
permet d’obtenir un identifiant ARK à partir d’une
autorité administrative (collectivité) spécifié via le paramètre de requête
organization=<identifiant ARK>
. L’identifiant d’une autorité administrative
peut être obtenu à partir des données RDF (elles-mêmes disponibles via une
requête OAI-PMH sur une unité administrative) en récupérant la valeur du champ
dc:identifier
(normalement une chaîne de caractères commençant par
“ark://”).
Pour utiliser ce service il faut être authentifié.
Exemple de requête :
POST /ark&organization=ark%3A%2F%2F12345%2Fo67
Accept: application/json
Exemples de réponse (JSON)
[{'ark': '12345/ext-000000001'}]
[{'error': 'This service is only accessible using POST.'}]
[{'error': 'This service requires authentication.'}]
[{'error': 'Organization "12345/o67" cannot assign ARK identifiers.'}]
[{'error': 'No organization matching identifier "12345/o67".'}]
[{'error': 'Missing required "organization" query parameter.'}])
Import d’une notice d’autorité au format XML EAC¶
Il est possible de poster un fichier XML EAC sur point d’accès /authorityrecord
afin d’importer
la notice d’autorité qu’il décrit. Ce service renverra l’identifiant ARK de la notice importée ou
bien une erreur en cas de problème (voir les exemples ci-dessous).
Pour utiliser ce service, il faut être identifié avec le compte d’un utilisateur qui est lié à une autorité administrative, elle-même liée à une autorité nommante.
Exemple de requête :
POST /authorityrecord
Content-Type: application/xml
Accept: application/json
<?xml version="1.0" encoding="UTF-8"?>
<eac-cpf>
<control>
...
</eac-cpf>
Exemples de réponse (JSON)
[{'ark': '12345/r000000042'}]
[{'error': 'This service requires authentication.'}]
[{'error': 'Authenticated user is not linked to an organisation,
or his organisation has no ARK naming authority..'}]
[{'error': u'Invalid XML file',
'details': "Start tag expected, '<' not found, line 1, column 1"}]
[{'error': 'Unexpected EAC data',
'details': 'Missing tag control in XML file'}])
OAI-PMH¶
On implémente les 6 types de requêtes (verbes) du protocole :
- GetRecord
- Identify
- ListIdentifiers
- ListMetadataFormats
- ListRecords
- ListSets
Moissonnage sélectif¶
On supporte le moissonnage sélectif à l’aide des Sets hiérarchiques avec a priori un hiérarchie à deux niveaux (pour l’instant, seul le cas des agents est vraiment concret pour l’aspect hiérarchique).
Le premier niveau hiérarchique correspond au type d’entité sur lequel il faut filtrer la réponse, on a 3 types de filtrage possible :
- agent : agents
- organizationunit : unités administratives
- profile : profils SEDA
- conceptscheme : vocabulaires contrôlés
- concept : concepts issus d’un vocabulaire contrôlé
Ainsi une requête pour obtenir la liste des identifiants des agents du
référentiel prend la forme : <baseurl>oai?ListIdentifiers&set=agent
Pour le cas des unités administratives, on supporte un axe de hiérarchie :
role
: les rôles archivistiques (service versant, service de contrôle, etc.)
Le prototype d’une requête avec un spécification de set hiérarchique est :
<baseurl>oai?verb=<VERB>&set=<entity type>:<axis name>:<axis value>
Exemple de requêtes¶
ListSets
<baseurl>/oai?verb=ListSets
ListIdentifiers avec un filtrage set (obligatoire dans notre cas) :
<baseurl>oai?verb=ListIdentifiers&set=organizationunit
ListIdentifiers avec filtrage hiérarchique :
<baseurl>oai?verb=ListIdentifiers&set=organizationunit:role:deposit
ListRecords avec ou sans filtrage hiérarchique :
<baseurl>oai?verb=ListRecords&set=conceptscheme <baseurl>oai?verb=ListRecords&set=organizationunit:role:deposit
GetRecord avec spécification de l”identifier (obligatoire dans notre cas) :
<baseurl>oai?verb=GetRecord&identifier=ark:/01234/000004145
Moissonnage sélectif d’objets reliés à d’autres objets¶
Certains Sets définis dans le référentiel permettent de moissonner des objets
en fonction de leur relation avec d’autres objets. C’est le cas par exemple
des concepts en fonction de leur appartenance à un vocabulaire à l’aide du set
concept:in_scheme:<scheme identifier>
ou encore des profils
sélectionnables par service versant à l’aide du set
profile:transferring_agent:<agent identifier>
.
Dans ces cas, le set prend la forme :
<type d'objet>:<relation>:<identifiant>
Il n’est pas possible selon la norme OAI d’utiliser des identifiants ARK pour les sets du
moissonnage sélectif car ces derniers contiennent des caractères interdits (:
et /
notamment). Ce problème reste à résoudre à ce jour. Pour le moment, l’identifiant ARK peut-être
directement utilisé simplement en retirant le préfix « ark:/ ».
Format des enregistrements record des réponses OAI-PMH¶
Pour les requêtes GetRecord et ListRecords, la réponse OAI-PMH contient
deux balises à l’intérieur de la (ou des) balise(s) <record>
:
- la balise
<header>
, qui contient l”identifier de l’enregistrement ainsi que sa date de modification ; - la balise
<metadata>
qui contient les données de l’enregistrement dont le format dépend du type d’objet de la requête.
Pour les objets de type agent et vocabulaire contrôlé, la balise
<metadata>
contient une représentation RDF des entités. Pour les profils
SEDA, on renvoie le XSD SEDA en version 0.2.