Die API-Dokumentation findest du unter Einstellungen → Öffentliche API. Dafür brauchst du Administrationsrechte.
Eine API ist eine Schnittstelle, über die Programme Daten abrufen können. Bei dieser öffentlichen Schnittstelle geht es um Tiere, die euer Verein für die Veröffentlichung freigegeben hat. Eure Website kann diese Daten verwenden, ohne dass ihr jede Tierbeschreibung dort noch einmal von Hand pflegen müsst.
„Die Person, die unsere Website betreut, fragt nach der Dokumentation“
Öffne Einstellungen → Öffentliche API. Oben im Abschnitt Öffentliche URLs stehen die drei Adressen Tierliste, Tier-Detail und Tierbild. Das Vereins-Kürzel ist dort bereits eingesetzt.
Weiter unten, nach Einstellungen und Sichtbare Felder, findest du API-Dokumentation. Dort stehen Erklärungen und Beispiele zu den Adressen.
Gib der Person, die die Einbindung auf eurer Website umsetzt, diese Adressen zusammen mit den Beispiel-Zeilen weiter. Sie kann damit prüfen, wie eure Website die freigegebenen Daten abrufen und anzeigen soll. Dafür braucht sie weder dein Passwort noch einen persönlichen Zugang zu den internen Vereinsdaten.
„Muss man sich für den Abruf anmelden?“
Nein. Die öffentliche Tierliste ist bewusst ohne Anmeldung abrufbar. Deshalb ist wichtig, vorher die Freigaben zu prüfen.
Unter Sichtbare Felder entscheidest du, welche Angaben nach außen gegeben werden. Am Tier selbst legt Veröffentlicht fest, ob es grundsätzlich öffentlich erscheinen soll. Weitere Ausschlussregeln gelten etwa für verstorbene, deaktivierte oder bereits endgültig vermittelte Tiere.
Prüfe auch die Freigaben für Bilder und mögliche personenbezogene Angaben. Dass eine Adresse öffentlich ist, heißt nicht, dass beliebige interne Daten dort veröffentlicht werden sollten. Mehr dazu: Kann ich Inhalte öffentlich teilen?.
„Wie sehe ich, ob Daten ankommen?“
Nutze bei Tierliste den Button In neuem Tab öffnen. Statt einer fertig gestalteten Tierübersicht siehst du Text mit Klammern, Anführungszeichen und Feldnamen. Dieses Datenformat heißt JSON. Für den Datenaustausch ist diese Darstellung normal.
Siehst du die freigegebenen Tiere, funktioniert der grundsätzliche Abruf. Ob eure Website sie richtig darstellt, muss dort gesondert geprüft werden.
Tier-Detail und Tierbild enthalten noch Platzhalter in geschweiften Klammern. Diese müssen für ein bestimmtes Tier beziehungsweise Bild ersetzt werden. Für einen ersten Test ist deshalb die Tierliste am einfachsten.
„Es erscheint nur eine leere Liste“
Eine leere Liste bedeutet, dass die Adresse antwortet, aber gerade keine passenden Tiere liefert. Prüfe bei einem vorgesehenen Tier Veröffentlicht und die sonstigen Veröffentlichungsregeln.
Verwende die kopierte Adresse aus Öffentliche URLs, statt eine Adresse selbst zusammenzusetzen. Prüfe außerdem, ob du die Einstellungen des richtigen Vereins geöffnet hast.
„Wie kommen die Tiere nun auf unsere Website?“
Die Schnittstelle liefert die Daten, aber noch keine fertig gestaltete Website-Ansicht. Die Einbindung erfolgt in eurer Website.
Gib die Angaben an die Person oder Agentur weiter, die eure Website technisch betreut. Welche Umsetzung möglich ist, hängt von eurem Website-System ab. Das bloße Kopieren der Datenadresse in einen normalen Textblock erzeugt nicht automatisch eine Tiergalerie.
„Kann ein anderes Programm auch Daten nach Sheltra schreiben?“
Die öffentliche Schnittstelle dient ausschließlich zum Lesen veröffentlichter Tierdaten. Damit können keine Tiere, Personen oder anderen internen Daten angelegt oder geändert werden.
Für einen Datenumzug nutze die vorgesehenen Importfunktionen. Den Unterschied erklärt Gibt es eine API?.
„Der Bereich Öffentliche API fehlt bei mir“
Bitte eine Person mit Administrationsrechten, dir die benötigten öffentlichen Adressen und Beispiele zu geben. Dafür muss sie dir nicht ihren Zugang überlassen oder deine Rechte unnötig erweitern.
Technischer Hinweis für eure Website-Betreuung
Die Dokumentation in der Anwendung nennt Pfad, Zweck, Antwortformat und ein curl-Beispiel. Die Tierliste liefert ein JSON-Array mit freigegebenen Feldern. Der Detailabruf ergänzt images; der Bildabruf liefert die Bilddatei mit passendem Content-Type.
Auf dem API-Host liegen außerdem /docs, /openapi.json und /openapi.yaml. Diese technische Gesamtreferenz beschreibt auch interne, anmeldepflichtige Funktionen. Sie ist keine Freigabe, diese als allgemeine externe Schreibschnittstelle zu verwenden.
Erscheint beim Test eine Fehlermeldung, hilft Warum erhalte ich eine Fehlermeldung?.
