Using Postman to interact with CluedIn API

#cluedin #postman 

CluedIn provides a powerful set of REST and GraphQL APIs. You can use them to ingest data to CluedIn, export data from CluedIn, migrate configuration, etc. As CluedIn is a web application with web UI (client) and API (server), you can do API anything you do via UI.

Everything we will do in this article can be done in any programming language, command-line tools like curl and wget, UI apps like Insomnia or Nightingale, and many others. However, we will use Postman, which is probably the most popular tool for working with APIs.

So, let's spinup a CluedIn instance, open Postman, and begin.

Environment setup

First, we need a CluedIn instance, of course. I have mine at: https://foobar.172.167.52.102.sslip.io/.

CluedIn

If we look at this URL, the subdomain foobar is a so-called "organization name" — you need to know it because technically, you can have multiple "organizations" configured on the same CluedIn instance so users, settings and data from one organization are isolated from another.

The 172.167.52.102.sslip.io part is the main domain of your CluedIn instance that you automatically get when you install CluedIn from Azure Marketplace. (of course, you can configure it to your domain, like mdm.contoso.com)

Now, in Postman, you can create your collection or import the one that I use daily: https://github.com/romaklimenko/cluedin/blob/main/postman/CluedIn.postman_collection.json.

In the next step, let's create a new Environment that will keep the domain and credentials configuration. If you use the template from here: https://github.com/romaklimenko/cluedin/blob/main/postman/CluedIn-%20Home.postman_environment.json, you only need to change a few things:

Postman Environment
  • domain — in my case, it's 172.167.52.102.sslip.io.
  • org_name — organization name, foobar in my case.
  • protocol — must be https if you don't run CluedIn in Docker on your local machine.
  • org_name — foobar in my case.
  • user_email and password — obviously, the email and the password. Some APIs require an access token generated for a user account, but some can work with API tokens you can generate in UI. For the last, you can skip email and password configuration.

Finally, the environment contains some predefined URLs:

  • org_url: {{protocol}}://{{org_name}}.{{domain}} - becomes https://foobar.172.167.52.102.sslip.io - we will reuse this URL to build every CluedIn API URL we need.
  • auth_url: {{org_url}}/auth - transforms to https://foobar.172.167.52.102.sslip.io/auth - used to login with email and password, to create users and so on.
  • api_url: {{org_url}}/api/api - transforms to https://foobar.172.167.52.102.sslip.io/api/api - where the most APIs live.
  • graphql_api_url: {{api_url}}/graphql - https://foobar.172.167.52.102.sslip.io/api/api/graphql the GraphQL endpoint you can use to export data from CluedIn. This endpoint works with an API token you can generate in CluedIn UI.
  • graphql_url: {{org_url}}/graphql - https://foobar.172.167.52.102.sslip.io/graphql - the GraphQL endpoint used for UI operations. This endpoint does not work with API tokens - you must use your user's access token.

Get a token

We have the Postman environment; let's try to "log in" with Postman, i.e., call the API to get the user's access token.

To do so, call the "Get a Token" endpoint:

Get a Token

Congratulations! The request is successful. And if you check the environment now, you will find a few new variables added automatically:

Postman Environment
  • access_token — the JWT token to access CluedIn API.
  • refresh_token — the token you can use to refresh the access token.
  • org_id — a special identifier of the token's context used in some calls, so you don't have to get it separately.

Call CluedIn APIs

Now you can call CluedIn APIs. For example, try calling "Get Schema" to get the full list of CluedIn Vocabulary keys and their mappings:

Get CluedIn Vocabulary Keys

Conclusion

To summarize and give a few recommendations:

  • Everything you can do via CluedIn UI, you can automate by calling APIs.
  • To explore how an API request is sent from UI, use the Network tab in your browser and an extension like GraphQL Network Ispector.
  • CluedIn Documentation Portal is updated regularly — there is a lot of useful information there.