API

ETSO propose une API publique pour consulter depuis d’autres projets les métadonnées des œuvres du catalogue. L’API permet de réutiliser les identifiants, les titres, les attributions, les liens et le résultat stylométrique de chaque œuvre.

Les informations sont fournies au format JSON et peuvent servir à intégrer les données d’ETSO dans des catalogues, visualisations, moteurs de recherche ou outils de recherche.

Endpoints

GET /api/obras

Renvoie le catalogue complet des œuvres avec leurs métadonnées publiques.

GET /api/obras/{id-o-slug}

Renvoie une seule œuvre à partir de son identifiant ou de son slug public.

Champs principaux

ChampDescription
idIdentifiant stable de l’œuvre.
slugIdentifiant lisible utilisé dans les URL publiques.
titleTitre tel qu’il figure dans la base de données, avec l’article final le cas échéant.
displayTitleTitre transformé selon le même procédé que celui utilisé sur le site ETSO.
titleVariantsAutres titres de l’œuvre tels qu’ils figurent dans la base de données.
displayTitleVariantsAutres titres transformés selon le même procédé que celui utilisé sur le site.
genreGenre de l’œuvre.
originProvenance ou source du texte utilisé par ETSO.
textStateÉtat du texte dans le catalogue.
addedOnDate d’incorporation au catalogue, lorsqu’elle est indiquée.
resultado1Résultat stylométrique de l’œuvre sous forme de phrase.
flagsIndicateurs booléens sur le rapport, le résumé, l’examen d’autorie et l’accès textuel.
traditionalAttributionTextAttribution traditionnelle prête à afficher.
traditionalAttributionPhrasePhrase d’attribution traditionnelle avec texte, Markdown, HTML et parties liables.
stylometryAttributionTextAttribution stylométrique prête à afficher.
traditionalAttributionAttribution traditionnelle normalisée.
stylometryAttributionAttribution stylométrique normalisée.
resourcesLiens publics associés dans ETSO.

Utilisation recommandée

Les réponses sont servies avec un cache public : public, max-age=3600, s-maxage=86400, stale-while-revalidate=604800. Pour les intégrations externes, il est recommandé de mettre la réponse en cache localement et de ne pas appeler l’API à chaque rendu.

Exemple

Requête pour une œuvre précise et réponse complète :

https://etso.es/api/obras/la-francesa-laura
{
  "meta": {
    "contentPolicy": {
      "includesFullText": false,
      "includesSummaries": false,
      "excludedFields": [
        "fullText",
        "text",
        "shortSummary",
        "summaryText",
        "resumen_breve",
        "resumen_largo"
      ]
    }
  },
  "work": {
    "id": "DESCONOCIDO_FrancesaLaura",
    "slug": "la-francesa-laura",
    "title": "Francesa Laura, La",
    "displayTitle": "La francesa Laura",
    "titleVariants": [],
    "displayTitleVariants": [],
    "genre": "Comedia",
    "origin": "El texto procede de la edición de Cuéllar y Vega.",
    "textState": "Bueno",
    "addedOn": "2021/03",
    "resultado1": "Los analisis de estilometria permiten asociar esta obra de forma clara con el perfil autorial de Lope de Vega Carpio.",
    "flags": {
      "inAuthorshipExam": true,
      "hasSummary": true,
      "hasReport": true,
      "hasTextAccess": true
    },
    "traditionalAttributionText": "Auteur inconnu",
    "traditionalAttributionPhrase": {
      "text": "Œuvre d’attribution inconnue.",
      "markdown": "Œuvre d’attribution [inconnue](https://etso.es/autores/desconocido).",
      "html": "Œuvre d’attribution <a href=\"/autores/desconocido\">inconnue</a>.",
      "parts": [
        {
          "kind": "text",
          "value": "Œuvre d’attribution "
        },
        {
          "kind": "author",
          "value": "inconnue",
          "authorId": "desconocido",
          "href": "/autores/desconocido",
          "url": "https://etso.es/autores/desconocido"
        },
        {
          "kind": "text",
          "value": "."
        }
      ]
    },
    "stylometryAttributionText": "Lope de Vega Carpio [Certaine]",
    "traditionalAttribution": {
      "groups": [
        {
          "members": [
            {
              "authorId": "desconocido",
              "authorName": "Auteur inconnu"
            }
          ]
        }
      ],
      "connector": "and",
      "rawExpression": "desconocido"
    },
    "stylometryAttribution": {
      "groups": [
        {
          "members": [
            {
              "authorId": "vega_carpio_lope_de",
              "authorName": "Lope de Vega Carpio",
              "confidence": "segura"
            }
          ]
        }
      ],
      "connector": "and",
      "rawExpression": "vega_carpio_lope_de[segura]"
    },
    "resources": {
      "work": "/obras/la-francesa-laura",
      "summary": "/obras/la-francesa-laura/resumen",
      "report": "/informes/analisis-estilometrico-la-francesa-laura",
      "textAccess": [
        {
          "label": "Texte BITESO",
          "href": "/biteso/francesa-laura-la",
          "kind": "biteso"
        }
      ]
    }
  }
}