Napoleon's Penguin Mascot

    imgix-management-js
    TypeScript icon, indicating that this package has built-in type declarations

    1.3.1 • Public • Published

    ⚠️ 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.

    NPM Version Build Status Monthly Downloads Minified Size License styled with prettier FOSSA Status


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

    License

    FOSSA Status

    Install

    npm i imgix-management-js

    DownloadsWeekly Downloads

    70

    Version

    1.3.1

    License

    BSD-2-Clause

    Unpacked Size

    29.1 kB

    Total Files

    15

    Last publish

    Collaborators

    • atlawrie
    • imgix-company
    • czacharias
    • sherwinski
    • cnoble
    • matt-imgix
    • heyitsbryanm
    • ultimatealf
    • edsz
    • lball
    • vuryanh