This QuickStart will discuss and demonstrate how to leverage the very popular API platform called Postman with Sigma's REST API.
Postman is an API platform for developers to design, build, test and iterate their APIs. Postman reports having more than 20 million registered users and 75,000 open APIs, which it says constitutes the world's largest public API hub.
Postman offers a tiered pricing model, with a free option that allows for "designing, developing, and testing APIs". We will use the free tier for testing.
Target Audience
Developers who are interested in using the API methods provided by Sigma to automate operations or use functionality embedded in their own commercial applications.
Prerequisites
- A computer with a current browser. It does not matter which browser you want to use.
- Access to your Sigma environment. A Sigma trial environment is acceptable and preferred.
- Postman installed. Web or Desktop version will work.
- If have not already, you can sign up for a Sigma Trial here:
What You'll Learn
We will install Postman, add the Sigma API to a new Postman API, configure authorization and test a few API methods.
What You'll Build
When done, we will have a ready for use Sigma API in Postman we can use whenever we want to evaluate methods and the returns.
Postman offers a native web experience as well as a Desktop version. Either is fine; we will use the web version for simplicity. For this QuickStart there is not much difference in the web/desktop versions of Postman.
If you already have a Postman account you can use that or otherwise you will have to sign up for an account (free tier for our use case):
After signing into Postman, click into Workspaces:
There are several workflows available in Postman and we will use this one:
Create a new Workspace called Sigma:
Give it the name, description and set the visibility to Personal for now. Click Create Workspace:
We want to create a new API and there are several ways to do that. In our case, we will use the Import option as we will grab the latest Sigma API release from our public Swagger page.
Click the Collections icon and click then the Import icon:
Next we will need to get the link (URL) to the latest Sigma API. Open another browser tab.
Browse to this Sigma Help page and click the link as shown below:
Click the button View OpenAPI Spec (New Tab1):
Copy the URL from the address bar:
Paste the address into the Postman UI (in the link section) as shown and click Import:
When done, it API will appear as a new Collection. It may be helpful to rename the collection if you have more than one copy.
Expand the Sigma Public API to see the available methods as below:
In order to be able to use any API in the web version of Postman, you need to install the Postman Agent on your local machine.
The Postman Desktop Agent is a micro-application that runs locally on your desktop. It enables you to bypass the limitations that exist in the browser by allowing API requests to originate in the browser, but be routed through your local machine and network. The Postman Desktop Agent overcomes the Cross Object Resource Sharing (CORS) limitations of browsers and acts as your agent for making API requests from the Postman web app.
Download and install the Postman Desktop Agent. You will need to unzip to perform the installation.
In preparation for using the API we need to use Sigma to generate a new API Token.
Log onto Sigma (as Administrator). Navigate to Administration, APIs & Embed Secrets
Click the Create New button:
Select API Token, give it a name and description. Notice that we have also created a Service Account user for automation purposes; this is a best practice. Since we are just testing, you can choose any Admin user you prefer. Click Create.
Copy the ClientID and Secret from the popup and save them to a secure location. We will use them later. Close the popup:
Postman variables enable us to store and reuse values in Postman. By storing a value as a variable, we can reference it throughout our API Collection (API).
At the top level node of the API, click the Variables tab and add the following variables and corresponding values.
Leave the "initial value" blank where we have not provided any default value.
If unsure where Sigma is hosted, this is found in Sigma > Administration > Account:
The baseURL for each cloud is available here
Modify the tokenBaseURL as needed for the cloud provider.
VARIABLES: / INITIAL VALUES:
baseUrl / https://aws-api.sigmacomputing.com
tokenBaseURL / https://aws-api.sigmacomputing.com/v2/auth/token
clientID / {use the clientID we created earlier that you saved off to a text file}
secret / {use the secret we created earlier that you saved off to a text file}
token
expires_in
Click on the Authorization tab and configure the value for Token to use our new variable using the format shown:
Save the changes and CLOSE THIS TAB.
Sigma's API requires that we authenticate prior to use. We will be using variables that we setup in the last step to request a token. This token is also know as a Bearer or JSON web token (JWT).
We are going to add a POST method to automate authenticating, retrieving a token and persisting it in a variable.
New POST Method
Click v2 > Add request:
This opens a new request which we will rename to Authenticate.
Change the method to POST and Authorization to No Auth:
Under the Body tab, all the following values (two are environment variables and one is static):
Be sure to select the x-www-form-urlencoded message type.
grant_type / client_credentials
client_id / {{clientID}}
client_secret / {{secret}}
Provide the request url using the curly-brace format to leverage our environment variable for tokenBaseURL:
Now that we are configured, click Save and Send to try our request. If all is correct, we will get a Status 200 OK and an access token:
Persist Token Response
One more step is required so that the values in the response are stored into our variables we setup earlier.
On the Authenticate > Test tab, paste the following code:
let response=pm.response.json();
console.log(response);
pm.collectionVariables.set("token", response['access_token']);
pm.collectionVariables.set("token_type", response['token_type']);
pm.collectionVariables.set("expires_in", response['refresh_token']);
Save this change.
Now that we are all setup, let's run a test to prove that our variables are being saved after we get a valid response.
Earlier, we ran Authenticate and got a valid response so we want to clear that out first.
Go back to the top level node > variables tab and click to Reset all:
This reset clears the three values related to the token. Current value will now be blank (Initial was already blank).
SAVE AND CLOSE THIS TAB
Now return to the Authenticate tab, run the method and get another token.
Then return to the top level node > Variables tab and we see that new values have appeared in the Current value fields for the three token related items:
We are now ready to proceed to using other API methods.
Let's use the API to Get a list of available Connections.
Expand the API to show the method under V2, connections, Returns a list of available connections and click to select open it in a new tab.
We need to uncheck the two checkboxes (item #4 in the screenshot) for Params as we just want to return all the connections. These two optional parameters allow us to filter the return but we won't do that at this point. Click Send:
In the Body section, is the return from the API in JSON. For example, our first connection is described this way:
{
"organizationId": "adbfe832-733a-4c83-b64d-bdbf6ae8d2cb",
"connectionId": "10eed7b7-4a10-4c40-802b-4ba91287d5fe",
"isSample": true,
"lastActiveAt": "2023-01-25T14:44:50.000Z",
"name": "Sigma Sample Database",
"type": "snowflake",
"useOauth": false,
"createdBy": "1IDcJykBMeDwcot0MXWaw5R1RUwI7",
"updatedBy": "yRn1UFV8ngVWBM1Hgrl51h7MS8uow",
"createdAt": "2022-09-22T18:41:47.151Z",
"updatedAt": "2023-01-25T14:44:50.695Z",
"isArchived": false
},
Even if you are only using a Sigma Trial and have not created a connection yourself, there will be one shown. This is Sigma's sample database and is included on all Sigma instances by default. Your ID values will be different of course.
The API provides methods to add/update/delete a Sigma instance using POST messages. We will demonstrate this by creating a new Snowflake connection.
This is a demonstration only as we will show duplicating an existing connection.
We will use the following code to configure a POST message to create a new connection in Sigma.
You can get this code and more information here.
The values shown below are for example only:
{
"name": "Snowflake via API POST",
"details": {
"type": "snowflake",
"account": "tester",
"host": "testing.snowtest.com",
"password": "<password>",
"role": "A_ROLE",
"user": "THE_DEV",
"warehouse": "TEST_WAREHOUSE",
}
}
Configure the method "Creates a new connection" as shown and click Send (we have masked some values of course). A successful result is similar to what is shown in item #6:
Logging into the Sigma portal we can see we have a new connection:
We created a Postman account, created API token secrets in Sigma, imported the Sigma API to a new Postman API, configured authorization and tested GET and POST methods.
Additional Resource Links
Be sure to check out all the latest developments at Sigma's First Friday Feature page!
Sigma Help Center Home
Sigma Community
Sigma Blog
