imgix-management-js

⚠️ This library is currently marked as experimental. We plan to eventually integrate it as its own module in @imgix/js-core.

!imgix logo

imgix-management-js is a JavaScript client library for making requests against the imgix Management API.


---

- Installation
* CommonJS
- Configuration
- API
* ImgixAPI.request(path, options)
- Usage Examples
* Retrieve a list of images
* Retrieve all details for a single image
* Retrieve custom fields for a single image
* Update custom fields for a single image
* Upload an image
* Retrieve all sources
* Specify the fields returned
* Paging by page number and size
* Sorting lists of objects
* Filtering lists of objects
* Create an object
- License

Installation

npm install imgix-management-js

imgix-management-js exposes a class ImgixAPI:

$3

``js
const ImgixAPI = require("imgix-management-js");

const imgix = new ImgixAPI({
apiKey: ${yourApiKey}
});
`

Configuration

The following options can be used when creating an instance of ImgixAPI:

- apiKey: String, required. The token used to authenticate API requests.
- version: Integer. The version of the API that will be requested against. Defaults to 1.

API

$3

- path: String, required. A partial path representing the relative URL endpoint to request. This will typically require a sourceId.
- options: Object. Any custom HTTP(S) settings to be applied to a request.
* method: String, required. The request method, defaults to 'GET'.
* headers: Object. Additional information included with a request.
* body: Object, String, or Buffer. A resource, such as binary data or a file, included with the request.

Makes a request against the specified imgix Management API endpoint.

Returns: Promise<[Response]>

The supplied path should be a relative URL, such as assets/{sourceId}. Using this path, the full API URL will be constructed at the time that the request is made, saving users the need to provide the full URL themselves each time.

ImgixAPI will intelligently populate any necessary headers prior to completing the request. This includes fields such as Content-Type and Authorization. Outside of that, the options argument can be used to override certain defaults, such as the HTTP request method, or provide a file for uploading.

Usage Examples

The following sections demonstrate how to use this library to make API requests for common use cases. For a full list of endpoints and operations, see the management API docs.

$3

`js
imgix.request(assets/${sourceId})
.then(response => console.log(JSON.stringify(response, null, 2)));
`

$3

`js
imgix.request(assets/${sourceId}/${originPath})
.then(response => console.log(JSON.stringify(response, null, 2)));
`

$3

`js
var customFields;

imgix.request(assets/${sourceId}/uploads/pecanpie.jpg)
.then(response => {
customFields = response.data.attributes.customFields;
console.log(customFields);
});
`

$3

`js
var document = {
'data': {
'id': ${sourceId}/pecanpie.jpg,
'type': 'assets',
'attributes': {}
}
};

imgix.request(sources/${sourceId}/assets/pecanpie.jpg)
.then(response => {
/*
** Populate document with all pre-existing fields
** so as to not overwrite them when sending a PATCH request
*/
document.data.attributes.custom_fields = response.data.attributes.custom_fields;
document.data.attributes.custom_fields.type = 'dessert';

// PATCH request to write in new custom field
imgix.request(sources/${sourceId}/assets/pecanpie.jpg, {
method: 'PATCH',
body: document
})
.then(response => console.log(response.data.attributes))
})
`

$3

`js
const data = fs.readFileSync('./src/monstera.jpg');

imgix.request(sources/upload/${sourceId}/monstera.jpg, {
method: 'POST',
body: data
})
.then(response => console.log(JSON.stringify(response, null, 2)));
`

$3

`js
imgix.request(sources)
.then(response => console.log(JSON.stringify(response, null, 2)));
`

$3

`js
// To request a deeply-nested field, use dot notation

imgix.request(sources/${sourceId}?fields[sources]=name,deployment_status,deployment.default_params)
.then(resp => console.log(resp));
`

$3

`js
imgix.request(assets/${sourceId}?page[number]=0&page[size]=1)
.then(resp => console.log(resp))
`

$3

`js
// To sort a field in descending order, prepend a dash “-” to the field name.

imgix.request('sources?sort=name&fields[sources]=name')
.then(resp => console.log(resp))
`

$3

`js
imgix.request('sources?filter[name]=staging&filter[deployment.type]=s3')
.then(resp => console.log(resp))
`

$3

`js
var data = {
"data": {
"attributes": {
"name": "New Web Folder Source",
"deployment": {
"type": "webfolder",
"webfolder_base_url": "https://my-domain.com/images/",
"imgix_subdomains": [
"my-unique-imgix-subdomain"
]
}
},
"type": "sources"
},
"jsonapi": {
"version": "1.0"
}
}

imgix.request(sources, {
method: 'POST',
body: data
})
.then(response => console.log(JSON.stringify(response, null, 2)));
``

License