Make resize and format URLs predictable, safe, and cacheable.
Constrain the recipe
A transformation URL should identify an immutable source plus a small allowed set of operations: width, height, fit, quality, and format. Normalize equivalent requests to one canonical recipe. Cap output dimensions and pixel count before starting a decoder so one request cannot consume excessive memory.
Version intentional changes
When crop behavior, sharpening, or encoder settings change, include a recipe version in the derivative identity. Otherwise a cached URL can mean different bytes before and after deployment. Record transformation errors separately from missing source assets.
Protect the origin
If anyone can request any width for any source, a crawler can create thousands of variants. Use named presets for common UI slots, sign private transformations, and rate-limit expensive misses. Warm only genuinely important variants; on-demand generation is useful when the variant space is bounded.
A concrete acceptance test
Request the same transform with reordered parameters, then request a disallowed extreme width. The first two URLs should map to one output; the extreme request should fail before expensive decoding. Run this test with a realistic asset and record the observed state, output URL, and failure reason.
Implementation check
- Canonicalize equivalent transformation recipes.
- Reject excessive dimensions before decoding.
- Version the recipe when output bytes change.
Related guides
Primary reference: Official documentation.