Sunday, May 26, 2019

Access Adobe APIs Using Postman

APIs (Application Programming Interface) facilitate the transfer of information between two systems and are leveraged in a magnitude of industries today ranging from Travel to Retail. Adobe offers open source APIs in its solutions across the Document, Creative and Experience Clouds. Major companies leverage APIs to allow users to do the following:

  • Share content on Social Media (Facebook)
  • Retrieve flight information (Alaska Airlines)
  • Real-time access to item price and availability (Amazon)
  • Access maps using GPS (Google Maps)
  • Tracking information on shipments (FedEx)
  • Server Side Analytics Implementation (Adobe)

In this post, I will cover how to leverage Adobe APIs for Launch by Adobe and Audience Manager but these APIs are also available to use across some other Experience Cloud solutions such as Adobe Analytics and Adobe Target via Adobe I/O. We won't go into the basics of how to create integrations as there's a lot of documentation available on it but we'll cover the steps on how to call the APIs using authentication tokens in Postman. Please note that Audience Manager is not part of Adobe I/O yet and we'll specifically cover REST APIs to work with elements within the AAM UI. Let's jump right in!

Launch By Adobe APIs


The first solution we will cover is Launch where we'll create a property and you can use this format to create , data elements, rules, environments etc. The first step is to go to the Adobe I/O console which shows you all the integrations setup for your experience cloud org. In this case, we've created an integration with Launch APIs using Adobe I/O.


Make sure you either select the Developer role or the Admin role (while creating the integration) in order to create properties. I had chosen Approver as listed in the instructions in our documentation which walks us through how to create an integration but that didn't let me create a Launch property.



The following screen will show you your API credentials which you'll need to access the API and the ones which is required is API Key and Client Secret. We'll also need the Org ID that needs to be sent as an additional attribute in one of the requests we'll make in one of the API calls covered later in this post.


The next step is to generate the JWT (JSON Web Token) which will be used to authenticate and access the Launch APIs. The Private Key is generated as part of the public certificate (CRT file) creation process outlined in the Launch documentation. Please note that during the creation of the certification, an additional file called private.key is generated which contains this information.


The next step is to use the generated JWT to create a Launch token that will be used to access Adobe APIs. 


We need to now copy the generated JWT in Postman to create a new access token (valid for 24 hours) but before that, I want to share with you a tip which my colleague Gil Jimenez shared with me. The tip is to create global variables in Postman to store sensitive values that you'll need to access over and over again. You can do that by clicking on the Environment icon as shown below. The other thing you can do is to save these API calls as collections in the form of separate folders as shown below in the left section.


Generate a Launch Access Token

The next step is to generate an access token using the client_id, client_secret and jwt_token parameters by making a POST request to https://ims-na1.adobelogin.com/ims/exchange/jwt/ as explained here. Note how we're using the global variables to store sensitive information and accessing it in the call. We need copy this access token and store it. In our case, we're storing it in a separate variable calls access-token which is different that the jwt-token we need to create it.


Make a POST Request to Create a Property


We'll now create a new Launch property by making a POST request to https://reactor.adobe.io/companies/:company_id/properties as covered here. We can also create Launch rules, data elements, environments etc using this method. Below is how we can make this call.


Once we press send, we successfully (if everything goes well) create a Launch property as shown below. So using APIs, developers can literally do everything in Launch without  having to login to Launch. These APIs are open source and super powerful!


Make a GET Request for a Property


We'll now cover how make a GET request to https://reactor.adobe.io/properties/:id t
o fetch the details of the Launch property we just created by entering the property ID (starting with PR) which you can get from the response you get when you created the property. We're going to leverage some mandatory attributes defined here as shown below (The {{property}} value stores the property ID). You can use this to get access to a lot of information such as name, creation timestamp, domains etc. We can also fetch the details of data elements, rules and extensions among other things.



Adobe Audience Manager REST APIs


We'll now cover how to make GET and POST requests for AAM using Postman to access REST APIs (centered around the AAM UI) which allow you to perform some basic functions without logging into the AAM UI. Please note that there's another set of APIs called DCS APIs (send data to AAM) which I'll save for a future post.

Generate an AAM Access Token

As I mentioned earlier, the AAM APIs are not yet part of Adobe I/O so in order to access the REST APIs, we need the following credentials to access the APIs:
  • AAM API user name (AAM Admin UI)- Adobe consultant can provide this
  • AAM API password (AAM Admin UI)- Adobe consultant can provide this
  • AAM UI Username (bank.demdex.com login)
  • AAM UI Password (bank.demdex.com login)
Once you have these credentials, we can leverage Postman to get the access token which is only valid for a few minutes. Here we enter the AAM API and password using Basic Auth and send a POST request to https://api.demdex.com/oauth/token


The next step is to enter the AAM UI credentials as shown below to generate the access token that will be used to access additional APIs.





Make a POST Request to Create a Folder


We can access all AAM APIs in the Swagger API portal. The first thing we want to create is a folder by sending a POST call to https://api.demdex.com/v1/folders/traits/ using the Bearer Token auth type as shown below. The folder is "REST API Test" and it will be placed under the root "All Traits" folder.


Once the call goes through successfully, we should see the following message and the folder should show up in the AAM UI immediately.




Make a POST Request to Create a Trait


We'll now create a simple trait by sending a POST request to https://api.demdex.com/v1/traits/. The only additional attributes we're adding is the Folder ID and the Data Source ID which we can get from the AAM UI. The result is the following as shown in the screenshots below.

Please note that the API doesn't have a way to create traits in bulk so you can leverage BAAAM to do so which is a custom solution.



Make a GET Request to Retrieve all Traits


This is the final request in this post to get details about traits but you can retrieve data for segments, destinations, data sources etc. We send a GET request to https://api.demdex.com/v1/traits/ to retrieve all traits within our AAM instance. In our case, we can see that the trait we just created can be accessed using this method and you can export this JSON output and perform additional searches.


So, this was just a small glimpse into what's possible via APIs where we're able to perform the same tasks that we usually do in the Adobe solution specific UIs. This also shows us that almost everything that happens in the UI is driven by APIs so in a way we took a look under the hood of Launch and Audience Manager. Hope you found this post useful.

No comments: