InDesign API Key Concepts

Consider these important concepts when using InDesign APIs.

Adobe Developer Console

Overview

The Adobe Developer Console is an administration interface that enables developers to manage Adobe's APIs and services. To securely access Adobe's APIs, including the InDesign API, your application must authenticate using OAuth 2.0 protocols. This involves obtaining an access token that grants your application permissions to interact with Adobe's services.

You will need:

• An Adobe Developer Console account.

• A project with Firefly API OAuth Server-to-Server credentials set up.

• Add and configure InDesign API Firefly Services to your new project.

• Access to your Client ID and Client Secret from the Developer Console.

Access tokens

You can generate access tokens either directly from the Developer Console UI or programmatically.

Best practices

• Token management: Access tokens are valid for 24 hours. Implement a mechanism to refresh tokens before they expire to maintain uninterrupted access.

• Scope limitation: Request only the scopes necessary for your application's functionality to adhere to the principle of least privilege.

• Secure storage: Store your Client ID, Client Secret, and access tokens securely to prevent unauthorized access.

Pre-signed URLs

What is a pre-signed URL?

A pre-signed URL is a URL that grants temporary access to a specific resource, typically in cloud storage, with predefined permissions and an expiration time. It allows users to upload or download files securely without needing direct access to the storage service's credentials.

While using InDesign APIs, the input and output assets are stored as pre-signed URLs.

Input assets

The platform supports multiple asset types for input. These asset types indicate storage repositories from which the platform can download. You can provide the input asset information within the assets array.

InDesign APIs support the following input assets:

• AWS S3: Use a pre-signed GET/PUT/POST URL.

• Dropbox: Generate temporary upload/download links.

• Azure: Use a Shared Access Signature (SAS) in Azure Storage for GET/PUT/POST operations.

Copy
Copied to your clipboard
"assets" :[
    {
        "source" : {
            "storageType" : "Azure", //Optional
            "url" : "https://xyz-blob.core.windows.net/Template.indt"
        },
        "destination" : "jobasset/template1.indt"
    },
    {
        "source" : {
            "storageType" : "Aws", //Optional
            "url" : "https://s3.eu-west-1.amazonaws/xyz/Template.indt"
        },
        "destination" : "jobasset/template2.indt"
    }
]

In the examples above, you can see that data is divided into source and destination.

The source attribute is where the asset is downloaded from. The destination attribute refers to where the asset would be downloaded to.

Output assets

The platform supports multiple asset types for output. These asset types signify storage repositories to which the platform can upload. You can provide this information in the outputs array within the body of the request.

Copy
Copied to your clipboard
"outputs": [
    {
        "destination" : {
            "type" : "Azure",
            "url" : "https://xyz-blob.core.windows.net/Template.indt"
        },
        "source" : "jobasset/template.indt"
    }
]

Each storage provider may have its own requirements for creating PUT or POST pre-signed URLs. Please follow the documentation from the individual storage provider creating these URLs.

About custom capability bundles

To script a custom capability to use with the Custom Capabilities API, you'll need to prepare a capability bundle, a ZIP file with a predefined structure.

Capability bundle structure

The structure for a simple capability bundle would look like this:

Copy
Copied to your clipboard
capability-folder
|------ manifest.json
|------ capability.js

Capability manifest

The manifest file is a plain JSON file with the following structure:

Copy
Copied to your clipboard
{
    "manifestVersion": "1.0.0",
    "id": "<Unique ID for the capability>",
    "name": "<Name of the capability>",
    "version": "<x.y.z>",
    "host": {
        "app": "indesign",
        "minVersion": "17.0.0",
        "maxVersion": "99.9.9"
    },
    "apiEntryPoints": [
        {
            "type": "capability",
            "path": "capability.js",
            "language": "extendscript"
        }
    ]
}

The apiEntryPoints field

In the manifest file, the apiEntryPoints attribute is an array of EntryPointDefinition objects with the following format:

• Each entry point specifies a capability script or a capability specification.
• There can be only one entry of each type in the array.
• The maximum size of the array is 3.

There's no need to define an entry point if the default values are being used for them.

The capability.js file

The script's author defines the custom attributes and values for a particular endpoint using capability.js files in the capability bundle.

The execution of any script depends on the following attributes:

For examples, see Writing Custom Scripts for the Custom Capability API.

Zipping and updating a capability bundle

When zipping the files, don't place them inside a folder first. Instead, directly select the files and create the ZIP. This way when it's unzipped the files will appear directly instead of appearing inside a folder.

The capability bundle can be updated by incrementing the version in the capability manifest. The updated ZIP bundle can be uploaded using the submission endpoint.

InDesign links support

The InDesign APIs support links to content within the same document or across different documents. This helps keep the assets and the document decoupled.

To handle links, a temporary folder/directory, called the working directory, is created to process a request. All the input assets mentioned in the request are downloaded and kept in the working directory.

Within the working directory, the location of individual assets is governed by the relative path mentioned in the destination attribute. Note that the value mentioned in the destination property must be used to refer to the same asset in the rest of the parameters.

Links can work in two ways:

• Maintain relative paths of assets to the target document. To do this, place the files outside the working directory.

• If you place the linked assets parallel to the target document, the links get resolved, and the assets will be picked.

When documents contain custom links that InDesign does not understand, the custom URLs can be relinked to assets provided in the request.

Relink example

In the example below, the existing URI "customScheme:4c189e2d-315e-4fab-a8c2-45690e44d1f0" in the document "TargetDocument.indd" cannot be interpreted by InDesign. The caller would have provided an input asset with the "destination" attribute as "SomeAsset.png".

In this example the caller is asking the specified URI to be relinked to the new asset, which is present at <Working_Directory>/SomeNewAsset.png.

Copy
Copied to your clipboard
{
    "params": {
        "generalSettings": {
            "links": {
                "replaceLinks": [
                    {
                        "targetDocument": "TargetDocument.indd",
                        "mapping": [
                            {
                                "currentURI": "customScheme:4c189e2d-315e-4fab-a8c2-45690e44d1f0",
                                "newAssetRelativePath": "SomeNewAsset.png"
                            }
                        ]
                    }
                ]
            }
        }
    }
}

Using custom fonts

Custom fonts or user fonts can be provided as a regular asset.

Copy
Copied to your clipboard
{

    "assets":[
        {
            "source": {
                "url":"<YOUR PRE-SIGNED URL>",
                "type":"HTTP_GET"
            },
            "destination" : "Cheese_final.indd"
        },
        {
            "source": {
                "url":"<YOUR PRE-SIGNED URL>",
                "type":"HTTP_GET"
            },
            "destination" : "FontName.otf"
        }
    ]
}

Best practices with fonts

For fonts to be found by default, please place them in the "Document Fonts" folder parallel to the document that uses them.

By keeping the fonts in the "Document Fonts" folder parallel to indivdual documents, you can avoid adding any font directory and get a more optimized performance (see below).

Copy
Copied to your clipboard
{
  "params": {
    "generalSettings": {
      "fonts": {
        "fontsDirectories": []
      }
    }
  }
}

Or, if the fonts are kept in some other folder (for example, fontFolder), please specify the correct font directory:

Copy
Copied to your clipboard
{
    "params": {
        "generalSettings": {
            "fonts": {
                "fontsDirectories": [
                    "fontFolder"
                ]
            }
        }
    }
}

When font directories are added, don't use them with InDesign documents because opening these files will create additional lock files and trigger recalculation of the font resources.

Using webhooks

InDesign APIs events provide job processing details similar to those shown in the status calls of InDesign APIs. However, InDesign API events are more comprehensive.

Please refer to the InDesign APIs Webhooks for a detailed guide on setting up webhooks.