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

Champ	Description
`id`	Identifiant stable de l’œuvre.
`slug`	Identifiant lisible utilisé dans les URL publiques.
`title`	Titre tel qu’il figure dans la base de données, avec l’article final le cas échéant.
`displayTitle`	Titre transformé selon le même procédé que celui utilisé sur le site ETSO.
`titleVariants`	Autres titres de l’œuvre tels qu’ils figurent dans la base de données.
`displayTitleVariants`	Autres titres transformés selon le même procédé que celui utilisé sur le site.
`genre`	Genre de l’œuvre.
`origin`	Provenance ou source du texte utilisé par ETSO.
`textState`	État du texte dans le catalogue.
`addedOn`	Date d’incorporation au catalogue, lorsqu’elle est indiquée.
`resultado1`	Résultat stylométrique de l’œuvre sous forme de phrase.
`flags`	Indicateurs booléens sur le rapport, le résumé, l’examen d’autorie et l’accès textuel.
`traditionalAttributionText`	Attribution traditionnelle prête à afficher.
`traditionalAttributionPhrase`	Phrase d’attribution traditionnelle avec texte, Markdown, HTML et parties liables.
`stylometryAttributionText`	Attribution stylométrique prête à afficher.
`traditionalAttribution`	Attribution traditionnelle normalisée.
`stylometryAttribution`	Attribution stylométrique normalisée.
`resources`	Liens 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"
        }
      ]
    }
  }
}