Set up Developer Console and Postman
In this lesson, you will set up a project in the Adobe Developer Console and download Postman collections so you can start using Platform APIs.
In order to complete the API exercises in this tutorial, download the Postman app for your operating system. While not required in order to use Experience Platform APIs, Postman makes API workflows easier, and Adobe Experience Platform provides dozens of Postman collections to help you execute API calls and learn how they operate. The rest of this tutorial assumes some working knowledge of Postman. For assistance, please reference the Postman documentation .
Platform is built API-first. While interface options also exist for all major tasks, you will likely want to use the Platform API at some point. For example to ingest data, move items around between sandboxes, automate routine tasks or to use new Platform features before the UI has been built.
Data Architects and Data Engineers may need to use Platform API outside of this tutorial.
In the Configure Permissions lesson, you set up all the access controls you need to complete this lesson, specifically:
- Permission item Sandboxes > Luma Tutorial
- Developer-role access to the Luma Tutorial Platform product profile
Set up Adobe Developer Console
- Create a folder on your local machine named Luma Tutorial Assets . This folder will be used to save files used in the tutorial
- Open the Adobe Developer Console
- Log in and confirm that you are in the correct Org
- Click button Create New Project in Quick Start menu.
- In the newly created project, click the Add to Project button and then select API
- Filter the list by clicking Adobe Experience Platform
- In list of available APIs, select Experience Platform API and click Next .
- For authentication from external systems like Postman, we require a public/private key pair. To generate a new key pair select Option 1 and press the Generate keypair button
- Once the keys are ready, you may be prompted to download the keys onto your local machine. Save the keys packaged in config.zip to the folder Luma Tutorial Assets . We will need them in the next exercise.
- After the key is generated, the public key will automatically be added to your project as shown in the screenshot. Click the Next button.
- Select the Luma Tutorial Platform product profile and click the Save Configured API button
- Now your Developer Console project has been created!
- In the Try it out section of the page, click Download for Postman and then click Service Account (JWT) to download the Postman environment json file. Save the service.postman_environment.json in your Luma Tutorial Assets folder.System Administrators of your organization would be able to see the project as an "Integration" in the product profile in the Admin Console
You might have noticed that the project was assigned a number, e.g. "Project 12":
- Click on the project number in the breadcrumb
- Click the Edit Project button
- Change the Project Title to Luma Tutorial API Project (add your name to the end, if multiple people from your company are taking this tutorial)
- Click the Save button
Set up Postman
- Download and install Postman
- Open Postman and import the downloaded json environment file, service.postman_environment.json
- In Postman, select your environment in the top-right dropdown and click the eye icon to view the environment variables. You should see that the ACCESS_TOKEN, PRIVATE_KEY, and JWT_TOKEN variables are blank:
Update the Environment Name
Since the exported name of the environment from Developer Console is randomly generated, let's quickly give it a more descriptive name so you don't confuse environments later on when you start working on your real Platform implementation
- With the environment variables screen still open, click the Edit on the top-right
- Update the Environment Name to Luma Tutorial
- Leave Manage Environments modal open in edit mode, as we will be editing it further in the next step
Add the Private Key
Now it's time to add the PRIVATE_KEY value to the Postman environment
- Extract the downloaded config.zip file which was generated in the previous exercise while creating the Developer Console Project. This will have two files:
- Open the private.key file in a text editor and copy all the content available.
- In Postman, on the Manage Environments > Edit modal which is still open from the last exercise, paste copied values in front of PRIVATE_KEY in the Initial Value and Current Value columns.
- Click the Update button to save your PRIVATE_KEY and the updated environment name.
Add the JWT and Access Tokens
Adobe provides a rich set of Postman collections to help you explore Experience Platform's API. These collections are located in the GitHub repo Adobe Experience Platform Postman Samples . You should bookmark this repo as you will be using this numerous times throughout this tutorial and later as you implement Experience Platform for your own company.
The first collection works with the Adobe Identity Management Service (IMS) APIs. It is a convenient way to populate the JWT_TOKEN and ACCESS_TOKEN from within Postman intended for non-production use cases such as completing this tutorial in your sandbox. Alternatively, the JWT Token can be generated within the Adobe Developer Console, but since it expires regularly, using this collection will allow you to refresh it without needing to revisit the Adobe Developer Console again while completing this tutorial.
To generate the tokens:
- Download the Developer Console Access Token Generation collection to your Luma Tutorial Assets folder
- Import the collection into Postman
- Select the request IMS: JWT Generate + Auth via User Token and click Send
- The JWT_TOKEN and ACCESS_TOKEN will auto-populate in the environment variables of Postman.
Add the Sandbox Name and Tenant ID
The SANDBOX_NAME and TENANT_ID and CONTAINER_ID variables are not provided in the environment export from the Adobe Developer Console so we will add them manually:
- In Postman, open the Environment Variables modal
- Click the Edit link to the right of the environment name
- In the Add new variable field , enter SANDBOX_NAME
- Into both value fields, enter luma-tutorial , the name we gave to our sandbox in the previous lesson. If you used a different name for your sandbox, eg. luma-tutorial-ignatiusjreilly, make sure to use that value.
- In the Add new variable field , enter TENANT_ID
- Switch to your web browser and look up your company's tenant id by going to Experience Platform's interface and extracting the portion of the URL after the @ sign . For example, my tenant id is techmarketingdemos but yours will be something different:
- Copy this value and return to the Postman Manage Environments screen
- Paste your tenant id into both value fields
- In the Add new variable field , enter CONTAINER_ID
- Enter global into both value fieldsCONTAINER_ID is a field whose value we will change several times during the tutorial. When global is used the API will interact with Adobe-provided elements in your Platform account. When tenant is used, the API will interact with your own custom elements.
- Click the Update button to save the variables
You can now close the Manage Environments modal.
Make a Platform API Call
Now let's confirm that we've configured everything correctly by making an API call.
Open the other group of Experience Platform Postman collections in Github, the experience-platform-postman-samples . There are a number of collections on this page, related to various Platform features.
We will download collections as we need them for this tutorial. This Github repository will be extremely useful to you after this tutorial as you begin to implement Platform for your company, so I strongly recommend you bookmark it.
Now, let's make our first API call:
- Download the Schema Registry API collection to your Luma Tutorial Assets folder
- Import it into Postman
- Open Schema Registry API > Classes > List all classes in the specified container
- Look at the Params and Headers tabs and note how these include some of the environment variables we entered earlier.
- Click in the Headers > Accept value field and change it to application/vnd.adobe.xed-id+json . The Schema Registry API require one of these specified Accept header values which provide different formats in the response.
- Click Send button to make your first Platform API call!
Hopefully you got a successful 200 OK response containing a list of the available standard XDM classes in your sandbox, as pictured below.
If your call was not successful, take a moment to debug using the error response details of the API call and review the steps above. If you get really stuck, please request help in the Community Forum or use the link in the right side of this page to "Log an issue".