Getting Library and Element Data

Any integration with the Libraries API will involve reading information about a user's stored libraries and elements.

For example, you may want answers to questions like:

What libraries or elements were created in the last week?
What is the name of each element in a given library?
Where is the thumbnail for a given library element?

As you might imagine, you can accomplish all of this and much more with GET requests to the Libraries API.

Depending on your use case, you may prefer to make your Libraries API calls from the client or from your server. In this tutorial, we're going to focus on how to make calls from your server with Node.js and Express.

In each step, we'll set up an Express route to make an API call and talk a little about the response we get. The accompanying sample repo will embellish slightly on what we cover here by making simple use of the API responses in the browser.

Reading through this tutorial will give you a simple jumping off point for learning more about our GET endpoints in the API references.

Before you start

Technology Used

Node.js
npm
Express
Axios

Prerequisites

Development Steps

Info Complete code for this tutorial can be found on GitHub.

1. Bootstrap an Express app

We'll start by using express-generator, a scaffolding tool provided by Express, a popular server-side framework for Node.js. In your terminal, create your project:

npx express-generator --ejs --git myapp
Copied to your clipboard
npx express-generator --ejs --git myapp

Info You can learn more about express-generator in their docs. For our purposes here, this is all we need to do before digging in.

Then navigate to your new project, install dependencies, and start your app:

cd myapp
npm install --save axios dotenv
touch .env
npm start
Copied to your clipboard
1cd myapp
2npm install --save axios dotenv
3touch .env
4npm start

Info For setting up your .env file, see the "Set up your environment variables" section in our Quick Start: Node.js tutorial.

In your browser, if you navigate to localhost:3000, you'll see the default home page created by express-generator. (We won't be working with UI in this tutorial, but the accompanying sample repo makes very basic use of the API responses in the browser.)

2. Get metadata about your user's Libraries

We'll get started with the Libraries API by getting a top-level view of the libraries that the user has stored.

Creating the route

In the app we just generated, we'll create a new route in the routes/index.js file:

require("dotenv").config();
const express = require("express");
const router = express.Router();
const axios = require("axios"); // Be sure to require axios

const baseURL = "https://cc-libraries.adobe.io/api/v1/libraries";

// The default GET route provided by express-generator
router.get("/", async (req, res, next) => {
  res.render("index", { title: "Creative Cloud Libraries API" });
});

// Our new route
router.get("/cc-libraries/data", async (req, res, next) => {
  const options = {
    headers: {
      "x-api-key": process.env.API_KEY,
      Authorization: `Bearer ${process.env.ACCESS_TOKEN}`,
    },
  };

  try {
    const response = await axios.get(baseURL, options);
    res.json(response.data);
  } catch (error) {
    console.log(error);
    next(error);
  }
});

module.exports = router;
Copied to your clipboard
1require("dotenv").config();
2const express = require("express");
3const router = express.Router();
4const axios = require("axios"); // Be sure to require axios
5
6const baseURL = "https://cc-libraries.adobe.io/api/v1/libraries";
7
8// The default GET route provided by express-generator
9router.get("/", async (req, res, next) => {
10  res.render("index", { title: "Creative Cloud Libraries API" });
11});
12
13// Our new route
14router.get("/cc-libraries/data", async (req, res, next) => {
15  const options = {
16    headers: {
17      "x-api-key": process.env.API_KEY,
18      Authorization: `Bearer ${process.env.ACCESS_TOKEN}`,
19    },
20  };
21
22  try {
23    const response = await axios.get(baseURL, options);
24    res.json(response.data);
25  } catch (error) {
26    console.log(error);
27    next(error);
28  }
29});
30
31module.exports = router;

Info Above this route, we've also set the baseURL variable. We'll use this variable in other routes later on, so make sure you've set it outside of the route as you see above.

What it does

The heart of the "/cc-libraries/data" route is where we make the API call (for this example, we're using the axios module for making HTTP requests):

const response = await axios.get(baseURL, options);
res.json(response.data);
Copied to your clipboard
1const response = await axios.get(baseURL, options);
2res.json(response.data);

If everything goes well, we'll get a response from the Libraries API that contains JSON data (in this example, within response.data) that we return to the browser.

Try it out

You can access this endpoint by navigating your browser to:

http://localhost:3000/cc-libraries/data
Copied to your clipboard
http://localhost:3000/cc-libraries/data

The response will look something like this:

{
  "total_count": 2,
  "libraries": [
    /* Your libraries here */
  ]
}
Copied to your clipboard
1{
2  "total_count": 2,
3  "libraries": [
4    /* Your libraries here */
5  ]
6}

The libraries array contains a JSON object full of metadata related to each of your user's Libraries. Each object in this array will have a unique id property for that specific library:

{
  "id": "AAAAAA-AAAA-AAAA-AAAA-AAAAAAAAAAAA",
  "name": "My Libraray",
  "created_date": 1565044330560,
  "modified_date": 1568329791348
  /* More library metadata */
}
Copied to your clipboard
1{
2  "id": "AAAAAA-AAAA-AAAA-AAAA-AAAAAAAAAAAA",
3  "name": "My Libraray",
4  "created_date": 1565044330560,
5  "modified_date": 1568329791348
6  /* More library metadata */
7}

Go ahead and copy an id from one of your libraries. We'll use it in the next step.

3. Get metadata for elements in a specific Library

Next we'll get a list of elements contained in a given library.

Creating the route

Back in routes/index.js, we'll create a route for retreiving metadata for a specific Library's elements:

router.get("/cc-libraries/data/:libraryId", async (req, res, next) => {
  const { libraryId } = req.params;

  const options = {
    headers: {
      "x-api-key": process.env.API_KEY,
      Authorization: `Bearer ${process.env.ACCESS_TOKEN}`,
    },
  };

  try {
    const response = await axios.get(
      `${baseURL}/${libraryId}/elements`,
      options
    );
    res.json(response.data);
  } catch (error) {
    console.log(error);
    next(error);
  }
});
Copied to your clipboard
1router.get("/cc-libraries/data/:libraryId", async (req, res, next) => {
2  const { libraryId } = req.params;
3
4  const options = {
5    headers: {
6      "x-api-key": process.env.API_KEY,
7      Authorization: `Bearer ${process.env.ACCESS_TOKEN}`,
8    },
9  };
10
11  try {
12    const response = await axios.get(
13      `${baseURL}/${libraryId}/elements`,
14      options
15    );
16    res.json(response.data);
17  } catch (error) {
18    console.log(error);
19    next(error);
20  }
21});

What it does

Our route above takes a libraryId parameter. This parameter is then used to create the Libraries API endpoint we want to call:

`${baseURL}/${libraryId}/elements`;
// Or, https://cc-libraries.adobe.io/api/v1/libraries/AAAAAA-AAAA-AAAA-AAAA-AAAAAAAAAAAA/elements
Copied to your clipboard
1`${baseURL}/${libraryId}/elements`;
2// Or, https://cc-libraries.adobe.io/api/v1/libraries/AAAAAA-AAAA-AAAA-AAAA-AAAAAAAAAAAA/elements

As in the first route, we use the axios module to make the HTTP request. If the request is successful, we get a JSON object from the Libraries API that we send back to the browser.

Try it out

You can access this endpoint by navigating your browser to this URL (be sure to swap in the library ID you copied in the previous step):

http://localhost:3000/cc-libraries/data/AAAAAA-AAAA-AAAA-AAAA-AAAAAAAAAAAA
Copied to your clipboard
http://localhost:3000/cc-libraries/data/AAAAAA-AAAA-AAAA-AAAA-AAAAAAAAAAAA

The response will look something like this:

{
  "total_count": 60,
  "elements": [
    /* Library elements here */
  ]
}
Copied to your clipboard
1{
2  "total_count": 60,
3  "elements": [
4    /* Library elements here */
5  ]
6}

The elements array contains a JSON object full of metadata related to each of the elements stored in a given Library:

{
  "id": "BBBBBBBB-BBBB-BBBB-BBBB-BBBBBBBBB",
  "name": "An Element Name",
  "created_date": 1565044330560,
  "modified_date": 1568329791348,
  "type": "application/vnd.adobe.element.pattern+dcx",
  "thumbnail": {},
  "groups": [],
  "assetSubType": "element"
}
Copied to your clipboard
1{
2  "id": "BBBBBBBB-BBBB-BBBB-BBBB-BBBBBBBBB",
3  "name": "An Element Name",
4  "created_date": 1565044330560,
5  "modified_date": 1568329791348,
6  "type": "application/vnd.adobe.element.pattern+dcx",
7  "thumbnail": {},
8  "groups": [],
9  "assetSubType": "element"
10}

Info It's worth noting that if you already have a specific element ID that you want metadata for, you can request it directly using the element ID (e.g., ${baseURL}/${libraryId}/elements/${elementId}). See the endpoint references for more details.

4. Getting image renditions and thumbnails

Next we'll get an image rendition for a specific element.

Creating the route

Back in routes/index.js, we'll create a route for retreiving an image representation of a Library element:

router.get("/cc-libraries/image", async (req, res, next) => {
  let { url } = req.query;
  url = url.slice(0, url.lastIndexOf("/")); // See the Info box below

  const options = {
    responseType: "arraybuffer",
    headers: {
      "x-api-key": process.env.API_KEY,
      Authorization: `Bearer ${process.env.ACCESS_TOKEN}`,
    },
  };

  try {
    const response = await axios.get(url, options);
    const dataUrl = getBase64dataUrl(response);

    res.set("Content-Type", response.headers["content-type"]);
    res.set("Content-Length", response.headers["content-length"]);
    res.send(dataUrl);
  } catch (error) {
    console.log(error.message);
    next(error);
  }
});

const getBase64dataUrl = (response) => {
  const base64flag = `data:${response.headers["content-type"]};base64,`;
  const base64string = Buffer.from(response.data, "binary").toString("base64");

  return `${base64flag}${base64string}`;
};
Copied to your clipboard
1router.get("/cc-libraries/image", async (req, res, next) => {
2  let { url } = req.query;
3  url = url.slice(0, url.lastIndexOf("/")); // See the Info box below
4
5  const options = {
6    responseType: "arraybuffer",
7    headers: {
8      "x-api-key": process.env.API_KEY,
9      Authorization: `Bearer ${process.env.ACCESS_TOKEN}`,
10    },
11  };
12
13  try {
14    const response = await axios.get(url, options);
15    const dataUrl = getBase64dataUrl(response);
16
17    res.set("Content-Type", response.headers["content-type"]);
18    res.set("Content-Length", response.headers["content-length"]);
19    res.send(dataUrl);
20  } catch (error) {
21    console.log(error.message);
22    next(error);
23  }
24});
25
26const getBase64dataUrl = (response) => {
27  const base64flag = `data:${response.headers["content-type"]};base64,`;
28  const base64string = Buffer.from(response.data, "binary").toString("base64");
29
30  return `${base64flag}${base64string}`;
31};

Info Note that above, for simplicity we are naively slicing off from the url query the rendition argument the Libraries API provides by default, which is :rendition;size=200. Slicing this off gives you a full-size image, which in many cases may not be ideal due to size. If you have a specific size in mind, you can change 200 to another value, or keep the query in tact.

What it does

Our route above takes a url query (/cc-libraries/image?url=https://url-here). The value of this query (which is the element's thumbnail URL we copied in the previous step) is then used to call the Adobe storage service:

const response = await axios.get(url, options);
Copied to your clipboard
const response = await axios.get(url, options);

Again, we use the axios module to make the HTTP request. If the request is successful, we receive image data that we can do further work with.

Info Note that, unlike in our previous routes, here we are not using the Libraries API baseURL variable that we defined earlier. Images come from another service which we will call directly.

The route will then transform the response data from an array buffer to a base64 data URL (dataUrl) that can be used as the src of an image element in the browser. This step is just for the purpose of demonstration; you might have other uses for the image data.

Try it out

You can access this endpoint by navigating your browser to this URL (be sure to swap in the thumbnail URL you copied in the previous step):

http://localhost:3000/cc-libraries/image?url=https://url-here
Copied to your clipboard
http://localhost:3000/cc-libraries/image?url=https://url-here

Your browser will receive a base64 string representing the image data. Since we haven't set up an image element to display the image data, you'll need to have a look in your browser's developer tools to see the data. In Chome DevTools for example, you can find the data string in the Sources tab, under top > localhost:{port} > cc-libraries > image?url=https://url-here:

data:image/jpeg;base64,base64stringhere...
Copied to your clipboard
data:image/jpeg;base64,base64stringhere...

If we wanted to display the image, this base64 data URL (dataUrl) could be used as the src of an image element. In fact, the accompanying sample repo does this if it's something you're interested in seeing.

Guides

Working with library elements