Les web services de l'Inist

@François Parmentier François Parmentier authored on 17 Sep 2021
FT2C-EZmaster readme 1 year ago
NLP_tools-EZmaster readme 1 year ago
affiliations-libpostal examples.http 1 year ago
affiliations-rnsr docs(affiliations): Update READMEs 1 year ago
affiliations-tools docs(affiliations-tools): idRNSR.value is an array 1 year ago
ark-tools missing file 1 year ago
biblio-tools retrieve has_repository_copy 1 year ago
loterre-resolvers fix localization 1 year ago
loterre-xslt/ v1 add WS to register all concepts of a collection with ARK identifers 1 year ago
terms-extraction/v1/ teeft import legacy ws 1 year ago
www-home update home 1 year ago
.gitignore chore(affiliations-rnsr): Ignore swagger.json 1 year ago
.npmignore import loterre resolver 1 year ago
.npmrc import loterre resolver 1 year ago
CHANGELOG.md add changelog 1 year ago
README.md fix doc 1 year ago
package.json 1.1.0 1 year ago
README.md

Les web services TDM de l'Inist

Tester

Des exemples de requetes sont disponbiles dans des fichers examples.http ceux-ci peuvent être utilisés directment dans VSCode, avec l'extension REST Client (humao.rest-client) Ils peuvent également être lancés en ligne de commande via rest-cli ou via dot-http

Exemple 1 : lancement des exemples sans affichage

$ restcli  ./biblio-tools/examples.http
examples:1 [1] POST https://biblio-tools.services.inist.fr/v1/unpaywall/is_oa?indent=true
examples:2 [1] POST https://biblio-tools.services.inist.fr/v1/crossref/prefixes/expand?indent=true
$

Exemple 2 : lancement des exemples avec affichage


$ restcli --full  ./affiliations-libpostal/examples.http
examples:1 [1] POST https://affiliations-libpostal.services.inist.fr/v1/parse?indent=true
POST https://affiliations-libpostal.services.inist.fr/v1/parse?indent=true
Content-Type: application/json

[
    {
        "value": "Barboncino 781 Franklin Ave, Crown Heights, Brooklyn, NY 11238"
    }
]

HTTP/1.1 200 OK
Access-Control-Allow-Origin: *
Connection: close
Content-Disposition: inline
Content-Encoding: gzip
Content-Type: application/octet-stream
Date: Fri, 23 Jul 2021 09:00:14 GMT
Server: nginx/1.15.10
Transfer-Encoding: chunked

[{
    "value": {
        "id": "Barboncino 781 Franklin Ave, Crown Heights, Brooklyn, NY 11238",
        "value": {
            "house": "barboncino",
            "house_number": "781",
            "road": "franklin ave",
            "suburb": "crown heights",
            "city_district": "brooklyn",
            "state": "ny",
            "postcode": "11238"
        }
    }
}]
$

Développement en local

  • Pour les services utilisant lodex-workers :

Lancement du serveur local

$ cd loterre-resolvers
$ ezs -v -d .

le webservice est accessible à cette adresse http://localhost:31976

Déclarer la documentation Swagger

Le répertoire www-home contient le HTML de la page d'accueil https://services.inist.fr.

Si la racine de votre service répond une documentation respectant OpenAPI 3.0 (swagger), il vous suffit de la déclarer dans www-home/index.html pour qu'elle soit prise en compte.

Convention de nommage

Chaque instance sur l'ezmaster de la machine aura un nom en trois parties:

  1. texte (domaine)
  2. texte (spécialité)
  3. numéro (version)

La troisième partie du champ ne doit pas être communiquée à l'extérieur, c'est un numéro de version (si plusieurs instances ont les mêmes deux premiers champs, c'est la dernière version qui est exposée quand on n'utilise pas de numéro de version, ce qui sera le cas).

Le numéro de version permet la mise à jour de l'image docker associée au webservice.

Nom de l'instance

Les champs textuels sont obligatoirement en minuscules, et sans accent (mais peuvent contenir des chiffres) et donc de préférence en anglais. Ils ne doivent pas contenir un nom de personne.

La première partie décrit le domaine d'application du webservice. Exemple : affiliation, text, classification, nlp, etc.

La seconde partie décrit une spécialité du domaine. Cette spécificité est principalement liée à une image docker différente, comme c'est le cas, si les différents web services d'un domaine utilisent des langages différents (C++, python, nodejs, etc.)

Nom des répertoires

Chaque instance donne accès à une arborescence de webservices. Le nom de route dépend du nom des répertoires. Les noms des répertoires doivent donc être choisis dans cette optique.

Il convient donc de respecter les pratiques communément admises dans la définition d'API de type REST. En utilisant des noms de répertoires en minuscules, sans accent (mais pouvant contenir des chiffres) et de préférence en anglais.

Si le premier niveau caractérise obligatoirement la version, les suivants peuvent être adaptés selon le besoin. On veillera à créer un répertoire si et seulement si il propose plusieurs sous-répertoire ou fichiers.

  1. Version des APIs (v1, v2, v3, etc.)
  2. Nom de l'algorithme ou de la ressource utilisés ou de la langue
  3. Nom de l'action ou de l'algorithme caractérisant le traitement
  4. (...)

Exemple :

  • /v1/test/analyse
  • /v2/istex/expand
  • /v1/en/stemmer/analyse