APIs, Endpoints and URL Scheme

In the Customize AssetFeed dialog you define at which addresses your feed answers and what it delivers there. The configuration has three levels:

AssetFeed (title, feed URL)
└── API (validity of the asset URLs)
    ├── List endpoint          → JSON with all published assets
    └── Single asset endpoint  → one image, one download or metadata as JSON

All endpoints live below the feed URL. With https://share.vaulo.com/mustermann/press as the feed URL, an endpoint with the URL scheme assets/{filename} answers at https://share.vaulo.com/mustermann/press/assets/summer-party.jpg.

APIs

An API bundles the endpoints for one consuming system. In most cases the single API every new feed comes with is enough. Add another API creates a second one when another system has different requirements – a shorter validity of the image URLs, for instance. As soon as there are two APIs, the API name (optional) field appears so you can tell them apart. A new API starts without endpoints.

Validity of asset URLs

The url values the feed emits in the JSON are signed direct links to the image files. Under Validity of asset URLs you define per API how long they work: Default (4 days), 15 minutes, 1 hour, 6 hours, 1 day, 4 days or Custom with your own duration and unit. Allowed are 5 minutes to 4 days. The same validity applies to the redirect of a single asset endpoint in inline mode.

Endpoints

Every endpoint has an endpoint type, a URL scheme and – depending on the type – a response mode and a JSON template. An endpoint in the list is live as soon as you save. There is no switch to disable it: remove the endpoint with the trash icon when it should stop answering.

List endpoint

A list endpoint renders the JSON template over all published files of the feed, always page by page (see below).

• URL schema (empty = feed URL): Leave the field empty and the endpoint answers directly on the feed URL. Only one endpoint per feed can claim the empty feed URL. Alternatively enter a path, for example catalog/list.
• {size}, {width} and {height} are allowed in the scheme. {fileId}, {assetId} and {filename} belong to single asset endpoints.
• The JSON template defines the response. How to write it is explained under JSON template with Liquid syntax.

Single asset endpoint

A single asset endpoint addresses one file. Which one follows from the placeholders in the URL scheme for assets:

At least one identifying placeholder is required: {fileId}, {assetId}, {filename} or {tenantProps.…}. Static path segments and query parameters are allowed. The template spelling works as well: {asset.assetId}, {asset.filename} or {asset.id} mean the same as {assetId}, {filename} and {fileId}. Below the field, Example: shows live what a finished URL looks like.

Under Response you choose what the endpoint delivers:

• View in browser (inline) – a redirect to the image in the requested size. The right mode for <img src="…"> on a website.
• Force download (attachment) – the file is delivered as a download. Images in the requested size, videos and other formats as the original file.
• Metadata as JSON (incl. download URL) – a JSON document rendered from this endpoint's JSON template with the file's data under asset, including its temporary url.

Which endpoint answers?

A request is checked against all endpoints of all APIs of the feed. If several schemes match, the most specific one wins: first the scheme with the most static path segments, then the one with the fewest placeholders, and on a tie the order in the configuration. The empty feed URL always goes to the list endpoint without a scheme. If no endpoint matches, the feed answers with 404.

Reserved query parameters

Every list endpoint understands these parameters. Your URL scheme must not claim them as query parameters itself.

size and fallback also apply to single asset endpoints, unless the scheme already fixes the size through {size}.

https://share.vaulo.com/mustermann/press?page=2&pageSize=50
https://share.vaulo.com/mustermann/press?ids=3f2ab81c-5c1e-4f6a-9d15-0c9be31e4b7a,9c1d2e3f-…
https://share.vaulo.com/mustermann/press?id=000123&id=000124
https://share.vaulo.com/mustermann/press?tenantProps.category=Red&tenantProps.category=Blue&tenantProps.season=Summer
https://share.vaulo.com/mustermann/press?size=800
https://share.vaulo.com/mustermann/press/assets/summer-party.jpg?size=sm&fallback=true

Image sizes

Exact image sizes with width and height

With the placeholders {width} and {height} an endpoint delivers the image in exactly the requested size – rendered from the original file, never upscaled. Both placeholders may sit next to static text in a segment, so foreign URL schemes can be reproduced. The query parameters width and height work instead of the placeholders as well.

• Width or height only: The image is scaled along that edge; the aspect ratio is kept.
• Width and height: The endpoint's Fit for width × height decides. Fill the box and centre-crop (cover) scales until the box is filled and crops the overflow around the centre – the image then has exactly the requested dimensions. Fit inside the box without cropping (contain) scales until the whole image fits inside the box.
• No upscaling: If the original is smaller than requested, it comes back at its own size.
• Allowed sizes: Because the feed is public, you can define per endpoint which sizes may be requested – as 800 (width), 292x219 (box) or x219 (height). With a non-empty list, every other size answers 404. With an empty list, any size up to 8192 px per edge is allowed.

Paging

A list endpoint is always paginated. Without pageSize the external system receives 100 assets per page. To let it find the following pages, the template provides the page object – with page.nextUrl pointing to the next page, and null when there is none. How to write these values into the JSON is shown by the default template.

Status codes