Nav

Runtime Manager API

logo cloud disabled logo hybrid active logo server active logo pcf active

The Runtime Manager REST API provides a way for you to programmatically access much of the functionality offered by the Runtime Manager.

This document details the process to follow for deploying Mule applications via the Runtime Manager REST API. The process described is to be implemented as a task in the Continuous Integration pipeline. The task could be implemented as either a shell (e.g. Microsoft PowerShell, Bash, etc.) script or a Jenkins/Maven Plugin written in Java.

For a more complete reference of all the operations that are supported through the API, see:

Please note that a Mule Maven Plugin also exists that provides exactly the same capabilities. Therefore this document is to be used as an alternative for those who cannot or do not want to use the plugin.

Also note that a CloudHub API also exists that allows you to deploy applications to CloudHub. This document is intended for deploying to your own servers that are on-premises or to other cloud servers.

Data Format

All resources or methods that return or accept a type use the JSON as the data format. As an example, here’s data you might receive, in JSON format, in response to a request to get an application:


         
      
1
2
3
4
5
6
7
8
9
10
11
12
13
{
  "access_token": {
    "access_token": "4c091a7c-5d28-43af-b949-214251e5472c",
    "expires_in": 3543
  },
  "user": {
    "id": "c4cf05d7-74c4-4178-b013-d976c57b4c8a",
    "organization": {
      "name": "MyOrganisation",
      "id": "8d05377b-132c-43ef-994b-4cd8143e6c79"
    }
  }
}

Workflow Overview

The workflow explained below can be carried out by various different means depending on your preference, but the steps remain the same. It first logs your user into the Anypoint Platform, obtains information about the servers/server groups/clusters that are registered on that account, and then deploys an application to it. It interfaces with the APIs for the MuleSoft Anypoint Platform Core Services and Runtime Manager.

The workflow must receive the following input parameters:

  • Username - The Anypoint Platform account username

  • Password - Password for the Anypoint Platform username

  • Environment - The deployment environment (Dev, Test, Prod, etc.)

  • Target Name - The name of the target onto which deploy the application

  • Target Type - The type of target (Server, Cluster or ServerGroup)

  • Artifact Name - Name of the Mule application to deploy

  • File - The binary file of the Mule application to deploy

The workflow executes the following API calls in sequence:

  1. Call Login on the Core Services API with valid Anypoint Platform Username and Password to obtain the 'access_token' and 'token_type' to use in all the subsequent calls.

  2. Call Accounts on the Core Services API to retrieve the organization 'id'.

    This step is not mandatory, as the organization identifier can be passed as a local parameter to the task due to its static nature.
  3. Call Environments on the Core Services API, passing the organization 'id' retrieved in the previous step and choosing the correct environment 'id' based on the relevant environment name (e.g. Dev, Test, Production, etc.).

  4. Call either the Servers, Clusters or Server Groups on the Runtime Manager API, passing the server /cluster / server group name, as well as the retrieved organization 'id' and environment 'id'. This returns all of the data about this server /cluster / server group, including the 'targetId'.

  5. Call Applications on the Runtime Manager API, passing the organization’s 'id' and the environment’s 'id', to retrieve the application’s 'id' and the rest of its data.

  6. Call Applications on the Runtime Manager API, passing the organization’s 'id', the environment’s 'id', 'artifactName', 'targetId' (retrieved in the in step 4), the Mule application .zip 'file' to deploy and optionally the application 'id'. See Deploying to CloudHub for details on how the deployment procedure is through the UI.

workflow

1- Login (Core Services API)

API Endpoint https://anypoint.mulesoft.com/accounts/login

Method

POST

Headers

Content-Type

application/json

Input

         
      
1
2
3
4
{
  "username": "donald.duck",
  "password": "aBs12Dvz5"
}
Output

         
      
1
2
3
4
5
{
  "access_token": "895d1a05-ba24-44f2-a9df-3675c1bde97b",
  "token_type": "bearer",
  "redirectUrl": "/accounts/#/cs/profile/home"
}

If using Jenkins, the Username and Password will need to be configured in the task. It is advised to create a dedicated Anypoint Platform account used exclusively for deployment and CI related activities.

The task will have to concatenate the 'token_type' and 'access_token' and save them for the duration of the entire workflow process. The fields must be concatenated as follows:

'token = token_type + " " + access_token'

E.g. '"bearer 895d1a05-ba24-44f2-a9df-3675c1bde97b"'

The token in its concatenated form must be passed as header in every subsequent API call.

2 - Accounts (Core Services API)

API Endpoint https://anypoint.mulesoft.com/accounts/api/me

Method

GET

Headers

Authorization: token (from step 1)

Content-Type

Output

         
      
1
2
3
4
5
6
7
8
9
10
11
12
13
{
  "access_token": {
    "access_token": "4c091a7c-5d28-43af-b949-214251e5472c",
    "expires_in": 3543
  },
  "user": {
    "id": "c4cf05d7-74c4-4178-b013-d976c57b4c8a",
    "organization": {
      "name": "MyOrganization",
      "id": "8d05377b-132c-43ef-994b-4cd8143e6c79"
    }
  }
}

This step is used to retrieve the organization identifier that is used later in the process. It is not mandatory, as the organization identifier is very unlikely to change, so you could have it hardcoded into your script.

The task must then extract the organization identifier from the location 'user.organisation.id' and save it for later use.

3 - Environments (Core Services API)

API Endpoint anypoint.mulesoft.com/accounts/api/organizations/{orgId}/environments

Method

GET

URI Parameters:

{orgId}: organisationId (from step 2)

Headers

Authorization: token (from step 1)

Content-Type

Output

         
      
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
{
  "data": [
    {
      "id": "876a4e54e2b0617fe28f1b42",
      "name": "Integration",
      "organizationId": "8d05377b-132c-43ef-994b-4cd8143e6c79",
      "isProduction": false
    },
    {
      "id": "225c4e73a3b0219fe26e1a88",
      "name": "Release",
      "organizationId": "8d05377b-132c-43ef-994b-4cd8143e6c79",
      "isProduction": false
    },
    {
      "id": "371e4e53f7f0812fe14d1c34",
      "name": "Production",
      "organizationId": "8d05377b-132c-43ef-994b-4cd8143e6c79",
      "isProduction": true
    }
  ],
  "total": 3
}

This step is to retrieve the 'id' for the environment that you wish to deploy to, it is later used as the target for the deployment in a further step. The organization 'id' retrieved in step 2 must be passed as part of the API URI.

This task needs to pick up the right environment 'id' based on the provided Environment, that you may set as an input at the beginning of the workflow. The environment 'id' must be extracted from the path 'data[i].id', where 'data[i].name == inputEnvironment' (it may take values like 'Dev', 'Test', 'Production' or any valid environment name that set up in your Anypoint Platform).

4 - Servers (Runtime Manager API)

GET Servers

This step must be executed only if the Target Type passed as an input parameter to the workflow task is equal to Server.
API Endpoint https://anypoint.mulesoft.com/hybrid/api/v1/servers

Method

GET

URI Parameters:

Headers

Authorization: token (from step 1)

X-ANYPNT-ORG-ID: organisationId (from step 2)

X-ANYPNT-ENV-ID: environmentId (from step 3)

Content-Type


          
       
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
Output
{
  "data": [
    {
      "id": 721,
      "name": "api-gateway-local-01",
      "serverType": "GATEWAY",
      "type": "SERVER"
    },
    {
      "id": 734,
      "name": "mule-esb-local-01",
      "serverType": "MULE",
      "type": "SERVER"
    },
    {
      "id": 724,
      "name": "mule-esb-local-02",
      "serverType": "MULE",
      "type": "SERVER"
    }
  ]
}

The step retrieves the server 'id', which is then used as target for the deployment.

The task will need to pick up the right server identifier based on the provided Target Name, that you may set as an input at the beginning of the workflow. The server 'id' msut be extracted from 'data[i].id' where 'data[i].name == inputTargetName'.

GET Clusters

This step must be executed only if the Target Type passed as an input parameter to the workflow task is equal to Cluster.
API Endpoint https://anypoint.mulesoft.com/hybrid/api/v1/clusters

Method

GET

URI Parameters:

Headers

Authorization: token (from step 1)

X-ANYPNT-ORG-ID: organisationId (from step 2)

X-ANYPNT-ENV-ID: environmentId (from step 3)

Content-Type


          
       
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
Output
{
  "data": [
    {
      "id": 725,
      "name": "ap-gateway-cluster",
      "multicastEnabled": false,
      "servers": [
        {
          "id": 722,
          "name": "api-gateway-local-02",
          "serverType": "GATEWAY",
          "type": "SERVER"
        },
        {
          "id": 721,
          "name": "api-gateway-local-01",
          "serverType": "GATEWAY",
          "type": "SERVER"
        }
      ]
    }
  ]
}

The step retrieves the cluster 'id', which is then used as target for the deployment.

The task will need to pick up the right cluster identifier based on the provided Target Name, that you may set as an input at the beginning of the workflow. The cluster 'id' msut be extracted from 'data[i].id' where 'data[i].name == inputTargetName'.

GET Server Groups

This step must be executed only if the Target Type passed as an input parameter to the workflow task is equal to ServerGroup
API Endpoint https://anypoint.mulesoft.com/hybrid/api/v1/serverGroups

Method

GET

URI Parameters:

Headers

Authorization: token (from step 1)

X-ANYPNT-ORG-ID: organisationId (from step 2)

X-ANYPNT-ENV-ID: environmentId (from step 3)

Content-Type


          
       
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
Output
{
  "data": [
    {
      "id": 751,
      "name": "mule-esb-group",
      "servers": [
        {
          "id": 734,
          "name": "mule-esb-local-03",
          "serverType": "MULE",
          "type": "SERVER"
        },
        {
          "id": 724,
          "name": "mule-esb-local-02",
          "serverType": "MULE",
          "type": "SERVER",
        }
      ]
    }
  ]
}

The step retrieves the server group 'id', which is then used as target for the deployment.

The task will need to pick up the right server group identifier based on the provided Target Name, that you may set as an input at the beginning of the workflow. The server group 'id' msut be extracted from 'data[i].id' where 'data[i].name == inputTargetName'.

5 - Applications (Runtime Manager API)

GET Applications

API Endpoint https://anypoint.mulesoft.com/hybrid/api/v1/applications

Method

GET

URI Parameters:

Headers

Authorization: token (from step 1)

X-ANYPNT-ORG-ID: organisationId (from step 2)

X-ANYPNT-ENV-ID: environmentId (from step 3)

Content-Type


          
       
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
Outputw
{
  "data": [
    {
      "id": 686,
      "artifact": {
        "id": 1027,
        "name": "test-new"
      },
      "target": {
        "id": 734
      }
    },
    {
      "id": 684,
      "artifact": {
        "id": 1026,
        "name": "test",
      },
      "target": {
        "id": 734
      }
    }
  ]
}

This step retrieves the application 'id' to determine whether the following step is a new deployment (6a) or a re-deployment (6b).

The application 'id' must be extracted from 'data[i].id' where 'data[i].artifact.name == inputArtifactName' and 'data[i].target.id == serverId' / 'clusterId' / 'serverGroupId'

POST Application

This step must be executed only if no application identifier was retrieved in step 5.
API Endpoint https://anypoint.mulesoft.com/hybrid/api/v1/applications

Method

POST

URI Parameters:

Headers

Authorization: token (from step 1)

X-ANYPNT-ORG-ID: organisationId (from step 2)

X-ANYPNT-ENV-ID: environmentId (from step 3)

Content-Type

form-data body

Body

artifactName = inputArtifactName (passed at the beginning of the workflow)

file = inputFile (passed as input at the beginning of the workflow)

targetId = serverId / clusterId / serverGroupId (from steps 4a, 4b or 4c)


          
       
1
2
3
4
5
6
7
8
9
10
11
12
13
14
Output
{
  "data": {
    "id": 684,
    "artifact": {
      "id": 1027,
      "name": "test",
      "fileName": "test.zip",
      "fileChecksum": "e98753b28c0fc7f2d01c56682de1387be0faf040",
      "timeUpdated": 1441221944496
    },
    "lastReportedStatus": "UNDEPLOYED"
  }
}

This step is a deployment of a new application. This step deploys the actual Mule application artifact for the first time to a target environment and server / cluster / server group.

PATCH Application

This step must be executed only if an application identifier was retrieved in step 5.
API Endpoint https://anypoint.mulesoft.com/hybrid/api/v1/applications/{appId}

Method

PATCH

URI Parameters:

{appId}: applicationId (from step 5)

Headers

Authorization: token (from step 1)

X-ANYPNT-ORG-ID: organisationId (from step 2)

X-ANYPNT-ENV-ID: environmentId (from step 3)

Content-Type

form-data body

Body

artifactName = inputArtifactName (passed at the beginning of the workflow)

file = inputFile (passed as input at the beginning of the workflow)

targetId = serverId / clusterId / serverGroupId (from steps 4a, 4b or 4c)


          
       
1
2
3
4
5
6
7
8
9
10
11
12
13
14
Output
{
  "data": {
    "id": 684,
    "artifact": {
      "id": 1027,
      "name": "test",
      "fileName": "test.zip",
      "fileChecksum": "e98753b28c0fc7f2d01c56682de1387be0faf040",
      "timeUpdated": 1441221944496
    },
    "lastReportedStatus": "STARTED"
  }
}

This step re-deploys the actual Mule application artifact to a target environment and server / cluster / server group.

Status Codes and Error Handling

When you call the REST APIs, the following status codes are returned:

Status Code Description

200

The operation was successful.

201

The resource (such as, application) was created. The Location header contains the location of the resource.

404

The resource was not found.

409

When creating a resource (such as, server, server group, or deployment), a resource with that name already exists.

500

The operation was unsuccessful. See the HTTP body for details.

When errors occur (for example, a 500 status code), the HTTP response contains a JSON response with an error message. For example:


         
      
1
2
3
4
5
6
7
8
500
Content-Type: application/json
Server: Apache-Coyote/1.1
Date: Mon, 10 Aug 2015 00:12:55 GMT
 
{
  message : "Some error message."
}

Check out the API Portal of the Runtime Manager REST API to see an interactive reference of all the supported resources, methods, required properties and expected responses.

Also, check out the CloudHub API for specifically managing cloud deployments.