Communication : Le middleware Crossref évolue

crossref-logo

Bonjour,

 

Depuis plusieurs années maintenant, l’enrichissement via l’API de Crossref est activé par défaut lors des traitements de fichiers de log par ezPAARSE. Pour rappel, Crossref nous permet de récupérer les informations bibliographiques des ressources consultées, à partir de leur identifiant (DOI ou PII). Cet enrichissement apporte une grande valeur ajoutée, car il donne accès à des informations utiles : titre de la revue et de l’article, domaine scientifique, éditeur, date de publication…

Or, l’adoption grandissante d’ezPAARSE dans les établissements, ainsi que notre partenariat avec OCLC (éditeur d’EZproxy), ont pour effet de grandement augmenter la charge soumise à cette API. Il en résulte des lenteurs occasionnelles, parfois même des interruptions de service, entraînant des erreurs et l’arrêt des traitements ezPAARSE. En réponse à ces problèmes, et pour aider l’API Crossref à respirer un peu, le middleware Crossref évolue.

 

Préambule : on n’est jamais mieux servi que par soi-même

Les optimisations dont nous allons parler nécessitaient de pouvoir agir sur les headers HTTP échangés avec l’API. Jusqu’ici, le middleware était dépendant d’un module externe gérant les requêtes à notre place. Bien que pratique d’utilisation, ce dernier manque cruellement de flexibilité, et ne semble plus maintenu à ce jour. Il a donc été supprimé, nous donnant ainsi un bien meilleur contrôle sur les échanges HTTP.

 

1 – En cas d’erreur, soyons patients

Lorsqu’une requête échoue, un délai d’une seconde est maintenant observé avant de renouveler l’essai. Ce délai double à chaque tentative, laissant du temps à l’API pour se remettre sur pieds sans compromettre le traitement. Plusieurs headers permettent de paramétrer le comportement à adopter en cas d’erreur :

  • Crossref-Base-Wait-Time : correspond au temps à attendre (en millisecondes) après le premier échec d’une requête. Ce temps vaut 1000 par défaut et double à chaque tentative.
  • Crossref-Max-Tries : il s’agit du nombre maximal d’essais avant que l’enrichissement ne soit considéré comme échoué. Ce nombre est de 5 par défaut.
  • Crossref-On-Fail : définit le comportement à adopter si le nombre maximum de tentatives est dépassé. La valeur peut être abort (annuler le traitement, le comportement par défaut), ignore (ne pas enrichir les ECs et continuer le traitement), ou retry (réessayer indéfiniment).

2 – On ne court pas dans les couloirs

Lors des échanges, l’API Crossref transmet des headers particuliers, X-Rate-Limit-Limit et X-Rate-Limit-Interval, afin de recommander un taux maximum de requêtes par seconde. Si les requêtes sont trop concentrées et que l’API est débordée, celle-ci peut retourner une erreur 429 invitant à réduire la voilure. L’accès aux headers permet à présent au middleware d’ajuster sa vitesse en fonction des recommandations fournies en continu par Crossref. Ce qui peut se traduire par un ralentissement… mais également par une accélération, quand l’API est en pleine forme.

 

3 – N’oublions pas les bonnes manières

Crossref fait le choix de laisser un accès libre et gratuit à son API. En contrepartie, une certaine politesse est attendue de la part de ses utilisateurs, afin de limiter les abus et de maintenir un niveau de service acceptable pour tous. Parmi ces règles de courtoisie, on retrouve la mise en cache des résultats et l’adaptation du taux des requêtes, deux conditions maintenant remplies par ezPAARSE.

Mais avant d’entretenir une conversation, la plus simple des politesses reste de se présenter. Nous ajoutons donc à présent une « étiquette » à nos requêtes, via le header User-Agent, pour permettre à l’équipe de Crossref de nous contacter plus facilement en cas de problème lié aux enrichissements d’ezPAARSE. Si vous traitez des logs volumineux, nécessitant de nombreux enrichissements Crossref, nous vous invitons à personnaliser cette étiquette via le header Crossref-User-Agent.

 

4 – Le service avant tout

Crossref propose un abonnement Metadata Plus donnant accès, moyennant finance, à un meilleur niveau de service. Si vous y avez souscrit, le middleware peut désormais en tirer parti : en renseignant votre token d’accès dans le header Crossref-Plus-API-Token, le middleware pourra utiliser votre accès privilégié à l’API.

 

Tous ces changements ont pour but de stabiliser les traitements ezPAARSE, en limitant les arrêts liés à Crossref. À mesure que la charge globale augmente, il devient de plus en plus important d’utiliser l’API de manière raisonnée, afin de diminuer au maximum notre impact sur le service. Nous vous invitons donc à mettre vos middlewares à jour pour profiter de ces évolutions, et pour aider Crossref à maintenir un niveau de service acceptable.

Les paramètres du middleware sont documentés à cette adresse, et l’équipe reste toujours disponible à l’adresse ezteam@couperin.org pour répondre à vos questions.

Happy paarsing à tous !

Yannick Schurter pour ezTEAM