Building on it
Product pictures
A merchant gives a product one picture. The terminal asks for it at whatever size it wants to draw, in the same way the
Graph API lets you ask for a profile picture by width/height.
For the terminal#
Every catalog item (GET /v1/terminal/catalog, /v1/merchants/{id}/catalog, barcode lookup) carries imageId (null = no picture).
GET /v1/images/{imageId}?w=200&h=200&fit=cover&fmt=webp| Param | Meaning |
|---|---|
w, h |
Target size in pixels. Either or both. Rounded up to a multiple of 8 and capped at 1600, so a picture has few distinct sizes. |
fit |
contain (default): fits inside the box, keeps its shape. cover with both w and h: crops to exactly that shape. |
fmt |
webp (default), jpg or png. Pick jpg for very old Android WebViews. |
- No auth header. The
imageIdis an unguessable token naming one picture, so the URL is safe to hand to an image loader or CDN. - Never upscaled. Asking for more than we hold returns the largest size we have (the stored original is at most 2048 px).
- Cache it forever. Responses carry
Cache-Control: public, max-age=31536000, immutableand anETag. A changed picture gets a newimageId, and the product's variants reappear in the next catalog delta, so a terminal that keys its image cache onimageIdnever shows a stale picture and never needs to revalidate. - A removed picture arrives as
imageId: null; the old address then answers 404.
For the console / API#
POST /v1/merchants/{id}/products/{productId}/image: multipart fieldfile, JPEG/PNG/WebP, up to 6 MB and 8000 px a side. Replaces any existing picture. Needscatalog:write.DELETE /v1/merchants/{id}/products/{productId}/image.503with codeunavailablewhen the server has no storage configured.
How it works#
The upload is decoded, turned upright (EXIF orientation), stripped of all metadata (so phone GPS never leaves the server) and re-encoded as a WebP no larger than 2048 px: that is the only copy kept. Each requested size is rendered from it on first request and stored beside it, so the second request is a file read. At most four renders run at once, so a burst of new sizes queues rather than starving the sales API.
Storage is S3-compatible (MinIO locally, any S3 later). The bucket is never public: pictures leave only through /v1/images, the same rule that keeps owl-express's MinIO internal.
| Setting | |
|---|---|
Storage__Endpoint |
e.g. minio:9000. Empty = pictures disabled |
Storage__AccessKey, Storage__SecretKey |
|
Storage__Bucket |
default tillstack (created on first use) |
Storage__UseSsl |
true for HTTPS endpoints |
Locally: docker compose up -d minio (console on :9003), then set the variables above with endpoint localhost:9002.
Not done#
- One picture per product (not per variant); no gallery.
- Orphaned renders are deleted with their picture, but a crash between the database write and the delete leaves a few kilobytes behind; there is no sweeper.
- No rate limit on
/v1/imagesbeyond the render concurrency cap. Put Cloudflare in front in production (the responses are built for it).