Skip to main content

Backlight JSON API

Backlight exposes an API for accessing published albums, album sets and photos.

The raw API is documented below. We have also created two API libraries:

  • JSON API Library for jQuery
  • JSON API Library for modern JavaScript

To get started, visit Backlight's Settings page, Admin => Settings. Scroll down to the "JSON API" section, and set Enable JSON API: yes.

The API​

Hit the API endpoints at /backlight/api, wherever you have Backlight installed. Successful responses will deliver a JSON object containing the requested data.

You may determine id programmatically, or observe the id in the browser's address bar when viewing the desired item in Backlight's publisher.

We are not providing sample responses, but you can travel to the endpoints in your browser to observe the results for yourself. If using Chrome, then the JSON Formatter extension is nice to have.

get / get_album​

/backlight/api/get_album/:id
/backlight/api/get/:id

Two equivalent endpoints; get_album is preferred, with get being an alias. Returns all of the data for the album, including the album's title, description, photos, etc.

To get data for an album with id 12345, use:

/backlight/api/get_album/12345

get_photo​

backlight/api/get_photo/:id

Gets the data for a single photo.

To get data for an album with id 67890, use:

backlight/api/get_photo/67890

get_photos​

backlight/api/get_photos/:id/(:from)/(:to)

Returns the album's photos array, without the extra album data. Can be used to fetch a partial range of photos.

To get all photos in an album with id 12345, use:

/backlight/api/get_photos/12345

To get only the first ten photos from that same album, provide from and to parameters:

/backlight/api/get_photos/12345/1/10

get_publisher_root​

/backlight/api/get_publisher_root/:id

Returns data for a top-level set. For example, use this to get data for the default galleries top-level set, which is created with an id of 1:

/backlight/api/get_publisher_root/1

get_all_publisher_roots​

/backlight/api/get_all_publisher_roots

Returns data for all of a site's top-level sets.

JavaScript Library​

The library for modern JavaScript can be found at:

backlight/modules/module-publisher/lib/js/api.js

This library uses the Fetch API, so will not work in Internet Explorer. If needing to support older browsers, see the jQuery Library, else you will need to code your own solution.

To use, the API needs to be instantiated:

const backlight = new Backlight()

This assumes Backlight to be installed at the default location, e.g. yourdomain.com/backlight. If this is not the case, then you will need to instantiate the API with the URL to your API:

const backlight = new Backlight('/path/to/backlight/api')

getAlbum​

getAlbum(id, { done: function, fail: function })

Uses the get_album endpoint; id and done are required; fail is optional.

const backlight = new Backlight()

backlight.getAlbum('12345', {
    done: data => {
        // do something with the data
    },
    fail: error => {
        // handle the error
    },
})

getPhoto​

getPhoto(id, { done: function, fail: function })

Uses the get_photo endpoint; id and done are required; fail is optional.

const backlight = new Backlight()

backlight.getPhoto('67890', {
    done: data => {
        // do something with the data
    },
    fail: error => {
        // handle the error
    },
})

getPhotos​

getPhotos(id, { from: num, to: num, done: function, fail: function })

Uses the get_photos endpoint; id and done are required; from, to and fail are optional.

const backlight = new Backlight()

backlight.getPhotos('12345', {
    from: 1,
    to: 10,
    done: data => {
        // do something with the data
    },
    fail: error => {
        // handle the error
    },
})

getRoot​

getRoot(id, { done: function, fail: function }

Uses the get_publisher_root endpoint; id and done are required; fail is optional.

const backlight = new Backlight()

backlight.getRoot(1, {
    done: data => {
        // do something with the data
    }
})

If the id is passed as null or undefined, the get_all_publisher_roots endpoint will be used instead, returning data for all top-level sets.

jQuery Library​

The library for jQuery can be found at:

backlight/modules/module-publisher/lib/js/jquery.api.js

This uses jQuery.ajax(), and requires jQuery 3 or newer.

The interface here is almost exactly the same as the JavaScript API above. The only difference is that the done and fail methods grant access to some additional parameters, and that we prefer the ES5 syntax.

var backlight = new Backlight()

backlight.getAlbum(id, {
    done: function(data, textStatus, jqXHR) {
        // do something with the data
    },
    fail: function(jqXHR, textStatus, errorThrown) {
        // handle the error
    },
})

Such is the case for all methods, getAlbum, getPhoto, getPhotos, getRoot.

Of course, the extra parameters may be more than you need to think about. In many circumstances, this is just fine:

var backlight = new Backlight()

backlight.getAlbum(id, {
    done: function(data) {
        // do something with the data
    },
})