Edit in GitHubLog an issue

Creating Library Elements

This document provides background on workflows to create library elements. It does not assume that you have any background in library element concepts. However, it does assume that you are already familiar with how to call the Libraries API, e.g., how to get an API token, required header fields, etc. this document attempts to remain technology-agnostic w.r.t. documenting API calls.

Background

A library consists of one or more library elements. These elements consist of metadata that represent entities which are used within different Creative Cloud applications, e.g., images, videos, colors, 3D models, etc. Library elements contain one or more representations, each of which refers to, or contains, an asset, and will have a particular relationship to the entity represented by the element.

Representations may have one of three different relationships to the entity they represent, 'primary', 'rendition', or rarely, 'alternate'. 'Primary' representations usually refer to the asset that is the thing itself, e.g., for graphics, the largest, highest-resolution version; for 3d models, the file containing 3d data, etc. All library elements should have a single primary representation. 'Renditions' typically refer to versions of the primary representation specific to some use case, e.g., a thumbnail for display on a web page. Elements may have an unlimited number of renditions. The 'alternate' relationship designates alternative primary representations that are used in different contexts; currently, its use is limited to pattern elements.

Assets in this context refer to the primary data source for some representation, e.g., for an image, it will be some image file, for colors, it will be a json document containing the spec for that color, etc.

Generally Required Properties

In addition to a list of representations, every library element requires a "type" property, and a "client" dictionary.

The "type" property will contain the MIME type of the library element you are creating. This type will be in the group application/vnd.adobe.*+dcx.

The "client" dictionary contains the properties "deviceId", "device", and "app". These fields are unchecked, but you will get them back with future element requests, and it may be helpful to populate them with something meaningful to track who or what is creating or modifying library elements.

Each representation is required to contain a "type" property that is the MIME type of that representation. The primary representation type is constrained according to the MIME type of the library element. For example, when creating a color, the library element will have a MIME type of "application/vnd.adobe.element.color+dcx", and the primary representation must be of type "application/vnd.adobe.color+json". Other properties within the representation may be required depending on the representation type.

Generally, all representations should also contain a "relationship" property as described above. However, this is not strictly required; the default relationship is "rendition."

Copied to your clipboard
1{
2  "name": "my-cool-graphic",
3  "type": "application/vnd.adobe.element.image+dcx",
4  "client": {
5    "deviceId": "MY_COOL_DEVICE_ID",
6    "device": "MY_COOL_DEVICE",
7    "app": "MY_COOL_APP"
8  },
9  "representations": [
10    {
11      "type": "image/svg+xml",
12      "relationship": "primary",
13      "storage_href": "https://cc-api-storage-stage.adobe.io/assets/adobe-libraries/4dc522a7-af3d-4274-986c-bb1f59bb20d0/3f4d2883-f7e5-4d64-bec1-f153ae5d80af"
14    }
15  ]
16}

Figure 1: An example image payload for postLibraryElements (/api/v1/libraries/{{library-id}}/elements/), containing the minimum required properties.

Asset Types, Usage Patterns, Required Fields by Asset Type

Assets generally fall into three categories: 1. User-uploaded, 2. Self-contained, 3. Stock. Each category of asset may require a different usage pattern to correctly create a library element, and each requires different representation properties.

User-Uploaded Assets

User-uploaded assets are files that are uploaded before the library element is created, and the library element should contain a link to that file. In other words, the recommended pattern for creating any library element that contains user-uploaded assets is to upload all the assets first, then create the library element referencing them using a single call to the Libraries service. The steps to upload assets change depending on the size of the file; files under 5mb in size may be uploaded in one shot, files over 5mb must be broken into chunks.

User-uploaded asset representations require, alongside a "type" property, either a "storage_href" or "path" property, but not both. The "storage_href" property should contain an absolute link to the asset in Creative Cloud storage, and "path" should contain the relative path to the asset (TODO: ?? & explain this). Figure 1 contains an example of a valid asset representation.

Self-contained Assets

Self-contained assets refer to assets that are entirely contained within the library element representation metadata. In this case, only a single call to the Library service is needed. An example might be a json document describing a color. Self-contained assets will always contain a required namespaced property, e.g., for colors, "color#data". The requirements for these properties will vary by representation type.

Copied to your clipboard
1{
2  "name": "my-cooler-color",
3  "type": "application/vnd.adobe.element.color+dcx",
4  "client": {
5    "deviceId": "MY_COOL_DEVICE_ID",
6    "device": "MY_COOL_DEVICE",
7    "app": "MY_COOL_APP"
8  },
9  "representations": [
10    {
11      "type": "application/vnd.adobe.color+json",
12      "relationship": "primary",
13      "color#data": {
14        "mode": "CMYK",
15        "value": {
16          "c": 100,
17          "m": 79.0585160255432,
18          "y": 39.5178139209747,
19          "k": 31.2565803527832
20        },
21        "type": "process"
22      }
23    },
24    {
25      "id": "fe595a93-aefc-4e2f-a6a7-d594610f292f",
26      "type": "application/vnd.adobe.color+json",
27      "relationship": "rendition",
28      "color#data": {
29        "mode": "RGB",
30        "value": {
31          "r": 12.7313232421875,
32          "g": 56.0341644287109,
33          "b": 89.8001861572266
34        },
35        "type": "process"
36      }
37    }
38  ]
39}

Figure 2: An example color payload for postLibraryElement, containing two color representations, each with a required "color#data" property.

Stock Assets

Stock assets refer to files managed within the Adobe Stock product. Library elements that contain stock asset representations will contain a link to the asset within Adobe Stock, as well as additional metadata describing the stock asset. A stock asset is acceptable within a library element representation wherever a user-uploaded asset is (TODO: glossing over this for the moment).

In Practice

Although the last few examples contained different asset types in isolation, it is more realistic to expect to use multiple asset types within a single library element. For example, a common scenario is to have a primary representation that contains a self-contained asset, and other asset renditions.

Let's say we want to create a font element. The font element requires two representations: a self-contained font specification, and a thumbnail image. In this example, for clarity, we will assume that the thumbnail image is under 5mb in size. If the image were bigger, we would need to upload the file in chunks (see below).

First, we would upload the thumbnail:

POST /api/v1/libraries/{{library-id}}/representations/content

Copied to your clipboard
1(form-data)
2Representation-Data: {"type":"image/png"}
3Representation-Content: <... the file ...>
4

5Response:
6{
7    "id": "602eb2e4-d86d-481f-adc2-d751fc5ca961",
8    "storage_href": "https://cc-api-storage-stage.adobe.io/id/urn:aaid:sc:US:efb1969b-fed5-4381-836e-6d7a97a14fbf?component_id=602eb2e4-d86d-481f-adc2-d751fc5ca961",
9    "asset_id": "urn:aaid:sc:US:e51bf45b-5799-43bb-9c64-37857357cb5e",
10    "type": "image/png",
11    "content_length": 158356,
12    "etag": "\"9b4fb626b2ea694ceceda1b5caa7463c\"",
13    "md5": "m0+2JrLqaUzs7aG1yqdGPA==",
14    "version": "0"
15}

Then, we would upload the metadata:

POST /api/v1/libraries/{{library-id}}/elements/

Copied to your clipboard
1REQUEST:
2{
3  "name": "my-coolest-font",
4  "type": "application/vnd.adobe.element.font+dcx",
5  "client": {
6    "deviceId": "MY_COOL_DEVICE_ID",
7    "device": "MY_COOL_DEVICE",
8    "app": "MY_COOL_APP"
9  },
10  "representations": [
11    {
12      "type": "application/vnd.adobe.font+json",
13      "relationship": "primary",
14      "font#data": {
15          "postScriptName": "TimesNewRomanPS-BoldMT",
16          "name": "Times New Roman Bold",
17          "family": "Times New Roman",
18          "style": "Bold",
19          "typekitFontId": "some_meaningful_uuid",
20          "foundry": "The FooBaz Corporation"
21        }
22    },
23    {
24        "type": "image/png",
25        "relationship": "rendition",
26        "storage_href": "https://cc-api-storage-stage.adobe.io/id/urn:aaid:sc:US:efb1969b-fed5-4381-836e-6d7a97a14fbf?component_id=602eb2e4-d86d-481f-adc2-d751fc5ca961",
27        "content_length": 158356,
28        "etag": "\"9b4fb626b2ea694ceceda1b5caa7463c\"",
29        "md5": "m0+2JrLqaUzs7aG1yqdGPA==",
30        "version": "0"
31    }
32  ]
33}
34

35RESPONSE:
36{
37    "total_count": 1,
38    "elements": [
39        {
40            "id": "9e46e07f-f9c1-4380-b199-754c1f6ffb9c",
41            "name": "my-coolest-font",
42            "created_date": 1590014039430,
43            "modified_date": 1590014039430,
44            "type": "application/vnd.adobe.element.font+dcx",
45            "thumbnail": {},
46            "assetSubType": "element",
47            "_fc": false,
48            "path": "ad9bcb38-b783-4490-8ca4-a87b18b12349",
49            "library#createdData": {
50                "app": "MY_COOL_APP",
51                "time": 1590014039430,
52                "userId": "35305C3E5E861DB40A494026@AdobeID",
53                "deviceId": "MY_COOL_DEVICE_ID",
54                "device": "MY_COOL_DEVICE"
55            },
56            "library#modifiedData": {
57                "app": "MY_COOL_APP",
58                "time": 1590014039430,
59                "userId": "35305C3E5E861DB40A494026@AdobeID",
60                "deviceId": "MY_COOL_DEVICE_ID",
61                "device": "MY_COOL_DEVICE"
62            }
63        }
64    ]
65}

Afterwards, if you were to get the element, it might look like this:

GET /api/v1/libraries/{{library-id}}/elements/9e46e07f-f9c1-4380-b199-754c1f6ffb9c?selector=full

Copied to your clipboard
1{
2  "id": "9e46e07f-f9c1-4380-b199-754c1f6ffb9c",
3  "name": "my-coolest-font",
4  "created_date": 1590014039430,
5  "modified_date": 1590014039432,
6  "type": "application/vnd.adobe.element.font+dcx",
7  "thumbnail": {
8    "type": "href",
9    "rendition": "https://cc-api-storage-stage.adobe.io/assets/adobe-libraries/4dc522a7-af3d-4274-986c-bb1f59bb20d0/22fd8c85-eb35-47bc-aa0d-379497e7414e/:rendition;size=200"
10  },
11  "representations": [
12    {
13      "id": "22fd8c85-eb35-47bc-aa0d-379497e7414e",
14      "type": "image/png",
15      "relationship": "rendition",
16      "path": "84688801-5e6e-466e-a896-fd69188d9904",
17      "is_full_size": false,
18      "is_external_link": false,
19      "content_length": 158356,
20      "version": "0",
21      "md5": "m0+2JrLqaUzs7aG1yqdGPA==",
22      "_links": {
23        "http://ns.adobe.com/melville/rel/primary": {
24          "href": "https://cc-api-storage-stage.adobe.io/assets/adobe-libraries/4dc522a7-af3d-4274-986c-bb1f59bb20d0/22fd8c85-eb35-47bc-aa0d-379497e7414e",
25          "rel": "http://ns.adobe.com/melville/rel/primary",
26          "type": "image/png",
27          "templated": false
28        },
29        "http://ns.adobe.com/melville/rel/path": {
30          "href": "https://cc-api-storage-stage.adobe.io/assets/adobe-libraries/4dc522a7-af3d-4274-986c-bb1f59bb20d0/22fd8c85-eb35-47bc-aa0d-379497e7414e",
31          "rel": "http://ns.adobe.com/melville/rel/path",
32          "type": "image/png",
33          "templated": false
34        },
35        "http://ns.adobe.com/melville/rel/rendition": {
36          "href": "https://cc-api-storage-stage.adobe.io/assets/adobe-libraries/4dc522a7-af3d-4274-986c-bb1f59bb20d0/22fd8c85-eb35-47bc-aa0d-379497e7414e/:rendition{;page,size,version}",
37          "rel": "http://ns.adobe.com/melville/rel/rendition",
38          "templated": true
39        },
40        "http://ns.adobe.com/melville/rel/version-history": {
41          "href": "https://cc-api-storage-stage.adobe.io/assets/adobe-libraries/4dc522a7-af3d-4274-986c-bb1f59bb20d0/22fd8c85-eb35-47bc-aa0d-379497e7414e/:paged_versions{?order,orderby,start,limit,property}",
42          "rel": "http://ns.adobe.com/melville/rel/version-history",
43          "type": "application/vnd.adobe.versions+json",
44          "templated": true
45        },
46        "http://ns.adobe.com/melville/rel/raw": {
47          "href": "https://cc-api-storage-stage.adobe.io/assets/adobe-libraries/4dc522a7-af3d-4274-986c-bb1f59bb20d0/22fd8c85-eb35-47bc-aa0d-379497e7414e{;version}/:raw",
48          "rel": "http://ns.adobe.com/melville/rel/raw",
49          "templated": true
50        }
51      },
52      "etag": "\"9b4fb626b2ea694ceceda1b5caa7463c\"",
53      "storage_href": "https://cc-api-storage-stage.adobe.io/assets/adobe-libraries/4dc522a7-af3d-4274-986c-bb1f59bb20d0/22fd8c85-eb35-47bc-aa0d-379497e7414e",
54      "representation_order": 1,
55      "is_preferred_thumbnail": false,
56      "is_component": true,
57      "is_external_link": false,
58      "state": "unmodified",
59      "name": "7f95b8e0-5f88-4ba0-8404-82ed3ce90ed5"
60    },
61    {
62      "id": "3cebe682-a820-4b47-a267-f124dcde0941",
63      "type": "application/vnd.adobe.font+json",
64      "relationship": "primary",
65      "is_full_size": false,
66      "is_external_link": false,
67      "is_preferred_thumbnail": false,
68      "is_component": false,
69      "is_external_link": false,
70      "library#isExternalLink": false,
71      "font#data": {
72        "foundry": "The FooBaz Corporation",
73        "postScriptName": "TimesNewRomanPS-BoldMT",
74        "name": "Times New Roman Bold",
75        "style": "Bold",
76        "family": "Times New Roman",
77        "typekitFontId": "some_meaningful_uuid"
78      }
79    }
80  ],
81  "assetSubType": "element",
82  "_fc": true,
83  "_links": {
84    "http://ns.adobe.com/melville/rel/primary": {
85      "href": "/api/v1/libraries/urn:aaid:sc:us:efb1969b-fed5-4381-836e-6d7a97a14fbf/elements/9e46e07f-f9c1-4380-b199-754c1f6ffb9c",
86      "rel": "http://ns.adobe.com/melville/rel/primary",
87      "type": "application/json",
88      "templated": false
89    },
90    "http://ns.adobe.com/melville/rel/path": {
91      "href": "/api/v1/libraries/urn:aaid:sc:us:efb1969b-fed5-4381-836e-6d7a97a14fbf/elements/9e46e07f-f9c1-4380-b199-754c1f6ffb9c",
92      "rel": "http://ns.adobe.com/melville/rel/path",
93      "type": "application/json",
94      "templated": false
95    },
96    "http://ns.adobe.com/melville/rel/id": {
97      "href": "/api/v1/libraries/urn:aaid:sc:us:efb1969b-fed5-4381-836e-6d7a97a14fbf/elements/9e46e07f-f9c1-4380-b199-754c1f6ffb9c",
98      "rel": "http://ns.adobe.com/melville/rel/id",
99      "type": "application/json",
100      "templated": false
101    },
102    "http://ns.adobe.com/melville/rel/describedBy": {
103      "href": "/api/v1/libraries/urn:aaid:sc:us:efb1969b-fed5-4381-836e-6d7a97a14fbf/elements/9e46e07f-f9c1-4380-b199-754c1f6ffb9c",
104      "rel": "http://ns.adobe.com/melville/rel/describedBy",
105      "type": "application/json",
106      "templated": false
107    },
108    "http://ns.adobe.com/melville/rel/rendition": {
109      "href": "https://cc-api-storage-stage.adobe.io/assets/adobe-libraries/4dc522a7-af3d-4274-986c-bb1f59bb20d0/22fd8c85-eb35-47bc-aa0d-379497e7414e/:rendition{;size}",
110      "rel": "http://ns.adobe.com/melville/rel/rendition",
111      "templated": true
112    },
113    "http://ns.adobe.com/melville/rel/representations": {
114      "href": "/api/v1/libraries/urn:aaid:sc:us:efb1969b-fed5-4381-836e-6d7a97a14fbf/elements/9e46e07f-f9c1-4380-b199-754c1f6ffb9c?selector=representations",
115      "rel": "http://ns.adobe.com/melville/rel/representations",
116      "type": "application/json",
117      "templated": false
118    }
119  },
120  "parent_id": "urn:aaid:sc:us:efb1969b-fed5-4381-836e-6d7a97a14fbf",
121  "details": {
122    "created": {
123      "userId": "35305C3E5E861DB40A494026@AdobeID",
124      "deviceId": "MY_COOL_DEVICE_ID",
125      "device": "MY_COOL_DEVICE",
126      "app": "MY_COOL_APP"
127    },
128    "lastModified": {
129      "userId": "35305C3E5E861DB40A494026@AdobeID",
130      "deviceId": "MY_COOL_DEVICE_ID",
131      "device": "MY_COOL_DEVICE",
132      "app": "MY_COOL_APP",
133      "time": 1590014039432
134    }
135  }
136}

Multipart Uploads

Uploading an asset that is 5mb or greater requires a different usage pattern than the above. In this case, we will: (1) initiate an upload, (2) split the asset into chunks, (3) upload each chunk separately, (4) finalize the upload, and lastly, (5) create the new element.

... coming soon ...

Ash Ryan ArnwineValerii Naida
Last updated 8/11/2021
Was this helpful?

Community

Support

Adobe Developer

  • Privacy
  • Terms of Use
  • Do not sell or share my personal information
  • AdChoices
Copyright © 2023 Adobe. All rights reserved.