The primary function of the Application REST APIs is the creation and update of applications. In addition to this, tags can be added and users / groups mapped to roles (permissions) for the application.
The currently available APIs include:
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.
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" } ] } ] }
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.
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:
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" } ] }
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." } ] }
Developer
and Owner
.
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:
USER
or GROUP
.
For this step, we’ll be using the following PUT API call…
PUT /api/v2/applications/"id"/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.
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}
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:
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:
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" } ] }
Terms of Service Privacy Policy
Copyright ©
2008-present, Sonatype Inc. All rights reserved. Includes the
third-party code listed here. Sonatype and Sonatype Nexus are trademarks
of Sonatype, Inc. Apache Maven and Maven are trademarks of the Apache
Software Foundation. M2Eclipse is a trademark of the Eclipse Foundation.
All other trademarks are the property of their respective owners.
Sonatype Headquarters - 8161
Maple Lawn Blvd #250, Fulton, MD 20759
Tysons Office - 8251 Greensboro Drive #610, McLean, VA
22102
Australia Office - 5 Martin Place, Level 14, Sydney 2000, NSW, Australia