Documentation Nexus IQ Server 1.30

Our documentation site has moved. For the most current version, please see http://help.sonatype.com

24.4. Application REST APIs (v2)

The primary functions of the Application REST APIs are creating, updating, and deleting applications. In addition to this, tags can be added and users / groups mapped to roles (permissions) for the application.

The currently available APIs include:

  • GET - used to retrieve information, such as a list of organizations, their internal IDs, and their tags. This is also used for retrieving roles and mapping those roles to an application.
  • POST - used to create applications.
  • PUT - used for mapping roles to the application, as well as making any necessary changes to modifiable application properties (i.e. name, tags, or contact).
  • DELETE - used to delete applications.

As mentioned in the introduction we will provide both the API, as well as an example using the HTTP client cURL. Additionally, to help demonstrate use of the APIs, we’ve approached this in a step-by-step manner that will start with gathering the necessary information to create and set permissions for an 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. Thus, 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"
                }
            ]
        }
    ]
}
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 represent identifying characteristic for an application. Tags are created at the organization level, and then applied to applications. Policies can then select which tags, and in turn applications, the policy will be evaluated against.

id (tags)
the internal id for the tag. This will be used when creating the application.
name (tags)
the name of the tag, 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:

"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)
As mentioned previously, a tag applied to an application will ensure it is evaluated by any policies that have selected the corresponding tag. The tag ID is returned as part of the organization information.
[Tip]

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"
        }
    ]
}
[Tip]

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. 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."
        }
    ]
}
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. 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:

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.

[Tip]

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}
[Tip]

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:

  • "id"
  • "organizationId"

The information for an application that can be updated, follows the same rules as editing an application via the IQ Server GUI. In addition, you will also need any information you will be editing, which can include any or all of the following:

  • "publicId" (see Important note below)
  • "name"
  • "contactUserName"
  • "applicationTags" (tagID)
[Note]

If you are looking to update the role mapping for the application, simply 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"
        }
    ]
}
[Important]

If you change an application PublicId, remember to update your integration tools to use the new value.

24.4.1. Deleting an Application

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

[Important]

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.