ARIX ist eine Schnittstelle zum Suchen und Abrufen von Bildungsmedien. Anwendungen senden XML-Befehle als HTTPS-Formularrequest. Je nach freigeschaltetem Zugang lassen sich außerdem Medienlinks anfordern, Metadaten exportieren und Lizenzen verwalten.
Diese Dokumentation richtet sich an Entwickler einer serverseitigen Integration. Sie beschreibt das Basisprotokoll und die Besonderheiten der einzelnen Befehle. Ein eingerichteter Zugang ist Voraussetzung; die Beispiele verwenden erfundene Kennungen und ersetzen keinen Testzugang.
Vor dem ersten Aufruf
Stimmen Sie mit uns die HTTPS-Adresse, den Kontext, die benötigten Befehle und die freizuschaltenden ausgehenden IP-Adressen ab. Für geschützte Aufrufe benötigen Sie zusätzlich ein Anwendungssecret. Ein Secret darf nur Ihr Backend verwenden.
Die übliche Adresse lautet:
https://arix.datenbank-bildungsmedien.net/KONTEXT
Ersetzen Sie KONTEXT durch die zugewiesene Zeichenfolge. Ein Kontext bestimmt den Lizenz- und Datenbereich; er allein berechtigt noch nicht zum Zugriff. Details: Kontext und Zugangsberechtigungen verwenden
Einen Suchrequest senden
Voraussetzung ist die Freigabe search. Speichern Sie beispielsweise folgendes XML als request.xml:
<search fields="titel,text,typ" limit="0,10">
<condition field="text_fields" operator="AND">Wasser Kreislauf</condition>
</search>
Senden Sie die Datei als Formularfeld xmlstatement:
ARIX_URL='https://arix.datenbank-bildungsmedien.net/XX/BEISPIEL'
curl --silent --show-error --connect-timeout 10 --max-time 30 \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'xmlstatement@request.xml' \
"$ARIX_URL"
XX/BEISPIEL muss vor dem Ausführen ersetzt werden. --data-urlencode bewirkt einen POST und schützt die Formularkodierung. Ein roher XML-Body mit Content-Type: application/xml ist nicht dasselbe Requestformat.
Eine mögliche Antwort mit einem erfundenen Medium:
<result>
<r identifier="anbieter-12345">
<f n="titel">Der Wasserkreislauf</f>
<f n="text">Verdunstung und Niederschlag.</f>
<f n="typ">55</f>
</r>
</result>
Bei einem eingerichteten Zugang kann die Suche auch korrekt leer bleiben. Prüfen Sie HTTP-Status und Antwortinhalt. ARIX kann einen Fehler als <error>…</error> liefern, obwohl der HTTP-Status 200 lautet.
Dokumentation nach Aufgabe
| Aufgabe | Artikel |
|---|---|
| Zugang und Kontext verstehen | Kontext und Zugangsberechtigungen verwenden |
| Suchbedingungen und Seitennavigation verwenden | Medien suchen und Ergebnisse seitenweise lesen |
| Einzelne Datensätze und Metadaten auswerten | Datensätze, Identifier und Metadaten auswerten |
| Authentifizieren, abspielen und herunterladen | Authentifizieren und Medienlinks anfordern |
| Größere Metadatenmengen abrufen | Metadaten mit Harvest abrufen |
| Taxonomien verwenden | Taxonomien und Wertezuordnungen verwenden |
| Vorschaubilder, Logos und Medienübersichten abrufen | Vorschaubilder, Logos und Playinfo abrufen |
| Freigegebene Lizenzeinträge verwalten | Lizenzen per API verwalten |
| Fehler und unerwartete Antworten behandeln | ARIX-Antworten und Fehler behandeln |
Typischer Medienablauf
- Mit
searchein Medium finden und seinen Identifier übernehmen. - Bei Bedarf mit
recordzusätzliche Metadaten abrufen. - Für den berechtigten Nutzerkontext einen
notchvom Typlinkanfordern. - Aus Nonce und Anwendungssecret die Passphrase berechnen.
- Mit
linkdie Abspiel- und gegebenenfalls Downloadadresse anfordern.
Ein Suchtreffer allein ist keine dauerhafte Abspielberechtigung. Medienlinks erst bei Bedarf erzeugen, vertraulich behandeln und nicht als feste Katalogadresse speichern.
Verfügbarkeit und Beispiele
Ersetzen Sie die Platzhalter in den Beispielen durch die Werte Ihres Zugangs. Für erste Aufrufe und insbesondere für Lizenzänderungen verwenden Sie einen mit uns vereinbarten Testkontext.
Nicht jeder Zugang unterstützt jeden beschriebenen Befehl. Gesonderte Integrationen, JSON-Zugänge und spezielle Sucherweiterungen benötigen eine eigene Vereinbarung. Die Artikel kennzeichnen Abweichungen von älteren ARIX-Beschreibungen, etwa bei Seitennavigation, Taxonomien und Datensatzantworten.