Skip to end of metadata
Go to start of metadata

Overview

Mission Control exposes a rich REST API to allow fully automated management of Artifactory instances under your control.

Version

Deprecated

 This version of Mission Control REST API has been deprecated. We strongly recommend updating your scripts to the latest version. For details, please refer to Mission Control REST API.

Authentication

All Mission Control REST API endpoints require authentication using user/password.

Exception

The System Health Check endpoint does not require authentication.

Error Handling

Mission Control REST API returns error responses in different formats depending on where the error occurred.

Top Level Errors

Top level errors are returned if the request cannot be executed, and have the following format:

{
	"errors" : [
		{
			"message" : <message>,   // a descriptive error message string
			"type" : <type>			// The error category
		}
	]
}

For example:

{
  "errors": [
    {
      "message": "selected script has wrong type: REPOSITORY",
      "type": "Template processing"
    }
  ]
}
Page Contents

Instance Errors

Instance errors are returned for API endpoints that act on instances, such as Create UserCreate User Group or Update Instance and others.

{
  "data": [
    {
      "success": "false",				// "false" indicates an error occurred
      "message": <message>,				// A descriptive error message string
      "instanceName": <instance name>	// The instance on which the error occurred
    }
  ]
}

For example:

{
  "data": [
    {
      "success": true,									//The action on this instance succeeded
      "instanceName": "localhost:8091/artifactory"

    },
    {
      "success": false,									//The action on this instance failed
      "message": "Connection refused",
      "instanceName": "localhost:8081/artifactory"
    }
  ]
}

Repository Errors

Repository errors are returned for API endpoints that act on repositories, such as Update Repository and others.

{
  "data": [
    {
      "success": "false",				// "false" indicates an error occurred
      "message": <message>,				// A descriptive error message string
      "instanceName": <instance name>,	// The instance on which the error occurred
      "repositoryKey": "maven-local"	// The repository on which the error occurred	
    }
  ]
}

For example:

{
  "data": [
    {
      "success": true,									// This operation succeeded
      "instanceName": "localhost:8091/artifactory",
      "repositoryKey": "maven-local"
    },
    {
      "success": false,									// This operation failed
      "message": "Connection refused",
      "instanceName": "localhost:8081/artifactory",
      "repositoryKey": "maven-local"
    }
  ]
}

Working with User Inputs 

Mission control configuration scripts offer the flexibility of letting you provide input just before the script is applied. When working with the Mission Control UI, the User Input screen allows you to enter all user input values required for the scripts you are about to apply.

When working with the REST API, another mechanism is provided that allows you to fully automate your management of Artifactory instances using Script Mappings.

For a detailsonhowtowork with script mappings and user input with the Mission Control REST API, please refer to Working with User Input.

Mandatory Fields

For all endpoints, mandatory input fields are indicated by a plus sign (+).

REST Resources

The following sections provide a comprehensive list of resources exposed by the Mission Control REST API.

SCRIPT MAPPINGS

Get Script List

Description: Gets the list of instance and repository configuration scripts available on Mission Control
Since: 1.0
Security: Requires an admin user
Usage: GET /api/v1/scripts
Consumes: None
Produces: application/json

{
	"data": [	
	{
		"name" : "string",						// The script name
		"description" : "string",				// The script description
		"target" : "INSTANCE" | "REPOSITORY"  	// Specifies whether this is an instance or repository scripts
	}
	]
}

Example:

GET /api/v1/scripts
{
  	"data": [
			 {
				"name" : "QA Property Sets",	
				"description" : "Applies property sets used by QA",
				"target" : "INSTANCE"
			 },
			 {
				"name" : "LDAP Dev",	
				"description" : "Applies development group LDAP settings",
				"target" : "INSTANCE"
			 },		
			...
			 {
				"name" : "Docker Local",
				"description" : "Creates a local Docker repo called docker-local",
				"target" : "REPOSITORY"
				
			 },
			 {
				"name" : "Replicate releases-local",	
				"description" : "Replicates releases-local repository to a target repo",
				"target" : "REPOSITORY"	
			 },
		  ]	
}

List User Inputs

Description: Gets the list of Artifactory user inputs needed for scripts that are being applied
Since: 
1.0 
Security: 
Requires an admin user
Usage: 
POST /api/v1/userInputs
Consumes: 
application/json

{
+	"scriptMappings" : [ {    //An array of scriptMapping objects 
+		"instanceName" : <instance name>,			// The instance on which you want to apply a script
        "repositoryKey" : <string>, // The repository on which you want to apply the script
                                    // Mandatory if the operationType is UPDATE_REPOSITORY.
                                    // *** Not applicable and should be omitted *** if the operationType is CREATE_REPOSITORY or UPDATE_INSTANCE
		"scriptNames" : [<script name>, <script name>, ...]	 //The names of the scripts you want to apply		
		}	
	]
	"operationType":	 "CREATE_REPOSITORY" | "UPDATE_REPOSITORY" | "UPDATE_INSTANCE" //The type of operation you want to perform in the subsequent call with the user inputs returned
}

Produces: application/json

{
	"data": 
		[ 
			{ 
				"success" : true, 
				"instanceName" : "localhost:8091/artifactory", 
				"repositoryKey" : "maven-local", 	// The repository on which the script was applied
				                                    // Only present if operationType was UPDATE_REPOSITORY.
				"scriptUserInputs" : [
					{
						"multiple" : "boolean",	// Whether this user input item can take multiple values
						"type" : "STRING" | "BOOLEAN" | "INTEGER" | "INSTANCE" | "REPOSITORY", // The type of this user input item
						"value" : "object",		// A default value for this user input item
						"description" : "string", // A description for this user input item
						"name" : "string",		// A logical name for this user input item
						"id" : "string"		// The identifier of this user input item. This is the identifier that must be used in any subsequent API call
					} ]		
 			}
		]
}

INSTANCES

Get Instances

Description: Gets the list of Artifactory instances managed by Mission Control
Since: 1.0 
Security: Requires an admin user
Usage: GET /api/v1/instances
Consumes: None
Produces:
 application/json

{
  	"data": [
			 {
				"url" : <string>,		//The Artifactory instance URL
				"name" : <string>		//The Artifactory instance name
			 }
			]
}

Example:

GET /api/v1/instances
{
  	"data": [
			 {
				"url":"http://10.0.0.110:8080/artifactory",
				"name":"QA"		
			 },
			 {
				"url":"http://10.0.0.120:8080/artifactory",
				"name":"DEV"		
			 }
			]
}

Update Instance

Description: Updates an array of Artifactory instances with corresponding scripts
Since: 1.0
Security: Requires an admin user
Usage: PUT /api/v1/instances
Consumes: application/json

{
	"scriptMappings": [
			  {
+				"instanceName" : <string>,	// The name of the instance being updated 
				"scriptNames" : [<string>],	// Scripts to apply		
				"scriptUserInputs":			// The user inputs needed for the applied scripts (if any)
					{
 						<userInputId> : <user input value> //  string or object, depending on the user input type
					}
			  }
	]
}

Produces: application/json

Example: Update Artifactory instances "DEV" and "QA" by applying script "LDAP Settings" to each of them. When applying this script, I need to provide a name for the LDAP settings with user input

PUT /api/v1/instances
{
	"scriptMappings" : [
			  {
      			"instanceName":"DEV",
      			"scriptNames":["LDAP Settings"],
				"scriptUserInputs" : 
						{
							"InstanceMapper#0#name#0" : "DEV-LDAP"	
						}
         	  },
    		  {
	      		"instanceName":"QA",
      			"scriptNames":["LDAP Settings"],
				"scriptUserInputs" : 
						{
							"InstanceMapper#0#name#0" : "QA-LDAP"	
						}
    		  }
		    ]
}

REPOSITORIES

Get Repositories

Description: Gets a list of repositories in an Artifactory instance
Since: 1.0
Security: Requires an admin user
Usage: GET /api/v1/instances/{instance name}/repositories
Consumes: None
Produces: application/json
Example: Get a list of repositories in instance cluster-126-10100.

GET /api/v1/instances/cluster-126-10100/repositories
 
Response:
{
  "data": [
    {
      "repositoryKey": "ext-release-local",
      "description": "Local repository for third party libraries",
      "type": "local",
      "packageType": "maven"
    },
    {
      "repositoryKey": "ext-snapshot-local",
      "description": "Local repository for third party snapshots",
      "type": "local",
      "packageType": "maven"
    },
   
...
 
    {
      "repositoryKey": "plugins-snapshot",
      "type": "virtual",
      "packageType": "maven"
    },
    {
      "repositoryKey": "remote-repos",
      "type": "virtual",
      "packageType": "maven"
    }
  ]
} 

Create Repository

Description: Creates a repository in a set of Artifactory instances. For more information, please refer to Configuring Repositories in the Artifactory documentation.
Since: 1.0
Security: Requires an admin user
Usage: POST /api/v1/repositories
Consumes: application/json

{
	"scriptMappings":[
			  {
+				"instanceName" : <string>,   	//Artifactory instance on which to create the repository
				"scriptNames" : [<string>],  	//scripts to apply when creating the repository				
				"scriptUserInputs": 		//user inputs required for the scripts applied. One of these should refer to the repositoryKey field
				{
					<userInputId> : <user input value> //  userInputId obtained from previous call to userInputs
				}
			  }
			]
}

Produces: application/json
Example: Use a script called create-docker-local to create a local Docker registry. From a previous call to userInputs we found that we need to supply the repository key as user input in the RepositoryMapper#0#repositoryKey#0 parameter. We are creating the same repository on instances DEV-EAST and QA-EAST.

POST /api/v1/repositories
{
	"scriptMappings":[
			  {
				"instanceName" : "DEV-EAST",
				"scriptNames" : ["create-docker-local"],  	
				"scriptUserInputs": 		
				{
						"RepositoryMapper#0#repositoryKey#0" : "dev-docker-local"
				}
			  },
			  {
				"instanceName" : "QA-EAST",
				"scriptNames" : ["create-docker-local"],  	
				"scriptUserInputs": 		
				{	
						"RepositoryMapper#0#repositoryKey#0" : "qa-docker-local"
				}
			  }
			]
}

Update Repository

Description: Updates a repository in a set of Artifactory instances. For more information, please refer to Configuring Repositories in the Artifactory documentation.
Since: 1.0
Security: Requires an admin user
Usage:PUT /api/v1/repositories
Consumes: application/json

{
	"scriptMappings" :[
			  {
+				"instanceName" : <string>,   //Artifactory instance on which to update the repository
+				"repositoryKey" : <string>,  //Name of the repository to update
				"scriptNames" :[<string>],  //scripts to apply when  updating the repository. The user inputs provided be provided in an order that corresponds to the script names.
				"scriptUserInputs" :  //user inputs required for the scripts applied
				{
					<userInputId> : <user input value> //  string or object, depending on the user input type
				}
			  }
			]
}


Produces: application/json
Example: Use a script called update-local to update the description field on local repository dev-docker-local on DEV-EAST, andlocalrepositoryqa-docker-local on QA-EAST.

POST /api/v1/repositories
{
	"scriptMappings":[
			  {
				"instanceName" : "DEV-EAST",
				"repositoryKey" : "dev-docker-local",
				"scriptNames" : ["update-local"],  	
				"scriptUserInputs": 		
				{
						"RepositoryMapper#0#description#0" : "Local Docker registry for dev"
				}
			  },
			  {
				"instanceName" : "QA-EAST",
				"repositoryKey" : "qa-docker-local",
				"scriptNames" : ["update-local"],  	
				"scriptUserInputs": 		
				{
						"RepositoryMapper#0#description#0" : "Local Docker registry for qa"
				}
			  }
			]
}



SECURITY

Create User

Description: Creates a user on a set of Artifactory instances. For more information, please refer to Managing Users in the Artifactory documentation.
Since: 1.0
Security: Requires an admin user
Usage: POST /api/v1/users
Consumes: application/json

{
+	"instanceNames":[<string>],					// The Artifactory instances on which to create this user
+	"user" :
	{
+		"name" : <string>,							// The user's name
+		"email" : <string>,								// The user's email
+		"password" : <string>,						// The user's password in clear-text
		"admin" : <boolean>,								// If true, this is an admin user
		"profileUpdatable" : <boolean>,    			// If true, this user can update their profile
		"internalPasswordDisabled" : <boolean>   	// If true, this user cannot use internal password when external authentication (such as LDAP) is enabled.
	}
}


Produces: application/json
Example: Create user "johns" with the below parameters on Artifactory instances  "cluster-121-10100" and "cluster-126-10100"

POST /api/v1/users
{
    "instanceNames": ["cluster-121-10100","cluster-126-10100"],
    "user": {
        "name": "johns",
        "email": "johns@somewhere.com",
        "password": "12345678",
        "admin": false,
        "profileUpdatable": false,
        "internalPasswordDisabled":   false
    }
}

Update User

Description: Updates a user on a set of Artifactory instances. For more information, please refer to Managing Users in the Artifactory documentation.
Since: 1.0
Security: Requires an admin user
Usage: PUT /api/v1/users/{username}
Consumes: application/json

{
+	"instanceNames":[<string>],			// The Artifactory instances on which to create this user
+	user:
	{
+		"email" : <string>,				// The user's email
		"password" : <string>,			// The user's password in clear-text
		"admin" : <boolean>, // If true, this is an admin user 
		"profileUpdatable" : <boolean>,  // If true, this user can update their profile
		"internalPasswordDisabled" : <boolean>   // If true, this user cannot use internal password when external authentication (such as LDAP) is enabled.
	}
}

Produces: application/json

Example: Update the email address of user "johns" Artifactory instances  "cluster-121-10100" and "cluster-126-10100"

PUT /api/v1/users/johns
{
    "instanceNames": ["cluster-121-10100","cluster-126-10100"],
    "user": {
        "email": "johns@newdomain.com"
    }
}

Create User Group

Description: Creates a user group on a set of Artifactory instances. For more information please refer to Creating and Editing Groups in the Artifactory documentation. 
Since: 1.0
Security: Requires an admin user
Usage: POST /api/v1/userGroups
Consumes: application/json

{
+	"instanceNames":[<string>],			// The Artifactory instances on which to create this user
+	"userGroup" : {
+		"name" : <string>,			// The group's name
		"description" : <string>,  // A description for this group
		"autoJoin" : <boolean>,    // If true, new users created in the target Artifactory instance will automatically be added to this group
		"users" : [<string>]      // The list of users (by user name) to include in this group
	}
}

Produces: application/json
Example: Creates a user group called "developers" along with the specified parameters on Artifactory instances "cluster-121-10100" and "cluster-126-10100"

POST /api/v1/userGroups
{
	"instanceNames": ["cluster-121-10100","cluster-126-10100"],			// The Artifactory instances on which to create this group
    "userGroup": {
        "name": "developers",
        "description": "The developer group",
        "autoJoin": false,
        "users": ["johns", "ronaldm"]
    }
}

Update User Group

Description: Updates a user group on a set of Artifactory instances. For more information please refer to Creating and Editing Groups in the Artifactory documentation. 
Since: 1.0
Security: Requires an admin user
Usage: PUT /api/v1/userGroups/{group name}
Consumes: application/json

{
+	"instanceNames":[<string>],			// The Artifactory instances on which to update this group
+	"userGroup:{
		"users" : [<string>],      // The new list of users (by user name) to include in this group. This list replaces the current set of users in the group
		"autoJoin" : <boolean>,    // If true, new users created in the target Artifactory instance will automatically be added to this group
		"description" : <string>  // A description for this group
	}
}

Produces: application/json
Example: Update the "developer" user group with the specified parameters on Artifactory instances "cluster-121-10100" and "cluster-126-10100"

PUT /api/v1/userGroups/developers
{
    "instanceNames": ["cluster-121-10100","cluster-126-10100"],
    "userGroup": {
        "description": "The developer group",
        "autoJoin": false,
        "users": ["janes", "colonels"]
    }
}

Create Permission Target

Description: Creates a permission target on a set of Artifactory instances. For more information, please refer to Managing Permissions in the Artifactory documentation.
Since: 1.0
Security: Requires an admin user
Usage: POST /api/v1/permissionTargets
Consumes: application/json

{
+	"instanceNames" : [<string>],			// The Artifactory instances to which this permission target should be applied
+	"permissionTarget" : {	
+		"name" : <string>,					// A name for this permission target
+		"repositories" : [<string>],		// The repositories to which this permission target applies
		"anyRemote" : <boolean>,			// If true, applies to any remote repository
		"anyLocal" : <boolean>,			// If true, applies to any local repository
		"excludesPattern" : <string>,		// Excludes pattern to filter out certain repositories
		"includesPattern" : <string>,		// Includes pattern to filter in certain repositories
		"principals": 	// The principles to which this permission target should be applied
		{
			"users" :
			{
				<userName> : [{permission}] // The users and corresponding permissions they are given where m=admin; d=delete; w=deploy; n=annotate; r=read
			},
			"groups" :
			{
				<groupName> : [{permission}] // The groups and corresponding permissions they are given where m=admin; d=delete; w=deploy; n=annotate; r=read
			}
		}
	}
}

Produces: application/json
Example:   Creates a permission target called "releasers" on repository "ext-release-local" for users "johns" and "colonels" and groups "developers" and "itmanagers" (each with corresponding permissions) on Artifactory instances "cluster-121-10100" and "cluster-126-10100".

POST /api/v1/permissionTargets
{
    "instanceNames": ["cluster-121-10100","cluster-126-10100"],
    "permissionTarget" : {
        "name" : "releasers",
        "includesPattern" : "**",
        "excludesPattern" : "",
        "anyLocal" : true,
        "anyRemote" : false,
        "repositories" : ["ext-release-local"],
       "principals": {
        "users" : {
          "johns": ["r","w","m"],
          "colonels" : ["d","w","n","r"]
        },
        "groups" : {
          "developers" : ["m","r","n"],
          "itmanagers" : ["r"]
        }
     }   
    }
}

Update Permission Target

Description: Updates a permission target on a set of Artifactory instances. Any permissions previously set for users or groups are replaced with the specified permissions. For more information, please refer to Managing Permissions in the Artifactory documentation.
Since: 1.0
Security: Requires an admin user
Usage: PUT /api/v1/permissionTargets/{permission target name}
Consumes: application/json

{
+	"instanceNames" : [<string>],			// The Artifactory instances to which this permission target should be applied
+	"permissionTarget" :
	{
+		"repositories" : [<string>],		// The repositories to which this permission target applies
		"anyRemote" : <boolean>,			// If true, applies to any remote repository
		"anyLocal" : <boolean>,			// If true, applies to any local repository
		"excludesPattern" : <string>,		// Excludes pattern to filter out certain repositories
		"includesPattern" : <string>,		// Includes pattern to filter in certain repositories
		"principals" : 	// The principles to which this permission target should be applied
		{
			"users" :
			{
				<userName> : [{permission}] // The users and corresponding permissions they are given where m=admin; d=delete; w=deploy; n=annotate; r=read
			},
			"groups" :
			{
				<groupName> : [{permission}] // The groups and corresponding permissions they are given where m=admin; d=delete; w=deploy; n=annotate; r=read
			}
		}
		
	}
}

Produces: application/json
Example:   Updates the permission target called "releasers" on repository "ext-release-local" for "itmanagers" awarding them full permissions on any remote repository on Artifactory instances "cluster-121-10100" and "cluster-126-10100".

PUT /api/v1/permissionTargets/releasers
{
    "instanceNames": ["cluster-121-10100","cluster-126-10100"],
    "permissionTarget" : {
        "anyRemote" : true,
        "repositories" : ["ext-release-local"],
       "principals": {
        "groups" : {
          "itmanagers" : ["d","w","n","r"]
        }
     }   
    }
}

SYSTEM

System Health Check

Description: Simple ping to Mission Control to see if it is running.
Since: 1.0
Security: None
Usage: GET /api/v1/ping
Consumes: None
Produces: application/json 

{
	"data" : true 
}



  • No labels