APIs, Endpunkte und URL-Schema

Im Dialog AssetFeed anpassen legst du fest, unter welchen Adressen dein Feed antwortet und was er dort ausliefert. Die Konfiguration ist dreistufig aufgebaut:

AssetFeed (Titel, Feed-URL)
└── API (Gültigkeit der Asset-URLs)
    ├── Listen-Endpunkt      → JSON mit allen veröffentlichten Assets
    └── Einzel-Asset-Endpunkt → ein Bild, ein Download oder Metadaten als JSON

Alle Endpunkte liegen unterhalb der Feed-URL. Bei https://share.vaulo.com/mustermann/presse als Feed-URL antwortet ein Endpunkt mit dem URL-Schema assets/{filename} also unter https://share.vaulo.com/mustermann/presse/assets/sommerfest.jpg.

APIs

Eine API bündelt die Endpunkte für ein konsumierendes System. In den meisten Fällen reicht die eine API, die jeder neue Feed mitbringt. Mit Weitere API hinzufügen legst du eine zweite an, wenn ein weiteres System andere Anforderungen hat – etwa eine kürzere Gültigkeit der Bild-URLs. Sobald es zwei APIs gibt, erscheint das Feld API-Name (optional), damit du sie auseinanderhalten kannst. Eine neue API startet ohne Endpunkte.

Gültigkeit der Asset-URLs

Die url-Werte, die der Feed im JSON ausgibt, sind signierte Direktlinks auf die Bilddateien. Unter Gültigkeit der Asset-URLs legst du pro API fest, wie lange sie funktionieren: Standard (4 Tage), 15 Minuten, 1 Stunde, 6 Stunden, 1 Tag, 4 Tage oder Benutzerdefiniert mit eigener Dauer und Einheit. Zulässig sind 5 Minuten bis 4 Tage. Dieselbe Gültigkeit gilt für die Weiterleitung eines Einzel-Asset-Endpunkts im Modus inline.

Endpunkte

Jeder Endpunkt hat einen Endpunkt-Typ, ein URL-Schema und – je nach Typ – einen Antwortmodus und ein JSON-Template. Ein Endpunkt in der Liste ist sofort nach dem Speichern aktiv. Einen Schalter zum Deaktivieren gibt es nicht: Entferne den Endpunkt über das Papierkorb-Symbol, wenn er nicht mehr antworten soll.

Listen-Endpunkt

Ein Listen-Endpunkt liefert das JSON-Template über alle veröffentlichten Dateien des Feeds, immer seitenweise (siehe unten).

• URL-Schema (leer = Feed-URL): Bleibt das Feld leer, antwortet der Endpunkt direkt auf der Feed-URL. Pro Feed kann nur ein Endpunkt die leere Feed-URL belegen. Alternativ gibst du einen Pfad an, zum Beispiel katalog/liste.
• {size}, {width} und {height} sind im Schema erlaubt. {fileId}, {assetId} und {filename} gehören zu Einzel-Asset-Endpunkten.
• Das JSON-Template bestimmt die Antwort. Wie du es schreibst, steht unter JSON-Template mit Liquid-Syntax.

Einzel-Asset-Endpunkt

Ein Einzel-Asset-Endpunkt adressiert eine Datei. Welche, ergibt sich aus den Platzhaltern im URL-Schema für Assets:

Mindestens ein identifizierender Platzhalter ist Pflicht: {fileId}, {assetId}, {filename} oder {tenantProps.…}. Statische Pfadteile und Query-Parameter sind erlaubt. Die Schreibweise aus dem Template funktioniert ebenfalls: {asset.assetId}, {asset.filename} oder {asset.id} bedeuten dasselbe wie {assetId}, {filename} und {fileId}. Unter dem Feld siehst du unter Beispiel: live, wie eine fertige URL aussieht.

Unter Antwort wählst du, was der Endpunkt liefert:

• Im Browser anzeigen (inline) – eine Weiterleitung auf das Bild in der angeforderten Größe. Der richtige Modus für <img src="…"> auf einer Website.
• Download erzwingen (attachment) – die Datei wird als Download ausgeliefert. Bilder in der angeforderten Größe, Videos und andere Formate als Originaldatei.
• Metadaten als JSON (inkl. Download-URL) – ein JSON-Dokument aus dem JSON-Template dieses Endpunkts mit den Daten der Datei unter asset, inklusive ihrer temporären url.

Welcher Endpunkt antwortet?

Eine Anfrage wird gegen alle Endpunkte aller APIs des Feeds geprüft. Passen mehrere Schemata, gewinnt das spezifischste: zuerst das Schema mit den meisten festen Pfadteilen, dann das mit den wenigsten Platzhaltern, bei Gleichstand die Reihenfolge in der Konfiguration. Die leere Feed-URL geht immer an den Listen-Endpunkt ohne Schema. Passt kein Endpunkt, antwortet der Feed mit 404.

Reservierte Query-Parameter

Diese Parameter versteht jeder Listen-Endpunkt. Dein URL-Schema darf sie nicht selbst als Query-Parameter belegen.

size und fallback gelten auch für Einzel-Asset-Endpunkte, sofern das Schema die Größe nicht bereits über {size} festlegt.

https://share.vaulo.com/mustermann/presse?page=2&pageSize=50
https://share.vaulo.com/mustermann/presse?ids=3f2ab81c-5c1e-4f6a-9d15-0c9be31e4b7a,9c1d2e3f-…
https://share.vaulo.com/mustermann/presse?id=000123&id=000124
https://share.vaulo.com/mustermann/presse?tenantProps.kategorie=Rot&tenantProps.kategorie=Blau&tenantProps.saison=Sommer
https://share.vaulo.com/mustermann/presse?size=800
https://share.vaulo.com/mustermann/presse/assets/sommerfest.jpg?size=sm&fallback=true

Bildgrößen

Exakte Bildgrößen mit Breite und Höhe

Mit den Platzhaltern {width} und {height} liefert ein Endpunkt das Bild exakt in der angeforderten Größe – gerendert aus der Originaldatei, nie vergrößert. Beide Platzhalter dürfen mit festem Text in einem Segment stehen, sodass sich auch fremde URL-Schemata nachbilden lassen. Statt der Platzhalter funktionieren auch die Query-Parameter width und height.

• Nur Breite oder nur Höhe: Das Bild wird auf diese Kante skaliert, das Seitenverhältnis bleibt erhalten.
• Breite und Höhe: Der Zuschnitt bei Breite × Höhe des Endpunkts entscheidet. Box füllen und mittig zuschneiden (cover) skaliert, bis die Box gefüllt ist, und schneidet den Überstand mittig ab – das Bild hat danach genau die angeforderten Maße. In die Box einpassen, ohne Zuschnitt (contain) skaliert, bis das ganze Bild in die Box passt.
• Kein Vergrößern: Ist das Original kleiner als angefordert, kommt es in seiner eigenen Größe zurück.
• Erlaubte Größen: Weil der Feed öffentlich ist, kannst du pro Endpunkt festlegen, welche Größen angefragt werden dürfen – als 800 (Breite), 292x219 (Box) oder x219 (Höhe). Ist die Liste gefüllt, antworten alle anderen Größen mit 404. Bleibt sie leer, ist jede Größe bis 8192 px pro Kante erlaubt.

Seitenweise Abfrage

Ein Listen-Endpunkt ist immer paginiert. Ohne pageSize bekommt das externe System 100 Assets pro Seite. Damit es die weiteren Seiten findet, stellt das Template das Objekt page bereit – mit page.nextUrl, das auf die nächste Seite zeigt, und null, wenn es keine mehr gibt. Wie du diese Werte ins JSON schreibst, zeigt das Standard-Template.

Statuscodes