{ "openapi": "3.1.0", "info": { "title": "Footnoted — Abfrage-API", "version": "v1", "description": "Lesende Abfragen über das Archiv Footnoted: Liste nach Filter, Umfeld eines Eintrags, Einträge zu einem Wikidata-Objekt. Ohne Schlüssel. Jede Antwort lässt sich auch aus den statischen Dateien herleiten (graph.json, entries.json je Bereich). Unbekannte Parameter werden mit 400 abgewiesen; erlaubt ist zusätzlich t, das nichts bedeutet und einen alten Abruf im Zwischenspeicher umgeht.", "license": { "name": "Creative Commons Namensnennung 4.0 International", "identifier": "CC-BY-4.0" } }, "servers": [ { "url": "https://footnoted.net/api/v1" } ], "paths": { "/": { "get": { "operationId": "uebersicht", "description": "Die Selbstbeschreibung: Abfragen, Parameter, Fehlercodes.", "responses": { "200": { "description": "Die Übersicht.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Uebersicht" } } } }, "405": { "description": "Methode außer GET, HEAD und OPTIONS (methode_unzulaessig).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Fehler" } } } }, "503": { "description": "Die Daten ließen sich nicht laden (daten_nicht_geladen). Retry-After sagt, wann ein neuer Versuch lohnt.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Fehler" } } }, "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Sekunden bis zum nächsten Versuch." } } } } } }, "/nachbarn": { "get": { "operationId": "nachbarn", "description": "Die Einträge im Umfeld eines Eintrags: über Querverweise in beide Richtungen, bis Tiefe 2, je mit der Begründung des Verweises. richtung ist „ausgehend“ (der nähere Eintrag verweist), „eingehend“ (der Nachbar verweist) oder „beide“; bei „beide“ steht die Begründung des Nachbarn in begruendungGegenrichtung. Dazu die Einträge mit demselben Wikidata-Gegenstand.", "parameters": [ { "name": "eintrag", "in": "query", "required": true, "description": "Pflicht. Adresse des Eintrags (/de/ai/eintrag/dartmouth-1956/), bereich/id (ai/dartmouth-1956) oder nur die Kennung (dartmouth-1956), wenn sie in einem einzigen Bereich vorkommt", "schema": { "type": "string", "minLength": 1 } }, { "name": "tiefe", "in": "query", "required": false, "description": "Optional, 1 oder 2, Standard 1", "schema": { "type": "integer", "enum": [ 1, 2 ], "default": 1 } }, { "name": "felder", "in": "query", "required": false, "description": "Optional, kommagetrennt: zusammenfassung, thema. Gibt je Eintrag die Zusammenfassung oder den Titel seines Themas mit; ohne Angabe nur die Grunddaten", "schema": { "type": "string", "pattern": "^(zusammenfassung|thema)(,(zusammenfassung|thema))*$" } }, { "name": "seite", "in": "query", "required": false, "description": "Optional, ab 1", "schema": { "type": "integer", "minimum": 1, "default": 1 } }, { "name": "proSeite", "in": "query", "required": false, "description": "Optional, höchstens 100, Standard 50", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } } ], "responses": { "200": { "description": "Die Antwort, vorn mit lizenz und stand.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Nachbarn" } } } }, "400": { "description": "Ein Parameter fehlt, ist unbekannt oder hat einen Wert, den die Abfrage nicht annimmt.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Fehler" } } } }, "404": { "description": "Der Eintrag oder die Abfrage ist unbekannt, oder die API ist nicht freigeschaltet (api_aus).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Fehler" } } } }, "405": { "description": "Methode außer GET, HEAD und OPTIONS (methode_unzulaessig).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Fehler" } } } }, "503": { "description": "Die Daten ließen sich nicht laden (daten_nicht_geladen). Retry-After sagt, wann ein neuer Versuch lohnt.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Fehler" } } }, "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Sekunden bis zum nächsten Versuch." } } } } } }, "/wikidata": { "get": { "operationId": "wikidata", "description": "Alle Einträge, die ein Wikidata-Objekt als ihren Gegenstand nennen. Eine leere Liste heißt: Kein Eintrag ist diesem Objekt zugeordnet — nicht, dass es keinen Eintrag zum Thema gibt.", "parameters": [ { "name": "id", "in": "query", "required": true, "description": "Pflicht. Wikidata-Kennung, etwa Q2453355", "schema": { "type": "string", "pattern": "^Q[1-9][0-9]*$" } }, { "name": "felder", "in": "query", "required": false, "description": "Optional, kommagetrennt: zusammenfassung, thema. Gibt je Eintrag die Zusammenfassung oder den Titel seines Themas mit; ohne Angabe nur die Grunddaten", "schema": { "type": "string", "pattern": "^(zusammenfassung|thema)(,(zusammenfassung|thema))*$" } }, { "name": "seite", "in": "query", "required": false, "description": "Optional, ab 1", "schema": { "type": "integer", "minimum": 1, "default": 1 } }, { "name": "proSeite", "in": "query", "required": false, "description": "Optional, höchstens 100, Standard 50", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } } ], "responses": { "200": { "description": "Die Antwort, vorn mit lizenz und stand.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Wikidata" } } } }, "400": { "description": "Ein Parameter fehlt, ist unbekannt oder hat einen Wert, den die Abfrage nicht annimmt.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Fehler" } } } }, "404": { "description": "Der Eintrag oder die Abfrage ist unbekannt, oder die API ist nicht freigeschaltet (api_aus).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Fehler" } } } }, "405": { "description": "Methode außer GET, HEAD und OPTIONS (methode_unzulaessig).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Fehler" } } } }, "503": { "description": "Die Daten ließen sich nicht laden (daten_nicht_geladen). Retry-After sagt, wann ein neuer Versuch lohnt.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Fehler" } } }, "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Sekunden bis zum nächsten Versuch." } } } } } }, "/liste": { "get": { "operationId": "liste", "description": "Alle Einträge, die den Filter erfüllen, vollständig und ohne Rangfolge, nach Datum sortiert. „enthaelt“ sucht in Titel, Zusammenfassung und den Wikidata-Namen der Gegenstände, ohne Rücksicht auf Groß- und Kleinschreibung und Akzente (Szilard findet Szilárd, Reissverschluss findet Reißverschluss); mehrere Wörter müssen alle vorkommen, in beliebiger Reihenfolge, und gängige Endungen zählen nicht (Lettern findet Letter, Impfungen findet Impfung), Wörter unter drei Buchstaben nur als ganzes Wort (KI findet nicht Kirche). Tippfehler verzeiht es nicht. Eine leere Liste heißt: Kein Eintrag führt diese Wörter in Titel, Zusammenfassung oder Gegenstand — nicht, dass es keinen Eintrag zum Thema gibt. Das zeigt erst die Suche nach weiteren Namen, Orten oder Begriffen.", "parameters": [ { "name": "enthaelt", "in": "query", "required": false, "description": "Optional, höchstens 100 Zeichen", "schema": { "type": "string", "maxLength": 100 } }, { "name": "von", "in": "query", "required": false, "description": "Optional, frühestes Jahr, eingeschlossen; vor Christus negativ (447 v. Chr. ist -447), ein Jahr 0 gibt es nicht", "schema": { "type": "integer", "not": { "const": 0 } } }, { "name": "bis", "in": "query", "required": false, "description": "Optional, spätestes Jahr, eingeschlossen; vor Christus negativ (447 v. Chr. ist -447), ein Jahr 0 gibt es nicht. Liegt es vor von, ist das ein Fehler, keine leere Liste", "schema": { "type": "integer", "not": { "const": 0 } } }, { "name": "bereich", "in": "query", "required": false, "description": "Optional, Name oder Kennung eines Bereichs", "schema": { "type": "string" } }, { "name": "zeitalter", "in": "query", "required": false, "description": "Optional, eine der Kennungen urgeschichte, altertum, mittelalter, fruehe-neuzeit, neueste-geschichte, neuzeit, zeitgeschichte. Nach europäischer Epocheneinteilung, aus dem Datum berechnet: ein Zeitband, keine Aussage, dass der Gegenstand zur europäischen Geschichte gehört. /de/zeitalter.json führt dazu Antike und Alter Orient; die sind Raumbegriffe, werden nicht nach Datum zugeordnet und gehen hier nicht", "schema": { "type": "string", "enum": [ "urgeschichte", "altertum", "mittelalter", "fruehe-neuzeit", "neueste-geschichte", "neuzeit", "zeitgeschichte" ] } }, { "name": "felder", "in": "query", "required": false, "description": "Optional, kommagetrennt: zusammenfassung, thema. Gibt je Eintrag die Zusammenfassung oder den Titel seines Themas mit; ohne Angabe nur die Grunddaten", "schema": { "type": "string", "pattern": "^(zusammenfassung|thema)(,(zusammenfassung|thema))*$" } }, { "name": "seite", "in": "query", "required": false, "description": "Optional, ab 1", "schema": { "type": "integer", "minimum": 1, "default": 1 } }, { "name": "proSeite", "in": "query", "required": false, "description": "Optional, höchstens 100, Standard 50", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } } ], "responses": { "200": { "description": "Die Antwort, vorn mit lizenz und stand.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Liste" } } } }, "400": { "description": "Ein Parameter fehlt, ist unbekannt oder hat einen Wert, den die Abfrage nicht annimmt.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Fehler" } } } }, "404": { "description": "Der Eintrag oder die Abfrage ist unbekannt, oder die API ist nicht freigeschaltet (api_aus).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Fehler" } } } }, "405": { "description": "Methode außer GET, HEAD und OPTIONS (methode_unzulaessig).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Fehler" } } } }, "503": { "description": "Die Daten ließen sich nicht laden (daten_nicht_geladen). Retry-After sagt, wann ein neuer Versuch lohnt.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Fehler" } } }, "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Sekunden bis zum nächsten Versuch." } } } } } } }, "components": { "schemas": { "Lizenz": { "type": "object", "description": "Lizenz, Bedingung und eine fertige Quellenangabe für diese Auswahl.", "required": [ "bedingung", "zitiervorlage", "license", "creditText", "usageInfo" ], "properties": { "bedingung": { "type": "string", "description": "Was die Lizenz verlangt, in einem Satz." }, "zitiervorlage": { "type": "string", "description": "Die Quellenangabe, die bei einer Übernahme dazugehört." }, "license": { "type": "string", "format": "uri" }, "creditText": { "type": "string" }, "usageInfo": { "type": "string", "format": "uri" } } }, "Kopf": { "type": "object", "required": [ "lizenz", "stand" ], "properties": { "lizenz": { "$ref": "#/components/schemas/Lizenz" }, "stand": { "type": [ "string", "null" ], "description": "Der Commit, aus dem die Daten gebaut sind." } } }, "Seiten": { "type": "object", "required": [ "gesamt", "seite", "seiten", "proSeite" ], "properties": { "gesamt": { "type": "integer", "description": "Treffer insgesamt, über alle Seiten." }, "seite": { "type": "integer" }, "seiten": { "type": "integer", "description": "Zahl der Seiten, mindestens 1. Hinter der letzten kommt eine leere Seite." }, "proSeite": { "type": "integer" } } }, "Eintrag": { "type": "object", "required": [ "id", "titel", "datum", "jahr", "bereich", "belegstufe", "belegstufeCode", "adresse" ], "properties": { "id": { "type": "string" }, "titel": { "type": "string" }, "datum": { "type": [ "string", "null" ], "description": "ISO 8601, astronomisch gezählt: 447 v. Chr. ist -0446." }, "jahr": { "type": [ "string", "null" ], "description": "Das Jahr in Worten, etwa „447 v. Chr.“." }, "bereich": { "type": "string", "description": "Der Name des Bereichs." }, "belegstufe": { "type": "string" }, "belegstufeCode": { "type": [ "string", "null" ] }, "adresse": { "type": "string", "format": "uri" } } }, "ListenEintrag": { "allOf": [ { "$ref": "#/components/schemas/Eintrag" }, { "type": "object", "properties": { "zeitalter": { "type": "array", "items": { "type": "string" } }, "zusammenfassung": { "type": "string", "description": "Nur mit enthaelt." }, "gegenstand": { "type": "array", "items": { "type": "string" }, "description": "Nur mit enthaelt: die Wikidata-Namen, in denen das Wort steht, wenn es nur dort steht." } } } ] }, "Nachbar": { "allOf": [ { "$ref": "#/components/schemas/Eintrag" }, { "type": "object", "required": [ "abstand", "richtung", "begruendung", "ueber" ], "properties": { "abstand": { "type": "integer", "minimum": 1 }, "richtung": { "type": "string", "enum": [ "ausgehend", "eingehend", "beide" ] }, "begruendung": { "type": "string" }, "begruendungGegenrichtung": { "type": "string", "description": "Nur bei „beide“: die Begründung des Nachbarn." }, "ueber": { "type": [ "string", "null" ], "description": "Bei Tiefe 2: bereich/id des Eintrags dazwischen." } } } ] }, "Liste": { "allOf": [ { "$ref": "#/components/schemas/Kopf" }, { "$ref": "#/components/schemas/Seiten" }, { "type": "object", "required": [ "durchsucht", "filter", "eintraege" ], "properties": { "durchsucht": { "type": "object", "required": [ "bereiche", "eintraege" ], "properties": { "bereiche": { "type": "integer" }, "eintraege": { "type": "integer" } } }, "filter": { "type": "object", "required": [ "enthaelt", "von", "bis" ], "properties": { "enthaelt": { "type": [ "string", "null" ] }, "von": { "type": [ "integer", "null" ] }, "bis": { "type": [ "integer", "null" ] }, "zeitalter": { "type": "string" } } }, "eintraege": { "type": "array", "items": { "$ref": "#/components/schemas/ListenEintrag" } } } } ] }, "Nachbarn": { "allOf": [ { "$ref": "#/components/schemas/Kopf" }, { "$ref": "#/components/schemas/Seiten" }, { "type": "object", "required": [ "eintrag", "tiefe", "gegenstand", "nachbarn", "gleicherGegenstand" ], "properties": { "eintrag": { "$ref": "#/components/schemas/Eintrag" }, "tiefe": { "type": "integer" }, "gegenstand": { "type": "array", "items": { "type": "object", "required": [ "id", "name" ], "properties": { "id": { "type": "string" }, "name": { "type": [ "string", "null" ] } } } }, "nachbarn": { "type": "array", "items": { "$ref": "#/components/schemas/Nachbar" } }, "gleicherGegenstand": { "type": "array", "items": { "$ref": "#/components/schemas/Eintrag" }, "description": "Einträge mit demselben Wikidata-Gegenstand, ohne Verweis." } } } ] }, "Wikidata": { "allOf": [ { "$ref": "#/components/schemas/Kopf" }, { "$ref": "#/components/schemas/Seiten" }, { "type": "object", "required": [ "wikidata", "eintraege" ], "properties": { "wikidata": { "type": "object", "required": [ "id", "name", "adresse" ], "properties": { "id": { "type": "string" }, "name": { "type": [ "string", "null" ] }, "adresse": { "type": "string", "format": "uri" } } }, "eintraege": { "type": "array", "items": { "$ref": "#/components/schemas/Eintrag" } }, "hinweis": { "type": "string", "description": "Nur bei leerer Liste: was sie heißt." } } } ] }, "Uebersicht": { "allOf": [ { "$ref": "#/components/schemas/Kopf" }, { "type": "object", "required": [ "version", "abfragen", "fehlercodes", "openapi" ], "properties": { "version": { "type": "string" }, "hinweis": { "type": "string" }, "abfragen": { "type": "object", "additionalProperties": { "type": "object" } }, "fehlercodes": { "type": "object", "additionalProperties": { "type": "string" } }, "openapi": { "type": "string" } } } ] }, "Fehler": { "type": "object", "required": [ "lizenz", "stand", "code", "fehler" ], "properties": { "lizenz": { "$ref": "#/components/schemas/Lizenz" }, "code": { "type": "string", "enum": [ "abfrage_unbekannt", "parameter_fehlt", "parameter_ungueltig", "eintrag_unbekannt", "eintrag_mehrdeutig", "bereich_unbekannt", "zeitalter_unbekannt", "methode_unzulaessig", "api_aus", "daten_nicht_geladen" ], "description": "abfrage_unbekannt: Diese Abfrage gibt es nicht; die Übersicht unter /api/v1/ nennt alle. parameter_fehlt: Ein Pflichtparameter fehlt. parameter_ungueltig: Ein Parameter hat eine Form oder einen Wert, den die Abfrage nicht annimmt. eintrag_unbekannt: Diesen Eintrag gibt es nicht. Nach Stichwort sucht liste?enthaelt=. eintrag_mehrdeutig: Die Kennung gibt es in mehreren Bereichen; sie braucht den Bereich davor. bereich_unbekannt: Diesen Bereich gibt es nicht. zeitalter_unbekannt: Dieses Zeitalter gibt es nicht. methode_unzulaessig: Nur GET und HEAD; die API schreibt nichts. api_aus: Die Abfrage-API ist nicht freigeschaltet. daten_nicht_geladen: Die Daten der Auslieferung ließen sich nicht laden; ein neuer Versuch kann helfen." }, "fehler": { "type": "string" }, "stand": { "type": [ "string", "null" ], "description": "Der Commit; null, wenn der Fehler vor dem Laden der Daten auftrat (405, 503, api_aus)." } } } } } }