Qu'est-ce que l'API ISTEX ?

La plate-forme ISTEX fournit l'ensemble de ses services sous la forme d'une API Web utilisant le protocole HTTP dans un esprit Restful.

Les principaux services de l'API permettent :

  • d'effectuer des recherches au sein des ressources mises à disposition
  • d'accéder aux documents trouvés, en choisissant parmi l'ensemble des formats proposés

Selon le type de requête, une authentification sera nécessaire ou non.

Sont en accès libre :

  • la recherche (toutes options incluses)
  • l'accès aux métadonnées (formats JSON et MODS)

L'accès aux formats de fichiers suivant est en accès contrôlé, et nécessite une étape d'authentification :

  • PDF (fulltext)
  • TEI (fulltext et enrichissements)
  • XML original (tel que fourni par l'éditeur, contient parfois du fulltext)
  • formats divers (images, vidéo, son...) correspondant aux annexes et aux couvertures

S'authentifier sur l'API

Pour accéder aux ressources en accès contrôlé, 3 modes d'authentification sont possibles :

  1. l'authentification par adresse IP
  2. l'authentification par fédération d'identités, ouvert automatiquement à tous les personnels de l'enseignement supérieur et de la recherche (ESR)
  3. l'accès nomade basé sur un annuaire LDAP centralisé

Authentification par adresse IP

Ce mode d'authentification est dépendant de l'endroit à partir duquel vous accédez à l'API. Concrètement, si vous vous connectez depuis un établissement autorisé (unité, laboratoire, université...), l'API vous donnera automatiquement accès aux ressources en accès contrôlé, en se basant sur l'adresse IP de votre ordinateur (ou du reverse-proxy de votre établissement, s'il en possède un)

Si votre établissement n'est pas encore autorisé

Vous (ou une personne habilitée) devez demander l'ajout de votre établissement à la liste des bénéficiaires, en vous rendez à l'adresse https://acces.licencesnationales.fr/

Une fois cette demande validée par l'ABES, elle sera diffusée à l'ensemble des portails (éditeurs, par exemple) et services concernés le 1er du mois suivant. L'équipe technique en charge de l'API pourra ensuite intégrer cette autorisation pour la rendre effective.

Authentification par fédération d'identités

Tout comme le mode nomade, ce mode d'authentification est indépendant de votre localisation géographique. Il permet à tout personnel de l'Enseignement Supérieur et de la Recherche (ESR) d'accéder à l'ensemble des ressources de l'API sans demande d'autorisation préalable. Pour ce faire, l'API va déléguer le mécanisme d'identification à la fédération d'identité de Renater, qui vous redirigera vers votre fournisseur d'identité (ex : Janus pour le CNRS).

Ce mode d'authentification peut être exploité de 2 manières :

  • de manière complètement transparente, lorsque l'API est interfacée dans un site web
  • de manière programmatique, ce qui est utile pour extraire des sous-corpus issus de la base ISTEX, par exemple

Accès depuis un portail ou un site ayant intégré l'API

Si vous accédez aux ressources ISTEX via un portail ou un site web qui communique de manière transparente à l'API, vous n'avez pas de démarche particulière à effectuer. Lorsque cela sera nécessaire, vous serez automatiquement redirigé :

  1. sur la page de choix de votre établissement
  2. chez votre fournisseur d'identité, qui vous demandera de saisir vos identifiants habituels (ou votre certificat si vous en possédez un)
  3. la redirection vers la page demandée initialement est automatique

Page de choix de votre établissement (comptes CRU non autorisés)
Page de choix de votre établissement

Exemple de formulaire de connexion d'un fournisseur d'identité : ici Janus, qui est utilisé pour les personnels CNRS
Page de choix de votre établissement

Note à l'attention des webmestres et responsables techniques des portails désirant intégrer ce processus :
Pour déclencher la redirection vers la page Renater de choix de l'établissement (WAYF), il suffit d'ajouter le paramètre d'URL auth=fede aux requêtes HTTP faites à l'API ISTEX.

Exemple :
https://api.istex.fr/document/992E[...]A16B/fulltext/pdf?auth=fede (tester en cliquant)

Accès programmatique, via un token d'identification

Pour rappel, ce mode d'accès peut être utile dans le cadre de vos travaux de recherche si vous avez besoin de constituer un sous-corpus issu des ressources ISTEX. De manière générale, ce mode d'accès est utile à partir du moment où vous souhaitez scripter et automatiser les requêtes à l'API.

La mise en place de cet accès se fait en deux temps :

  1. la génération d'un "token" (ou jeton) personnel, lié à votre compte chez votre fournisseur d'identité
  2. l'utilisation de ce token lors de l'accès aux ressources protégées.

Note importante :
Le token mis en oeuvre dans cette méthode est strictement personnel. Il ne doit en aucun cas être partagé avec d'autres personnes, y compris vos collègues proches. Ceux-ci pourront aisément en obtenir un eux-mêmes.
Il ne doit pas non plus être utilisé pour interfacer l'API dans un site web tiers : l'authentification par adresse IP ou via le paramètre d'URL auth=fede sont faits pour ça.
Dans le cas où votre token personnel serait diffusé et utilisé par une personne non autorisée, votre responsabilité pourrait être engagée.

1ère étape : génération du token

Pour générer un nouveau token, connectez-vous à l'adresse https://api.istex.fr/token/ dans votre navigateur.
Vous serez automatiquement redirigés vers le mécanisme d'authentification par fédération d'identité (cf paragraphe précédent).
Une fois l'authentification effectuée, vous serez redirigés vers l'API ISTEX, qui vous communiquera votre token dans une réponse au format JSON, comme illustré sur l'image suivante :

Page de choix de votre établissement

Le token est disponible dans le champ _accessToken. Ce token suit le format standard JWT. Consulter le site https://jwt.io pour plus de détails

2ème étape : utilisation du token

Maintenant que vous disposez d'un token valide, vous n'avez plus qu'à l'inclure à vos requêtes pour pouvoir accéder aux URL protégées de l'API.

Pour ce faire, vous devez utiliser le header HTTP Authorization et lui donner la valeur Bearer ${TOKEN} (remplacer ${TOKEN} par la vraie valeur de votre token)

Exemple d'utilisation en ligne de commande :

curl -i "https://api.istex.fr/document/${ID_ISTEX}/fulltext/pdf" -H "Authorization: Bearer ${TOKEN}" -o output.pdf

Si vous remplacez ${ID_ISTEX} par un identifiant ISTEX et ${TOKEN} par votre token valide, cette commande téléchargera la ressource au format PDF dans le fichier output.pdf

Ce principe est adaptable à n'importe quel langage de programmation, bibliothèque ou outil qui implémente le protocole HTTP.

Note importante :

Pour le moment, les tokens générés sont valides pour une durée indéterminée. L'ensemble des tokens sont chiffrés à l'aide d'une "passphrase" privée stockée sur nos serveurs. Par conséquent, l'ensemble des token pourra être révoqué lorsque nous modifierons cette "passphrase".

Accès nomade (LDAP)

Principe

Ce mode d’accès créé avant la mise en place de l'authentication par la fédération d’identités permettait d'accéder à l'API en dehors de votre établissement (télétravail, autorisation de votre établissement en attente de validation...) grâce à un login + mot de passe gérés par l'annuaire LDAP de l'INIST-CNRS.

Mode d'utilisation

  • Si vous vous connectez via un navigateur, ce dernier affichera une fenêtre d'authentification où il sera nécessaire de renseigner votre adresse mail comme identifiant et votre mot de passe.
  • Si vous souhaitez vous connecter en ligne de commande, il vous sera nécessaire de rentrer les paramètres suivants :
    • Pour curl : curl -u :{mot de passe} {URL de l'API}
    • Pour wget : wget --user= --password={mot de passe} {URL de l'API}

Note technique : ce mode d'authentification est une mise en oeuvre de la méthode "Basic" de l'authentification HTTP. Son utilisation est possible depuis n'importe quel langage de programmation ou bibliothèque qui implémente le protocole HTTP.

!!! ATTENTION !!!

Cependant ce type de connexion est amené à disparaître prochainement et n'est plus prioritaire. Pour privilégier ce mode d’authentification, tant qu'il est encore disponible, rajouter auth=ldap dans votre URL. https://api.istex.fr/document/F11C03882643184B3D12B60F771ADCB6FD23533A/fulltext/pdf?auth=ldap

URL de vérification de connexion

Si vous souhaitez vérifier que vous êtes bien authentifié sur l'API, vous pouvez utiliser la route https://api.istex.fr/auth