Dokumentation
Anleitung

Einstieg in die ARIX-Schnittstelle

Zugang vorbereiten, erste XML-Anfrage senden und die passende Anleitung für Suche, Medienlinks und Lizenzverwaltung finden.

Auf dieser Seite

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

  1. Mit search ein Medium finden und seinen Identifier übernehmen.
  2. Bei Bedarf mit record zusätzliche Metadaten abrufen.
  3. Für den berechtigten Nutzerkontext einen notch vom Typ link anfordern.
  4. Aus Nonce und Anwendungssecret die Passphrase berechnen.
  5. Mit link die 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.