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ête

  • Date: 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 et Date,

    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.