State of the URL API

When you’re looking for information about an imgix feature, the API documentation is your friend—every parameter in the service is listed with examples, ranges, and default values. We also have in-depth tutorials for more complex multi-parameter use cases.

This is great for humans who need to know the ins and outs of imgix, but what about machines? If you’re building tools, libraries, or URL generators based on our Image URL API, having a single, machine-readable source of truth about the capabilities of all available parameters is crucial. Fortunately, it’s available on GitHub in JSON format and as Bower and NPM packages.

Because it can be plugged directly into your projects, you can use the imgix-url-params distribution file to validate parameter inputs, build UI components, or programmatically assemble imgix URLs. It lists all pertinent information about each parameter, including input type expectations, ranges, defaults, and documentation links. The specification comes in two formats:

• dist/parameters.json is a JSON file with maps of all available parameters and their properties. It also includes a map of aliases for easy lookup of alternate parameter names.
• dist/parameters.js is a UMD wrapper around the JSON file, allowing it to be loaded easily in a <script> tag and accessed via a global imgixParameters object.

We use these files internally to set ranges in our Sandbox tool and documentation examples, ensuring that UI components conform to each parameter’s expectations. Now you can do the same—for instructions about how to add them to your project, check out the repo on GitHub.