Connect
Connecting
Five steps. The service operator does the first three, you do the last two on your side.
1. Domain
Pick the subdomain files will be served from — img.yourdomain,
say — and create the A record for it that the operator gives you.
The domain is declared canonical: it is what the service builds addresses from
in its answers.
A tenant can have as many domains as they like, but exactly one canonical. Otherwise one file gets two addresses, which means two caches and two downloads onto the reader's phone.
You do not have to connect a domain of your own: files are then served from
the shared keepix.cloud. Both roads work the same.
2. Kinds and variants
A kind (kind) is what sort of thing the file is:
prodimg for catalogue images, review for review
photos, and so on. For each kind it is declared which
variants it gets.
The ceilings are set at the same time: the size of one file, the number of uploads per minute, and the total volume.
3. Signing keys
You get two keys — an identifier and a secret for each. Two, not one, so that changing a key is not downtime: the new one goes into service while the old one is still valid, and only then is the old one put out.
The secret is shown once. Keep it where the project's other secrets live, and never pass it on the command line.
4. The first file
Send the original and save the addresses from the answer next to the record the file belongs to.
POST /api/v1/put?kind=prodimg&key=<your identifier>&variants=card,fullIf you already have ready-made copies, they can be moved over without
re-encoding through put-variant. Re-encoding what is already
finished means losing quality for nothing.
One place in the code, not four. Substitute the saved address in a single function that every storefront goes through. Spread the “local or on the service” condition across four pages and they will diverge on the first edit — and diverge silently.
5. A watchdog
Set up a check that walks the same path the storefront does: it asks the service for a known object and verifies four things — a 200 answer, the content type, a non-zero length, and that the address matches the one you have recorded.
The last one matters more than the rest. If the layout changes and you do not notice, the images vanish silently: the page renders, and where the product was there is a hole.
And test the watchdog by breaking something on purpose — substitute the recorded address and make sure it complains. A watchdog that has never fired is not a watchdog, it is a line in a config file.
What to do if a record is lost
Ask, do not guess:
GET /api/v1/resolve?kind=prodimg&key=48120
POST /api/v1/resolve-batch {"kind":"prodimg","keys":["1","2","…"]} ← up to 1000 keysThe service keeps the addresses precisely so that nobody has to derive them from a rule.