nuggan

API Reference

Request Format

All requests use the following URL format:

/:routePrefix/:cropX/:cropY/:cropWidth/:cropHeight/:resizeWidth/:resizeHeight/:compressionLevel/:base64Ref

The service accepts both GET and HEAD requests.

Path Parameters

routePrefix: Any request path prefix (not processed by Nuggan). Typically configured as optimg but can be any value.
cropX: Crop origin X coordinate (mandatory integer ≥ 0; 0 = leftmost edge).
cropY: Crop origin Y coordinate (mandatory integer ≥ 0; 0 = top edge).
cropWidth: Width of crop region according to the original image (optional integer ≥ 0 && ≤ original width OR "-"). Use "-" to skip cropping by width.
cropHeight: Height of crop region according to the original image (optional integer ≥ 0 && ≤ original height OR "-"). Use "-" to skip cropping by height.
resizeWidth: Target resize width (optional integer ≥ 0 && ≤ cropped width OR "-"). Use "-" to skip resize by width.
resizeHeight: Target resize height (optional integer ≥ 0 && ≤ cropped height OR "-"). Use "-" to skip resize by height.
compressionLevel: JPEG/PNG compression level (optional integer ≥ 0 OR "-"). Use "-" to use default compression.
base64Ref: Base64-encoded image reference. Format depends on strict mode setting (see below).

Image Reference Encoding

Strict Mode Disabled

If strict mode is disabled in your configuration, base64Ref can be any absolute URL encoded with Base64.

Example: Direct Base64 encoding of a public image URL.

Strict Mode Enabled

If strict mode is enabled, base64Ref must use the following format:

_{groupIndex}_{base64ImagePath}

groupIndex: 0-based index of the URL group to use from groupedBaseUrls configuration.
base64ImagePath: Base64-encoded image path that can be appended to any base URL from the specified group to resolve the absolute image URL.

Example: _2_L3BvcHRvY2F0X3YyLnBuZw==

Where:

2 is the group index (third group in groupedBaseUrls)
L3BvcHRvY2F0X3YyLnBuZw== is the Base64-encoded path /poptocat_v2.png

For validation details, see the codec acceptances test.

Examples

All examples below use the default configuration with routePrefix = "optimg". They reference the Poptocat image from the third group in groupedBaseUrls.

The original image is first cropped (if parameters are specified), then resized (if parameters are specified).