Using Postman and the API Connect 2018 APIs for semi-automated creation and configuration of Consumer Organizations and Applications

APIC 2018 has multiple ways of administration access, the most well-known and used being the web GUI. Another way is using the inbuilt management API’s which is a great option for automation. This guide will focus on using some of those API’s together with Postman to do some basic automated administrative tasks. We’ll be mostly focusing on creation of Consumer (old Developer) Organizations, Applications, Setting groups, and changing credentials.

Using Postman like this only gives us very basic automation, but it can help speed up the process of creating new environments and catalogs. Think if this as the middle ground between spending a lot of time creating a fully functional automatization script and doing everything manually.

API Connect 2018 Administrative API docs

More info about all calls used here can be found in https://apic-api.apiconnect.ibmcloud.com/v2018/.

As with normal API’s you can find example messages, required headers, and schemes here.

Using Postman’s Runner functionality

The core feature used here is Postman’s Collection Runner functionality. It allows us to run the same API request multiple times for different data that is taken from a file. The idea here is that we write a generic API call for something, for example Create_cOrg, that uses data from a CSV file to fill in the specifics.

• Choose the collection containing your generic API calls.
• Select the appropriate postman Environment setting.
• Select the data file that will be used for inserting specific values in your generic call.
• Select the appropriate API to be used with your data.

When inserting a data file, you can check the way your file is interpreted via the Preview button.

For example I used a CSV file here that simply lists all CO’s to be created:

We can now use the cOrg-name variable in our generic API call, and postman will fill that in with the current iteration’s value.

Getting an authorization token

When sending REST calls to APIC2018 you’ll need to provide an auth token. You can get this token by calling POST <BaseURI>/api/token. You’ll need valid user data in the body. Note that the user here is from a specific LDAP group.

The user you provide needs to have access to manage consumer-orgs and apps, since we’ll be modifying these types of objects.

In the response you’ll get a Bearer token that you can use in all your other API calls. You can check the bearer token via jwt.io to see if the user has the correct rights in the scopes section.

Creating a new Consumer Organization

There are 2 main complexities in creating a C-Org via the API.

1. We need an owner URL.
2. It needs a sluggified name

Getting an owner URL

To create new C-Orgs I chose to first create all of them with me as the owner. That way I can make all the configurations before transferring ownership to the real clients.

One way you can get your owner url is via the apic commandline via the apic toolkit.

Login via:

apic login —u YOURUSER -s apinonprd-cloud.com  –realm provider/ur-ldap

Login with your password, after logging in type:

apic users:list -o ProviderOrg -s apinonprd-cloud.com  –user-registry ur-ldap

You will get a list of users and user info. Find your user and copy the URI:

myuser    [state: enabled]   https://apinonprd-cloud.com/api/user-registries/0ed8248-1a6b-4b16-8e8f-1afe9774cc41/864fd286-8d38-44d6-ba0b-46d738a54199/users/5a274305-b4be-4d12-aead-780d1e9e74f4

This is the URI you will use from now on in your Create_cOrg call.

Sluggified names

There are multiple ways you can solve this issue. One simple way is to already add your sluggified name in the data file and just use that instead. However I chose for a dynamic approach using the Pre-Request-Script feature where I put in a custom function for sluggifying text.

This basically just sluggifies the cOrg-name we got from the data file and saves it in a cOrgSlug variable.

The API Call

The API call itself is relatively simple.

POST {{baseUrl}}/consumer-orgs/{{providerOrg}}/{{catalog}}/{{cOrg}}/apps

cOrgSlug is a value set in the PreRequest script. cOrg-title is a value automatically assigned by the Collection Runner.

Making it work via the collection runner

Putting all we’ve learned together, we get the following config in the Collection Runner using the following CSV file:

If everything went correctly you should get:

And if you check in APIC WebGUI

Note : If you got an unauthorized 401, make sure your token did not expire. Refresh token if needed.

Creating a new Application

To create a new application we need 3 values: The APP Name, the APP Title and the certificate that the app will use in PEM format. Note that a certificate is not mandatory.

The Collection Runner process will be the same as the “Create_cOrg” API call. So I will just give you the specifics of the API Call and the Data file.

Note that unlike the “Create_cOrg” API call, we give the sluggified name here as data via the data file. The reason is that for documentation purposes we wrote all the sluggified names in an excel anyway, so exporting it to a csv was trivial and we might as well use the data we already have.

The Data file

The datafile should include the app-title, app-name (sluggified) and certificate (if used). Note that the other values are used for other API calls discussed later.

The API Call

POST {{baseUrl}}/consumer-orgs/{{providerOrg}}/{{catalog}}/{{cOrg}}/apps

As discussed we don’t have a Pre-Request script here, since we got the sluggified name from our data file.

Updating credentials of existing applications

We made our applications and they have their certificates. But their credentials (clientId and clientSecret) are still empty. We want to give them the credentials of our choosing.

Using credentials exported from another version of APIC

When you export applications via the migration toolkit you get the ClientID and hashed clientSecret. To make APIC accept hashed secrets we need to enable a setting via an API call.

First get the current settings of the catalog:
GET {{baseUrl}}/catalogs/<ProviderOrg>/<Catalog>/settings
We get back:

Copy this json in notepad and change the value:
“hash_client_secret”: false to “hash_client_secret”: true

Then we can use this json as a new request to change the settings via:
POST {{baseUrl}}/catalogs/{{providerOrg}}/{{catalog}}/settings
Using json we just modified as request body.

We’ve now enabled hashed secrets for that specific catalog.

Now we can create our API call

PATCH {{baseUrl}}/apps/{{providerOrg}}/{{catalog}}/{{cOrg}}/{{app-name}}/credentials/credential-for-{{app-name}}

Where our values are filled in via our data file in the Collection Runner.

Using completely new credentials

If you don’t have any preexisting credentials you need to use this process is a lot simpler, since we don’t need to enable any settings in the catalog config.

The API call becomes

PATCH {{baseUrl}}/apps/{{providerOrg}}/{{catalog}}/{{cOrg}}/{{app-name}}/credentials/credential-for-{{app-name}}

Written by: Alexander Timmermans

Need some help with API Connect for your organization?