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-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
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 to 1.

API

`ImgixAPI.request(path, options)`

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.

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)));