API-Überblick

Die KolleK-API ist eine JSON-API, die die Webanwendung eins zu eins spiegelt. Jede Fähigkeit der App (Sammlungen erstellen, Objekte und Exemplare hinzufügen, Transaktionen erfassen, Mitglieder verwalten) hat einen passenden Endpunkt, durchgesetzt von genau denselben Regeln. Wenn deine Rolle dir etwas im Browser erlaubt, erlaubt es dir dein Token auch über HTTP. Wenn nicht, verweigert die API es auf dieselbe Weise wie die App.

Diese Seite gibt dir das mentale Modell. Die vollständige, immer aktuelle Endpunktreferenz wird aus dem Code generiert und von deiner Instanz ausgeliefert:

• /docs/api für die durchsuchbare Referenz.
• /docs/api.md für die gesamte Referenz als Markdown.
• /docs/api/{section}.md für einen einzelnen Abschnitt als Markdown, praktisch, um ein Thema in ein Werkzeug einzuspeisen.

Auf dein Konto begrenzt

Die API ist mandantenbegrenzt. Ein Token gehört zu einem Benutzer, und ein Benutzer gehört zu genau einem Konto, also löst jede Anfrage über dieses Konto auf. Du kannst nicht auf die Daten eines anderen Kontos zugreifen, und du übergibst nirgendwo eine Konto-ID. Es gibt nichts zu konfigurieren: Authentifiziere dich, und du befindest dich in deinem eigenen Arbeitsbereich.

Dieselben Rollen gelten wie in der App. Das Token eines Betrachters kann lesen, aber nicht schreiben. Das Token eines Bearbeiters kann Katalog-Inhalte verwalten. Aktionen, die nur der Eigentümer ausführen darf (Mitglieder, Kontoeinstellungen), brauchen das Token eines Eigentümers.

Wie die Ressourcen aufgebaut sind

Ressourcen sind so verschachtelt, wie KolleK organisiert ist:

• Dein Konto enthält kontoweite Ressourcen: Mitglieder, Sammlungstypen, benutzerdefinierte Felder, Tags, Standorte, Zustände.
• Sammlungen enthalten Objekte, zusammen mit Kategorien und Sets.
• Objekte enthalten Fotos und Exemplare.
• Exemplare tragen die Verlaufsressourcen: Transaktionen, Wertermittlungen, Versicherungseinträge, Leihgaben, Wartungseinträge, Provenienz-Ereignisse, Standortverlauf, Dokumente und die kombinierte Zeitleiste.

Antworten folgen lose der JSON:API-Form: Jede Ressource kommt als type, id, attributes und links zurück. Listen sind mit einem Standard-Umschlag paginiert, behandelt in Ratenlimits und Konventionen.

Was dieser Abschnitt abdeckt

Diese Seiten behandeln den Einstieg und die Konzepte, die die generierte Referenz nicht vermitteln kann: Authentifizierung, Konventionen und den aktuellen Stand der Webhooks. Für einen bestimmten Endpunkt, seine Parameter und ausgearbeitete Anfrage- und Antwortbeispiele geh direkt zu /docs/api.

Wie es weitergeht

• Stelle deine erste Anfrage in Mit der API authentifizieren.
• Überflieg Ratenlimits und Konventionen, bevor du einen Client schreibst.
• Durchsuch die generierte Referenz unter /docs/api auf deiner Instanz.