Getting Started with the REST APIs of SAS Customer Intelligence 360
In this post, we’ll introduce the Customer Intelligence 360 REST APIs and demonstrate how to get started using them, including submitting your first API call using Postman.
REST APIs 101
What is a REST API?
The APIs we will discuss here adhere to a set of defined requirements called REST, or Representational State Transfer. REST API calls consist of HTTP requests that can be submitted programmatically in a script, or submitted manually as we will be doing in this example.
RESTful APIs use calls submitted via a URL with one of the primary HTTP methods: Post, Get, Put, Patch, and Delete. When a client submits one of these methods and the associated data to a server, they are making a request.
The server, which in this case is Customer Intelligence 360, issues a response that includes the requested information or an error indicating what went wrong. The response may be formatted as JSON, XML, or an image.
Another characteristic of REST APIs is that all the information required to fulfill the request must be included in the request itself.
Figure 1: a client submits a request with an authentication token and the server provides a corresponding response.
Select any image to see a larger version.
Mobile users: To view the images, select the "Full" version at the bottom of the page.
What are the CI Rest APIs?
Customer Intelligence 360 can be integrated with on-premises and cloud-based data, channels, and services in a variety of ways. One of those ways is by providing REST APIs for managing data, tasks, segments, and other assets.
In this example, we will use the marketing gateway API to request the configuration information for an access point. Other endpoints of this API enable users or programs to download data tables and the agent zip files, inject external events, and more. For a complete list of the CI360 REST APIs and more information on their endpoints and functions, refer to the REST API documentation.
What is Postman, how do I use it? What other tools do I need?
We will be using Postman, a client enabling REST requests to be sent from the desktop to the CI360 gateway.
If you would like to try this example yourself, you can download the desktop client or access the browser version of Postman.
You’ll also need to install python and the python library PyJWT in order to run the script to generate a token to authenticate your request.
Where can I find more information?
For more information on the REST APIs of Customer Intelligence 360, see the developer’s site and documentation, product documentation, and SAS Communities.
Getting started
Authenticating REST requests
Setting up to use the REST APIs is simple, and you will only need to complete the initial steps once or infrequently. Then you can begin submitting REST API calls. These steps are setting up the external gateway, creating API credentials, and setting up authentication.
The REST APIs are secured using bearer token authentication. Different token types can be utilized to access Customer Intelligence 360 from the APIs depending on their security needs.
Requests to the Customer Intelligence 360 APIs can be authenticated in three different ways: a static JWT (JSON Web Token), a temporary JWT, and an access token.
A static JWT does not expire and can be generated programmatically using a tenant ID and a client secret associated with an access point. It is only invalidated if the access point used to create it is deleted or deactivated. This is the authentication method we will use in this example to access the Marketing Gateway API.
For more information on token types and generating and managing tokens for authenticating REST requests, see the token management section of the documentation.
We'll start by creating or utilizing an existing access point. We also need to take note of the external gateway host. These steps are completed in the Customer Intelligence 360 user interface in the general settings.
Figure 2: Under General Settings > External Access > Access Points, you can manage and create access points and their credentials.
I select Access Points under External Access and review my table of access points. At this point, I can either select the New Access Point icon to create a new general access point, or select an existing one from the table. If your environment has a general access point already configured, you can use the same general access point for the general agent, API requests, and other integrations.
I click General Access Point to pull up the access point credentials. I’ll use these credentials along with the external gateway address to customize and authenticate my API request.
Next, I need to create A JWT to be included with the calls for authentication. This can be done in Postman, or in the Customer Intelligence User Interface*.
A JSON Web token is a bearer token that is put in the header of the API request to authenticate the client (POSTMAN or a script on an on-premises machine, etc.) with the CI 360 server.
There are several ways to generate the static JWT, but in this example we will be using a python script that utilizes the PyJWT library. Here is the code:
import base64
import jwt
tenantId = '00001ae00001'
secret = 'MkiasdfasdfsadfsadfsdafsHSF98575'
encodedSecret = base64.b64encode(bytes(secret, 'utf-8'))
token = jwt.encode({'clientID': tenantId}, encodedSecret, algorithm='HS256')
print('\nJWT token: ', token)
I only need to adjust the tenant ID and client secret in this script. I save and run this script in the command line. The result is a JWT, which I note. This JWT will remain active unless I delete the access point used to generate it or replace its credentials.
C:\Users\sasdemo> python generateCIstaticJWT.py
JWT token: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJjbGllbnRJRCI6ImY2NzJjZDI5ODIwMDAxMDdmN2M2MzdmOCJ9.16uHULoaTv7VYhRewbcObqHQ36b9dHD3bZ0qZgY-QRSTUVWXYZDownloading the collection of API calls
Now, we'll download the collection to Postman before adjusting the calls to our specific environment. This is not required to submit the API calls, but it saves time and makes it easier to correctly format the requests because the collection acts as a template.
I begin on developer.sas.com and select CI360, then choose Get Started with APIs. Clicking ‘View the entire set of REST API Documentation’ will take me to the API section of the product documentation.
Figure 3: Landing page shown after selecting SAS Customer Intelligence 360 on developer.sas.com
Instead, I scroll down to the list of APIs and select Marketing Events Gateway. This directs me support.sas.com and additional API-specific documentation, including examples.
Next, I’ll download the collections from this documentation. I click Download next to Download Open API Specification.
Figure 4: After navigating to the Marketing Gateway developer documentation, I click Download to download the collection.
Now, I open postman. I create a new collection by clicking Import, and importing the collection I just downloaded.
Figure 5: Importing the collection from the download file
Modifying the collection for my environment
Now, I’ll modify this collection as needed to submit the calls to my specific tenant. I click the Marketing Gateway API collection in the right side bar, then select Variables on the right.
I edit the base URL of the collection and paste in my external gateway address from the Access Points page in the UI. In this case, it is extapigwservice-training.ci360.sas.com.
Figure 6: Modifying the base url of the collection
The base URL should now match the external gateway address I saw earlier under Access Points in the user interface, with the appended ‘root’ /marketingGateway.
Next, I’ll navigate to the Authorization tab. I select Bearer Token from the Type drop down. I enter the response from the python script I ran earlier.
Figure 7: Provide the JWT as the collection authentication
I click save in the top right to save both of these changes to my collection. Now, the calls in the collection will use the base URL corresponding to my tenant’s external gateway address, and inherit the authentication information I’ve specified here. This saves me the time of supplying the authentication with each call.
Let’s test our REST request
Now, we are ready to test the API configuration by submitting a call to the Marketing Gateway API. I will be submitting a request to query the API/access point configuration.
Under Marketing Gateway API in the left navigation pane, I expand the configuration folder and click the GET request “Get the configuration for the API”.
I review the authorization tab, verifying the call will inherit authorization information from its parent in the form of the bearer token we added earlier.
If desired, I can click the code icon to display the call as a code snippet instead of the form-like view where we enter each field in Postman
Figure 8: After selecting a call from the collection you can verify the authorization header inheritance and view the request as a formatted code snippet.
This is particularly helpful when comparing calls you are testing against the examples in the documentation, many of which are formatted as cURL snippets.
When I am ready to submit the request, I click Send and view the response. I get a 200 response – the standard HTTP response indicating my GET request has been successful. I can review the access point information in the response and toggle between raw and formatted JSON.
Figure 9: Formatted response JSON after a successful request
This example is just a small taste of the functionality available from the Customer Intelligence 360 REST APIs. For example, this post discusses how to use the Marketing Data API to GDPR delete identity data.
For more information on the APIs, their use cases, and additional examples, see the documentation and communities.
Find more articles from SAS Global Enablement and Learning here.
