imgix-management-js
v1.3.1
Published
A Javascript library that wraps the imgix management API
Downloads
5,623
Readme
⚠️ This library is currently marked as experimental. We plan to eventually integrate it as its own module in @imgix/js-core
.
imgix-management-js
is a JavaScript client library for making requests against the imgix Management API.
- Installation
- Configuration
- API
- 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
:
CommonJS
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 to1
.
API
ImgixAPI.request(path, options)
path
: String, required. A partial path representing the relative URL endpoint to request. This will typically require asourceId
.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.
Retrieve a list of images
imgix.request(`assets/${sourceId}`)
.then(response => console.log(JSON.stringify(response, null, 2)));
Retrieve all details for a single image
imgix.request(`assets/${sourceId}/${originPath}`)
.then(response => console.log(JSON.stringify(response, null, 2)));
Retrieve custom fields for a single image
var customFields;
imgix.request(`assets/${sourceId}/uploads/pecanpie.jpg`)
.then(response => {
customFields = response.data.attributes.customFields;
console.log(customFields);
});
Update custom fields for a single image
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))
})
Upload an image
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)));
Retrieve all sources
imgix.request(`sources`)
.then(response => console.log(JSON.stringify(response, null, 2)));
Specify the fields returned
// 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));
Paging by page number and size
imgix.request(`assets/${sourceId}?page[number]=0&page[size]=1`)
.then(resp => console.log(resp))
Sorting lists of objects
// 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))
Filtering lists of objects
imgix.request('sources?filter[name]=staging&filter[deployment.type]=s3')
.then(resp => console.log(resp))
Create an object
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)));