Quick Start: Make your first API call

Let’s walk through making your first XD Cloud Content API call together.

We'll keep things simple in this tutorial and use the command line tool cURL to make a request call.

At the end of the tutorial, we'll suggest some next steps for going deeper with the XD Cloud Content APIs.

Prerequisites

• Basic knowledge of Command Line Interfaces and APIs
• A text editor to write your code in (like VSCode, Sublime Text, Brackets, Atom, etc)

Development Steps

0. Get a client ID and client secret

Before you start, you'll want to request a client ID and client secret by filling out this form.

If approved, you will be assigned a unique client ID and client secret, which can be used to make API calls.

1. Decide whether your app will access private cloud docs or not

XD cloud documents are either private or public, depending on how the user has chosen to share them. If you are building an integration that requires access to private XD cloud ducments, your app will need an access token which can be obtained through an OAuth integration.

During this OAuth workflow, users will be asked to authorize your app to access private cloud documents.

Note that if your app tries to access a private XD cloud document without an access token, Cloud Content APIs will return the following error:

{
    "error": {
        "message": "Wrong/Missing authorization information"
    }
}

2. Get the document URL

You will need a document URL created from an XD document. In order to create a link, open Adobe XD and follow the steps below.

First, click on the "Share" button at the top right corner and select "Share for Review":

You will be asked to configure some settings. After choosing the right options for you, click on the "Create Link" button:

After creating the link successfully, you will be able to copy the link to the clipboard:

We'll use that link in the next step.

3. Find out what API endpoint can be used for a document URL

Send an OPTIONS call and read the response header to learn what API calls can be made for a particular XD document URL. Refer to the required headers and parameters in the endpoint references page.

curl -I -X OPTIONS -H "x-api-key: YOUR-API-KEY" -H "X-AdobeXD-Link: https://xd.adobe.com/view/21652643-762a-41c6-5cd9-6342060e8aff-5754/" https://xdce.adobe.io/v2/api

This should return a response header like this:

Access-Control-Allow-Headers →Origin, Content-Type, Accept, X-Api-Key, X-AdobeXD-Link, User-Agent
Access-Control-Allow-Methods →OPTIONS
Access-Control-Allow-Origin →*
Access-Control-Expose-Headers →x-request-id, Content-Type, Content-Length, Link
Connection →keep-alive
Content-Length →0
Content-Type →application/json; charset=utf-8
Date →Mon, 14 Oct 2019 20:57:24 GMT
Link →</v2/document/21652643-762a-41c6-5cd9-6342060e8aff-5754>; rel=document
Server →openresty
Strict-Transport-Security →max-age=15552000; includeSubDomains
Vary →Accept-Encoding
X-Content-Type-Options →nosniff
X-DNS-Prefetch-Control →off
X-Download-Options →noopen
X-Frame-Options →SAMEORIGIN
X-Request-Id →gJeLsvCSjgTXhhDEp8uGMa0rnBrNeZXo
X-XSS-Protection →1; mode=block

The value of the Link key is the endpoint you can use to make further API calls. In this example, that value is:

/v2/document/21652643-762a-41c6-5cd9-6342060e8aff-5754

4. Make a GET call to the document endpoint

Now that you've retrieved the exact endpoint, you can make a GET call to the API. Refer to the required headers and parameters in the endpoint references page.

curl -H "x-api-key: YOUR-API-KEY" https://xdce.adobe.io/v2/document/21652643-762a-41c6-5cd9-6342060e8aff-5754

This will return a JSON response that contains various data about the document, including the following and more:

• id
• name
• thumbnail
• publisher
• artboardCount
• artboards
• homeArtboardId
• version
• lastupdated
• history
• assetID
• includesDevelopmentData

You can leverage this response data in your integration as-is. Or, in some cases, you can use the data to dig deeper. We'll look how to do that with the artboards data in the next step.

4. Make a GET call to the artboard endpoint

The response we received above contains the artboards key with an array value of artboard objects. Each artboard object contains a unique id. You can use this value to make a GET call to the artboard endpoint.

Note that you need to chain the artboard URL to the document URL used in the previous step. Refer to the required headers and parameters in the endpoint references page.

curl -H "x-api-key: YOUR-API-KEY" https://xdce.adobe.io/v2/document/21652643-762a-41c6-5cd9-6342060e8aff-5754/artboard/5dec1809-bf44-4e9b-aef5-6e46e8aa18e9

This will return a response that contains various data about a given artboard, including:

• id
• name
• resourceAPI
• thumbnail
• bounds
• viewportBounds
• triggers
• parent

Congratulations on making your first couple of calls to the XD Cloud Content APIs!

Next Steps

Now you're ready to move forward in building you integration with XD Cloud Content APIs.

• Browse the endpoint references
• See working code in our samples