forked from Inist-CNRS/web-services
-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathswagger.json
33 lines (33 loc) · 7.38 KB
/
swagger.json
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
{
"openapi": "3.0.0",
"info": {
"title": "data-topcitation - Référence phare d'un corpus",
"description": "Extraction des 10 références phares d'un corpus.\n\nComme ces services s'appliquent à un corpus entier, la réponse finale n'est pas\ndonnée immédiatement après l'appel. \nAu contraire, un service comme [`/v1/topcitation`](#data-topcitation/v1/topcitation) renverra\nune réponse JSON contenant un champ `value` donnant l'identifiant du traitement\nen cours. \nEt comme on lui passe aussi l'URL d'un *webhook*, cela lui permet, une fois le\ntraitement terminé, de signaler qu'on peut dès lors utiliser le service de\nrécupération (les routes qui commencent par `/v1/retrieve`). \n\nExemple: traitement d'un corpus de doi\n\n### Préparation du corpus\n\nOn crée une archive `.tar.gz` de fichiers `.json`.\n\nSi on a un répertoire `corpus` contenant ces fichiers `.json`:\n\n```txt\ncorpus\n├── W2BVWkiVT.json\n├── W2CeZqyNR.json\n├── W77S4YQqx.json\n├── W8kkWKySy.json\n├── WcKPMhj3p.json\n├── WG5aHJqba.json\n├── Wh3itHprz.json\n├── WhW6tZ6NH.json\n├── WjS3eZyG4.json\n├── Wk6YCLbzZ.json\n├── WmiHPaEdf.json\n├── WmJYZipzE.json\n├── Wn8KqZXeX.json\n├── WPpTXDTJB.json\n├── WpRjkUwwB.json\n├── WtCWN5q5Y.json\n├── WtJ4NNWhq.json\n├── WTxTnPGxt.json\n├── WwzTseBX6.json\n├── WXer3K9QE.json\n├── Wymfn7YTm.json\n└── WzXkqs4zt.json\n```\n\nChaque fichier `.json` est un objet JSON, sur une seule ligne, contenant deux champs:\n\n1. `id`: un identifiant\n2. `value`: le doi à traiter\n\nExemple pour `corpus/W2BVWkiVT.json`:\n\n```json\n{\"id\":\"0\",\"value\":\"https://doi.org/10.1021/ja800073m\"}\n```\n\nLa commande Linux suivante crée le fichier `corpus.tar.gz` conforme à ce qui est\nattendu par le service web.\n\n```bash\ntar czf corpus.tar.gz corpus\n```\n\n### Appel du traitement\n\nIci, il faut donner un [*webhook*](https://fr.wikipedia.org/wiki/Webhook) pour\nconnaître l'instant où on peut (ou non) récupérer le résultat.\n\n```bash\ncurl -X 'POST' \n 'https://data-topcitation.services.istex.fr/v1/topcitation' \n -H 'accept: application/json' \n -H 'X-Webhook-Success: https://webhook.site/2caab8b5-fc96-4d7a-bb94-bdda20977830' \n -H 'X-Webhook-Failure: https://webhook.site/2caab8b5-fc96-4d7a-bb94-bdda20977830' \n -H 'Content-Type: application/x-gzip' \n --data-binary '@corpus.tar.gz'\n```\n\n> ⚠️ Attention : Les `webhooks` présents dans cet exemple ne sont plus valides.\n\nL'appel précédent renvoie une réponse du type:\n\n```json\n[{\n \"id\": \"topcitation\",\n \"value\": \"qiCVLyh5p\"\n}]\n```\n\nEt le serveur du *webhook* recevra, une fois le traitement terminé, un JSON\ncontenant un champ `identifier` (la même valeur que `value` dans la réponse au\n`curl`), et un champ `state` qui devrait être `ready`. \nIci c'est `qiCVLyh5p`.\n\n### Récupération du résultat\n\nEnfin, on peut demander la réponse via\n[`/v1/retrieve-json`](#data-topcitation/post-v1-retrieve-json), en n'oubliant\nd'adapter `value`:\n\n```bash\ncurl -X 'POST' \n 'http://localhost:31976/v1/retrieve-json' \n -H 'accept: json' \n -H 'Content-Type: json' \n -d '[\n {\n \"value\": \"qiCVLyh5p\"\n }\n]'\n```\n\nqui donnera ce résultat\n\n```json\n[{\n \"id\": \"n/a\",\n \"value\": [\n {\n \"citation\": \"https://doi.org/10.1007/bf01303701\",\n \"count\": 6,\n \"doi\": [\n \"https://doi.org/10.1021/ja800073m\",\n \"https://doi.org/10.1126/science.235.4793.1196\",\n \"https://doi.org/10.1103/physrevlett.58.908\",\n \"https://doi.org/10.1103/revmodphys.70.1039\",\n \"https://doi.org/10.1103/revmodphys.66.1125\",\n \"https://doi.org/10.1103/physrevb.37.3759\"\n ]\n },\n {\n \"citation\": \"https://doi.org/10.1103/physrev.115.2\",\n \"count\": 3,\n \"doi\": [\n \"https://doi.org/10.1126/science.235.4793.1196\",\n \"https://doi.org/10.1103/revmodphys.70.1039\",\n \"https://doi.org/10.1103/physrevb.37.3759\"\n ]\n },\n {\n \"citation\": \"https://doi.org/10.1126/science.235.4793.1196\",\n \"count\": 3,\n \"doi\": [\n \"https://doi.org/10.1103/revmodphys.70.1039\",\n \"https://doi.org/10.1103/revmodphys.66.1125\",\n \"https://doi.org/10.1103/physrevb.37.3759\"\n ]\n },\n {\n \"citation\": \"https://doi.org/10.1103/physrevb.40.2254\",\n \"count\": 2,\n \"doi\": [\n \"https://doi.org/10.1021/ja800073m\",\n \"https://doi.org/10.1103/revmodphys.70.1039\"\n ]\n },\n {\n \"citation\": \"https://doi.org/10.1103/physrevb.50.6534\",\n \"count\": 2,\n \"doi\": [\n \"https://doi.org/10.1021/ja800073m\",\n \"https://doi.org/10.1103/revmodphys.70.1039\"\n ]\n },\n {\n \"citation\": \"https://doi.org/10.1038/372532a0\",\n \"count\": 2,\n \"doi\": [\n \"https://doi.org/10.1021/ja800073m\",\n \"https://doi.org/10.1103/revmodphys.70.1039\"\n ]\n },\n {\n \"citation\": \"https://doi.org/10.1126/science.235.4788.567\",\n \"count\": 2,\n \"doi\": [\n \"https://doi.org/10.1126/science.235.4793.1196\",\n \"https://doi.org/10.1103/physrevlett.58.908\"\n ]\n },\n {\n \"citation\": \"https://doi.org/10.1088/0370-1298/62/7/303\",\n \"count\": 2,\n \"doi\": [\n \"https://doi.org/10.1126/science.235.4793.1196\",\n \"https://doi.org/10.1103/revmodphys.70.1039\"\n ]\n },\n {\n \"citation\": \"https://doi.org/10.1103/physrevlett.58.408\",\n \"count\": 2,\n \"doi\": [\n \"https://doi.org/10.1126/science.235.4793.1196\",\n \"https://doi.org/10.1103/physrevlett.58.908\"\n ]\n },\n {\n \"citation\": \"https://doi.org/10.1103/physrevlett.58.405\",\n \"count\": 2,\n \"doi\": [\n \"https://doi.org/10.1126/science.235.4793.1196\",\n \"https://doi.org/10.1103/physrevlett.58.908\"\n ]\n }\n ]\n}]\n```",
"version": "2.0.0",
"termsOfService": "https://services.istex.fr/",
"contact": {
"name": "Inist-CNRS",
"url": "https://www.inist.fr/nous-contacter/"
}
},
"servers": [
{
"x-comment": "Will be automatically completed by the ezs server."
},
{
"url": "http://vptdmjobs.intra.inist.fr:49199/",
"description": "Latest version for production",
"x-profil": "Standard"
}
],
"tags": [
{
"name": "data-topcitation",
"description": "Référence phare d'un corpus",
"externalDocs": {
"description": "Plus de documentation",
"url": "https://github.com/inist-cnrs/web-services/tree/main/services/data-topcitation"
}
}
]
}