API

توفّر ETSO واجهة API عامة للاستعلام من مشاريع أخرى عن البيانات الوصفية لأعمال الفهرس. صُممت الواجهة لإعادة استخدام المعرّفات والعناوين والإسنادات والروابط ونتيجة القياس الأسلوبي لكل عمل.

تُقدَّم المعلومات بصيغة JSON ويمكن استخدامها لدمج بيانات ETSO في الفهارس أو التصورات البيانية أو محركات البحث أو أدوات البحث.

نقاط الوصول

GET /api/obras

تعيد فهرس الأعمال الكامل مع بياناته الوصفية العامة.

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

تعيد عملًا واحدًا باستخدام معرّفه أو slug العام الخاص به.

الحقول الرئيسية

الحقل	الوصف
`id`	معرّف ثابت للعمل.
`slug`	معرّف مقروء يُستخدم في عناوين URL العامة.
`title`	العنوان كما يظهر في قاعدة البيانات، بما في ذلك أداة التعريف النهائية عند وجودها.
`displayTitle`	العنوان بعد تحويله بالعملية نفسها التي يستخدمها موقع ETSO.
`titleVariants`	عناوين أخرى للعمل كما تظهر في قاعدة البيانات.
`displayTitleVariants`	عناوين أخرى بعد تحويلها بالعملية نفسها التي يستخدمها الموقع.
`genre`	نوع العمل الأدبي.
`origin`	مصدر النص أو منشؤه كما تستخدمه ETSO.
`textState`	حالة النص داخل الفهرس.
`addedOn`	تاريخ إدراج العمل في الفهرس، عند توفره.
`resultado1`	نتيجة القياس الأسلوبي للعمل في صيغة جملة.
`flags`	مؤشرات منطقية حول التقرير والملخص وفحص الإسناد والوصول إلى النص.
`traditionalAttributionText`	الإسناد التقليدي جاهزًا للعرض.
`traditionalAttributionPhrase`	جملة الإسناد التقليدي مع نص وMarkdown وHTML وأجزاء قابلة للربط.
`stylometryAttributionText`	الإسناد الأسلوبي جاهزًا للعرض.
`traditionalAttribution`	الإسناد التقليدي بصيغة موحدة.
`stylometryAttribution`	الإسناد الأسلوبي بصيغة موحدة.
`resources`	روابط عامة مرتبطة داخل ETSO.

الاستخدام الموصى به

تُقدَّم الاستجابات مع ذاكرة تخزين مؤقت عامة: public, max-age=3600, s-maxage=86400, stale-while-revalidate=604800. في عمليات الدمج الخارجية، يُنصح بتخزين الاستجابة محليًا وعدم استدعاء API في كل عملية عرض.

مثال

استعلام عن عمل محدد والاستجابة الكاملة:

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": "مؤلف مجهول",
    "traditionalAttributionPhrase": {
      "text": "عمل ذو إسناد مجهول.",
      "markdown": "عمل ذو إسناد [مجهول](https://etso.es/autores/desconocido).",
      "html": "عمل ذو إسناد <a href=\"/autores/desconocido\">مجهول</a>.",
      "parts": [
        {
          "kind": "text",
          "value": "عمل ذو إسناد "
        },
        {
          "kind": "author",
          "value": "مجهول",
          "authorId": "desconocido",
          "href": "/autores/desconocido",
          "url": "https://etso.es/autores/desconocido"
        },
        {
          "kind": "text",
          "value": "."
        }
      ]
    },
    "stylometryAttributionText": "Lope de Vega Carpio [مؤكد]",
    "traditionalAttribution": {
      "groups": [
        {
          "members": [
            {
              "authorId": "desconocido",
              "authorName": "مؤلف مجهول"
            }
          ]
        }
      ],
      "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": "النص BITESO",
          "href": "/biteso/francesa-laura-la",
          "kind": "biteso"
        }
      ]
    }
  }
}