Application REST API

The primary functions of the Application REST APIs are creating, updating, and deleting applications. Application Categories (referred to as "tags" in this API, not to be confused with Component Labels) can be added.

The currently available API includes:

GET - Used to retrieve information, such as a list of organizations, their internal IDs, and their tags.
POST - Used to create applications.
PUT - Used to update applications.
DELETE - Used to delete applications.

Warning

The following REST API actions were deprecated in IQ Server Release 70 and removed in IQ Server Release 156. Use Authorization Configuration REST API.

GET - Used for retrieving roles and mapping those roles to an application.
PUT - Used for authorization configuration for applications (i.e. mapping users or groups to roles).

We will provide both the API, as well as an example using the HTTP client cURL. Additionally, to help demonstrate the use of the APIs, we’ve approached this in a step-by-step manner that will start with gathering the necessary information to create an application and set permissions for the new application.

Tip

If you already have an application and wish to make an update, you can jump to the final step now.

Step 1 - Get the Organization ID

In order to create an application, it must have a parent organization, which means that you must have already created at least one organization in IQ Server.

To retrieve an organization ID for an existing organization, we must start with our GET API call…

GET /api/v2/organizations

and find the organization ID. Additionally, any tags available to be applied to the application will be provided. To follow along using cURL, enter the following command:

curl -u admin:admin123 -X GET 'http://localhost:8070/api/v2/organizations'

This will produce a list of your organizations and associated information in a JSON format. Here is an example of what might be returned.

{
    "organizations": [
        {
            "id": "36d7e629462a4038b581488c347959bc",
            "name": "My Organization",
            "tags": [ ]
        },
        {
            "id": "f48b5344fa204a4c88df96b2d455d521",
            "name": "My Organization 2",
            "tags": [
                {
                    "id": "cd8fd2f4f289445b8975092e7d3045ba",
                    "name": "Distributed",
                    "description": "Applications that are provided for consumption outside the company",
                    "color": "yellow"
                },
                {
                    "id": "004d789684834f7c889c8b186a5ff24b",
                    "name": "Hosted",
                    "description": "Applications that are hosted such as services or software as a service.",
                    "color": "grey"
                },
                {
                    "id": "da9e09887c754157a2113831ae7e99ac",
                    "name": "Internal",
                    "description": "Applications that are used only by your employees",
                    "color": "green"
                }
            ]
        }
    ]
}

Item	Description
id	This is the internal id for the organization.
name	This is the name of the organization, and is visible in the IQ Server GUI.
tags	Tags are the internal name for Application Categories that represent identifying characteristics of an application. Tags should be created at the organization level and applied to applications. Policies can be scoped to specific Application Categories (tags) to target a specific subset of applications.
id (tags)	the internal id for the tag. This will be used when creating the application.
name (tags)	the name of the Application Category, which is visible in the IQ Server GUI.
description (tags)	each tag is required to have a description. This description provides information related to the type of application it should be applied to. In many cases, you will have more than one organization, as does our example.

Step 2 - Create an Application

To create an application, you need several pieces of information. As we’ve already mentioned, you will need the organization ID, but you will also need:

Item	Description
publicId (application ID)	This is the application ID for the application. In the IQ Server GUI this is represented by the "Application" field. It must be unique.
name (application name)	This is the name of the application. In the IQ Server GUI this corresponds to the "Application Name" field. It must be unique.
contactUserName (application contact)	In the IQ Server GUI, this corresponds to the contact field for the application. The value entered here should represent the user name. If you are using LDAP and have configured it to work with the IQ Server, that user name can be used here.
tagId (internal tag ID)	The 'tagId' is the internal identifier of the Application Category that should be applied to the application. see Step 1 to get available Application Categories from the organization. Use the Application Categories API to manage the available categories.

Note

The application contact and tags are optional, but it is generally recommended to include them.

We’ll be using the POST API call…

POST /api/v2/applications

and appending the information mentioned above into a JSON-formatted body. Here is an example of the body that’s been formatted for easier review:

{
    "publicId": "MyApplicationID",
    "name": "MyFirstApplication",
    "organizationId": "f48b5344fa204a4c88df96b2d455d521",
    "contactUserName": "AppContact",
    "applicationTags": [
        {
            "tagId": "cd8fd2f4f289445b8975092e7d3045ba"
        }
    ]
}

Putting this all together, and using our cURL example, you should enter the following command:

curl -u admin:admin123 -X POST -H "Content-Type: application/json" -d '{"publicId": "MyApplicationID","name": "MyFirstApplication","organizationId":"f48b5344fa204a4c88df96b2d455d521","contactUserName":"AppContact","applicationTags": [{"tagId":"cd8fd2f4f289445b8975092e7d3045ba"}]}' 'http://localhost:8070/api/v2/applications'

If your application creation was successful, the system will respond with the following:

{
    "id": "4bb67dcfc86344e3a483832f8c496419",
    "publicId": "MyApplicationID",
    "name": "MyFirstApplication",
    "organizationId": "f48b5344fa204a4c88df96b2d455d521",
    "contactUserName": "AppContact",
    "applicationTags": [
        {
            "id": "9beee80c6fc148dfa51e8b0359ee4d4e",
            "tagId": "cd8fd2f4f289445b8975092e7d3045ba",
            "applicationId": "4bb67dcfc86344e3a483832f8c496419"
        }
    ]
}

Note

Be sure to make note of the "applicationId". This is the internal application ID that will be used in the next steps when finding roles and mapping a user to them.

Step 3 - Find the Currently Available Roles

Warning

This API was deprecated in IQ Server Release 70 and removed in IQ Server Release 156. Use Role REST API instead.

Before mapping any roles, it’s a good idea to take a look at all the available roles for applications. This can be done using a simple GET:

GET /api/v2/applications/roles

This returns all the available roles for all applications:

{
    "roles": [
        {
            "id": "1da70fae1fd54d6cb7999871ebdb9a36",
            "name": "Developer",
            "description": "Allows to evaluate policies."
        },
        {
            "id": "1cddabf7fdaa47d6833454af10e0a3ef",
            "name": "Owner",
            "description": "Allows to manage policies."
        }
    ]
}

Item	Description
id	This is the internal ID for the role. There is no corresponding field in the IQ Server GUI.
name	This is the name of the role, which is exactly the same as the Role Name displayed in the IQ Server GUI. As we mentioned, there are two role names in the example above Developer and Owner.
description	This provides a description of the level of access the role grants.

As you may notice, there are two roles available for applications at this time. Before proceeding to the next step, take note of the roleId (in this example we will be adding an owner). This will be needed for mapping a user to the specific role.

Step 4 - Map Users to Roles

Warning

This API was deprecated in IQ Server Release 70 and removed in IQ Server Release 156. Use Authorization Configuration REST API instead.

To map users to roles, we’ll need the id (application ID) from our successful application creation, the roleId for the role returned above that you will be mapping a user to, and the following information:

Item	Description
type	The type of user, which at this time, can only be either USER or GROUP.
userOrGroupName	This is the username for the user you want to add to the role. If you are using LDAP and have configured it to work with the IQ Server, the LDAP user or group name can be used here.

For this step, we’ll be using the following PUT API call…

PUT /api/v2/applications/{applicationInternalId}/roleMembers

with an appended JSON-formatted body. Here is an example of the body that’s been formatted for easier review:

{
    "memberMappings": [
        {
            "roleId": "1cddabf7fdaa47d6833454af10e0a3ef",
            "members": [
                {
                    "type": "USER",
                    "userOrGroupName": "user-owner"
                }
            ]
        }
    ]
}

Putting this altogether, and using our cURL example, you should enter the following command:

curl -u admin:admin123 -X PUT -H "Content-Type: application/json" -d '{"memberMappings": [{"roleId": "1da70fae1fd54d6cb7999871ebdb9a36","members": [{"type": "USER","userOrGroupName": "user-b"}]}]}' 'http://localhost:8070/api/v2/applications/4bb67dcfc86344e3a483832f8c496419/roleMembers'

As before, standard HTTP response codes will be returned.

Note

You can map multiple roles in a single PUT.

Step 5 - Update Application Information

This final step isn’t a requirement to complete an application, but it will be necessary for any application you want to update.

Before updating the application, you will need the id for the application. If you haven’t recorded this, you can obtain it by using the publicId . To retrieve the information for the application use the following GET API call.

GET /api/v2/applications?publicId={YourPublicId}

Note

All applications can always be returned by omitting the reference to the public id.

Using the cURL command, it would look like this:

curl -u admin:admin123 -X GET 'http://localhost:8070/api/v2/applications?publicId=MyApplicationID'

If you like, you can also return multiple applications by appending additional &publicId={SomeOtherPublicId} to the command above.

Placing your application’s publicId where {YourPublicId} is, the following information will be returned (unique to your application). This has been formatted for readability:

{
    "applications": [
        {
            "id": "4bb67dcfc86344e3a483832f8c496419",
            "publicId": "MyApplicationID",
            "name": "MySecondApplication",
            "organizationId": "bb41817bd3e2403a8a52fe8bcd8fe25a",
            "contactUserName": "NewAppContact",
            "applicationTags": [
                {
                    "id": "9beee80c6fc148dfa51e8b0359ee4d4e",
                    "tagId": "cfea8fa79df64283bd64e5b6b624ba48",
                    "applicationId": "4bb67dcfc86344e3a483832f8c496419"
                }
            ]
        }
    ]
}

From the information returned above, make note of the following primary identifiers:

"id"
"organizationId"

The application information that can be edited can include any or all of the following:

"publicId" - If you change an application publicId, remember to update your integration tools to use the new value.
"name"
"contactUserName"
"applicationTags" (tagID)

Editing limitations:

You cannot move an application to a different organization by editing the "organizationId". To move an application to a different organization see Moving an Application to a Different Organization.
If you are looking to update the role mapping for the application follow the instructions from Step 4.

Now, you should be ready to apply your changes. Before we move on to the command, let’s take a look at a sample body for the attached JSON file:

{
    "id": "4bb67dcfc86344e3a483832f8c496419",
    "publicId": "MyApplicationID",
    "name": "MySecondApplication",
    "organizationId": "bb41817bd3e2403a8a52fe8bcd8fe25a",
    "contactUserName": "NewAppContact",
    "applicationTags": [
        {
            "tagId": "cfea8fa79df64283bd64e5b6b624ba48"
        }
    ]
}

Using cURL enter the following command:

curl -u admin:admin123 -X PUT -H "Content-Type: application/json" -d '{"id":"4bb67dcfc86344e3a483832f8c496419","publicId":"MyApplicationID","name":"MySecondApplication","organizationId":"bb41817bd3e2403a8a52fe8bcd8fe25a","contactUserName":"NewAppContact","applicationTags":[{"tagId":"cfea8fa79df64283bd64e5b6b624ba48"}]}' 'http://localhost:8070/api/v2/applications/4bb67dcfc86344e3a483832f8c496419'

If your update is successful, you will see something similar to the formatted JSON file below.

{
    "id": "4bb67dcfc86344e3a483832f8c496419",
    "publicId": "MyApplicationID",
    "name": "MySecondApplication",
    "organizationId": "bb41817bd3e2403a8a52fe8bcd8fe25a",
    "contactUserName": "NewAppContact",
    "applicationTags": [
        {
            "id": "9beee80c6fc148dfa51e8b0359ee4d4e",
            "tagId": "cfea8fa79df64283bd64e5b6b624ba48",
            "applicationId": "4bb67dcfc86344e3a483832f8c496419"
        }
    ]
}

Moving an Application to a Different Organization

An application can be moved from one organization to another one using the request:

POST /api/v2/applications/{applicationInternalId}/move/organization/{organizationId}

The following is an example request using the cURL tool:

curl -u admin:admin123 -X POST http://localhost:8070/api/v2/applications/4bb67dcfc86344e3a483832f8c496419/move/organization/bb41817bd3e2403a8a52fe8bcd8fe25a

The possible responses are as follows:

If the application is successfully moved to the target organization, status code 200 will be returned with an empty body.
Moving an application to a different organization can be successful albeit with warnings. In this case, status code 200 is returned with a body containing the warnings as follows:

{
  "warnings": [
    "Some policy waivers (1 in total) that were previously inherited no longer apply in the new parent organization.",
    "Some component labels (2 in total) that were previously inherited no longer exist in the new parent organization.",
    "Some license overrides (3 in total) that were previously inherited no longer exist in the new parent organization."
  ]
}

Moving an application to an organization can fail due to conflicts between the organizations the application is moved between. In this case status code 409 is returned with errors as follows:

{
  "errors": [
    "The application category 'Internal' from the organization 'Source-Organization' has no counterpart in the new parent organization.",
    "The policy 'Internal-Policy' from the organization 'Source-Organization' has no counterpart in the new parent organization."
  ]
}

If either an application with the provided "applicationInternalId" or an organization with the submitted "organizationId" is not found, this request yields status code 404.
Trying to move an application to its own organization yields status code 400.

Getting All Applications

All applications can be retrieved using the request

GET /api/v2/applications

The following is an example request using the cURL tool:

curl -u admin:admin123 http://localhost:8070/api/v2/applications

which returns all of the applications the user has permission to access

Here is an example of what might be returned.

{
        "applications": [
                {
                        "id": "e1db2d3f4ccf40a38f193183bffdb7e5",
                        "publicId": "app1",
                        "name": "app1",
                        "organizationId": "8162c39152974035b8d66df12f5abe7d",
                        "contactUserName": null,
                        "applicationTags": []
                },
                {
                        "id": "714342759d5d45a28e6b30866b1e244c",
                        "publicId": "app2",
                        "name": "app2",
                        "organizationId": "8162c39152974035b8d66df12f5abe7d",
                        "contactUserName": null,
                        "applicationTags": []
                },
        {
                        "id": "47951e63ddd742868484dee8630767bc",
                        "publicId": "app3",
                        "name": "app3",
                        "organizationId": "3e9d988f6727420ea445b02fbeaf73e9",
                        "contactUserName": null,
                        "applicationTags": [
              {
                "id": "feaf2c2e33854216bd47f62d9d5371a8",
                "tagId": "131765d40bee47fb9be5bc60d7b52cce",
                "applicationId": "47951e63ddd742868484dee8630767bc"
              }
             ]
                }
    ]
}

The result can also be filtered by specifying application public ids as optional query parameters e.g.

curl -u admin:admin123 http://localhost:8070/api/v2/applications?publicId=app1&publicId=app2

in this case would give

{
        "applications": [
                {
                        "id": "e1db2d3f4ccf40a38f193183bffdb7e5",
                        "publicId": "app1",
                        "name": "app1",
                        "organizationId": "8162c39152974035b8d66df12f5abe7d",
                        "contactUserName": null,
                        "applicationTags": []
                },
                {
                        "id": "714342759d5d45a28e6b30866b1e244c",
                        "publicId": "app2",
                        "name": "app2",
                        "organizationId": "8162c39152974035b8d66df12f5abe7d",
                        "contactUserName": null,
                        "applicationTags": []
                }
    ]
}

The details of the applied application tags (also called application categories) can be directly included in the response using the optional query parameter includeCategories e.g.

curl -u admin:admin123 http://localhost:8070/api/v2/applications?includeCategories=true&publicId=app3

would give a result such as

{
        "applications": [
        {
                        "id": "47951e63ddd742868484dee8630767bc",
                        "publicId": "app3",
                        "name": "app3",
                        "organizationId": "3e9d988f6727420ea445b02fbeaf73e9",
                        "contactUserName": null,
                        "categories": [
                                {
                                        "id": "131765d40bee47fb9be5bc60d7b52cce",
                                        "name": "Distributed",
                                        "description": "Applications that are provided for consumption outside the company",
                                        "organizationId": "ROOT_ORGANIZATION_ID",
                                        "color": "yellow"
                                }
                        ]
                }
    ]
}

Getting Applications for a given Organization

The applications for an organization can be retrieved using the request

GET /api/v2/applications/organization/{organizationId}

The following is an example request using the cURL tool:

curl -u admin:admin123 http://localhost:8070/api/v2/applications/organization/8162c39152974035b8d66df12f5abe7d

which returns all of the applications for the organization with the id matching the given "organizationId".

Here is an example of what might be returned.

{
        "applications": [
                {
                        "id": "e1db2d3f4ccf40a38f193183bffdb7e5",
                        "publicId": "app1",
                        "name": "app1",
                        "organizationId": "8162c39152974035b8d66df12f5abe7d",
                        "contactUserName": null,
                        "applicationTags": []
                },
                {
                        "id": "714342759d5d45a28e6b30866b1e244c",
                        "publicId": "app2",
                        "name": "app2",
                        "organizationId": "8162c39152974035b8d66df12f5abe7d",
                        "contactUserName": null,
                        "applicationTags": []
                }
        ]
}

Deleting an Application

In case you wish to delete an application permanently, the Application REST APIs offer the ability to do so.

Warning

Deleting an application is a destructive action that will permanently remove an application and all data associated with it. Ensure first that you are deleting the correct application and that deleting the application will not adversely affect any integrations that depend on the presence of the application.

Before deleting the application, you will need the id for the application. See updating an application for more information on how to obtain the application id using the application publicId.

The following DELETE API call is available for deleting an application…

DELETE /api/v2/applications/{applicationInternalId}

Using cURL:

curl -u admin:admin123 -X DELETE 'http://localhost:8070/api/v2/applications/4bb67dcfc86344e3a483832f8c496419'

Standard HTTP status codes will be returned in response to a request to delete an application.

Application REST API

Step 1 - Get the Organization ID

Step 2 - Create an Application

Step 3 - Find the Currently Available Roles

Step 4 - Map Users to Roles

Step 5 - Update Application Information

Moving an Application to a Different Organization

Getting All Applications

Getting Applications for a given Organization

Deleting an Application

Search results