Getting started with Adobe Experience Platform APIs

Adobe Experience Platform is developed under an “API first” philosophy. Using Platform APIs, you can programmatically perform basic CRUD (Create, Read, Update, Delete) operations against data, such as configuring computed attributes, accessing data/entities, exporting data, deleting unneeded data or batches, and more.

The APIs for each Experience Platform service all share the same set of authentication headers and use similar syntaxes for their CRUD operations. The following guide outlines the necessary steps for getting started with Platform APIs.

Authentication and headers

In order to successfully make calls to Platform endpoints, you are required to complete the authentication tutorial. Completing the authentication tutorial provides the values for each of the required headers in Experience Platform API calls, as shown below:

Sandbox header

All resources in Experience Platform are isolated to specific virtual sandboxes. Requests to Platform APIs require a header that specifies the name of the sandbox the operation will take place in:

For more information on sandboxes in Platform, see the sandbox overview documentation.

Content-type header

All requests with a payload in the request body (such as POST, PUT, and PATCH calls) must include a Content-Type header. Accepted values are specific to each API endpoint. If a specific Content-Type value is needed for an endpoint, its value will be shown in the example API requests provided by the API guides for individual Platform services.

Experience Platform API fundamentals

Adobe Experience Platform APIs employ several underlying technologies and syntaxes that are important to understand in order to effectively manage Platform resources.

To learn more about the underlying API technologies Platform utilizes, including example JSON schema objects, visit the Experience Platform API fundamentals guide.

Postman collections for Experience Platform APIs

Postman is a collaboration platform for API development that allows you to set up environments with preset variables, share API collections, streamline CRUD requests, and more. Most Platform API services have Postman collections which can be used to assist with making API calls.

To learn more about Postman including how to set up an environment, a list of available collections, and how to import collections, visit the Platform Postman documentation.

Reading sample API calls sample-api

Request formats vary depending on the Platform API being used. The best way to learn how to structure your API calls is by following along with the examples provided in the documentation for the particular Platform service you are using.

The documentation for Experience Platform shows example API calls in two different ways. First, the call is presented in its API format, a template representation showing only the operation (GET, POST, PUT, PATCH, DELETE) and the endpoint being used (for example, /global/classes). Some templates also show the location of variables to help illustrate how a call should be formulated, such as GET /{VARIABLE}/classes/{ANOTHER_VARIABLE}.

The calls are then shown as cURL commands in a Request, which includes the necessary headers and full “base path” needed to successfully interact with the API. The base path should be pre-pended to all endpoints. For example, the aforementioned /global/classes endpoint becomes https://platform.adobe.io/data/foundation/schemaregistry/global/classes. You will see the API format / request pattern throughout the documentation, and are expected to use the complete path shown in the example request when making your own calls to Platform APIs.

Example API request

The following is an example API request that demonstrates the format you will encounter in the documentation.

API format

The API format shows the operation (GET) and the endpoint being used. Variables are indicated by curly braces (in this case, {CONTAINER_ID}).

GET /{CONTAINER_ID}/classes

Request

In this example request, the variables from the API format are given actual values in the request path. Additionally, all required headers are shown as either sample header values or variables where sensitive information (such as security tokens and access IDs) should be included.

curl -X GET \
  https://platform.adobe.io/data/foundation/schemaregistry/global/classes \
  -H 'Accept: application/vnd.adobe.xed-id+json' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'x-api-key: {API_KEY}' \
  -H 'x-gw-ims-org-id: {ORG_ID}' \
  -H 'x-sandbox-name: {SANDBOX_NAME}'

Response

The response illustrates what you would expect to receive following a successful call to the API, based on the request that was sent. Occasionally the response is truncated for space, meaning that you may see more information or additional information to that which is displayed in the sample.

{
    "results": [
        {
            "title": "XDM ExperienceEvent",
            "$id": "https://ns.adobe.com/xdm/context/experienceevent",
            "meta:altId": "_xdm.context.experienceevent",
            "version": "1"
        },
        {
            "title": "XDM Individual Profile",
            "$id": "https://ns.adobe.com/xdm/context/profile",
            "meta:altId": "_xdm.context.profile",
            "version": "1"
        }
    ],
    "_links": {}
}

Error messages

The Platform troubleshooting guide provides a list of errors that you may encounter when using any Experience Platform service.

For troubleshooting guides on individual Platform services, see the service troubleshooting directory.

For more information on specific endpoints in Platform APIs, including required headers and request bodies, please see the Platform API guides.

Platform API guides api-guides

For more information on specific endpoints and operations available for each service, please see the API reference documentation on Adobe I/O.

Next steps

This document introduced the required headers, available guides, and provided an example API call. Now that you have the required header values needed to make API calls on Adobe Experience Platform, select an API endpoint you wish to explore from the Platform API guides table.

For answers to frequently asked questions, refer to the Platform troubleshooting guide.

To set up a Postman environment and explore the available Postman collections, refer to the Platform Postman guide.