API Usage Examples

This chapter shows how to use public API for some typical scenarios.

How to find a particular organization ID?

List all accessible organizations (link):

GET /api/1/organizations

Sample response:

[
  {
    "id": "5852c0c33d065c6d24ec4b70",
    "name": "Donald - Personal Account"
  },
  {
    "id": "5853ce5d3d06a1616c21f021",
    "name": "SAFD/RXP-CF"
  },
  {
    "id": "163d585d06a16ccef0212153",
    "name": "DXN-Zero CI/CD"
  }
]

Then search in the response JSON for the required organization and take its id field as a result.

How to find a particular application ID?

List all applications available within the desired organization (link):

GET /api/1/organizations/5852c0c33d065c6d24ec4b70/applications

Sample response:

[
  {
    "id": "5852c0c33d065c6d24ec4b81",
    "name": "Logstash"
  },
  {
    "id": "5852c0c43d065c6d24ec4b83",
    "name": "IIS"
  },
  {
    "id": "5852c0c43d065c6d24ec4b87",
    "name": "Kubernetes"
  },
  {
    "id": "5852c0c53d065c6d24ec4b89",
    "name": "Mesos"
  },
  {
    "id": "5852c0c53d065c6d24ec4b8b",
    "name": "MySQL"
  }
]

Now search in the response JSON for the required application and take its id field as a result.

How to find a particular application instance?

List all application instances (link):

Sample response:

[
  {
    "application": "5878f3173d06cd26897ed1e3",
    "name": "Imperial Pearl Tomcat",
    "revision": "588b37fd3d064ba646378e64",
    "id": "58c806313d06fc6666890b61",
    "status": "Running",
    "environment": "5852c0c33d065c6d24ec4b71"
  },
  {
    "application": "5878f3173d06cd26897ed1e3",
    "name": "Vivid Indigo Tomcat",
    "revision": "588b37fd3d064ba646378e64",
    "id": "58c806253d06fc6666890b5f",
    "status": "Destroyed",
    "environment": "5852c0c33d065c6d24ec4b71"
  }
]

Now search in the response JSON for the desired application instance.

How to launch a particular application?

The following API method support different ways for launching applications (link). Consider the Main Application is created and has got ID 5878f3173d06cd26897ed1e3. To launch the application the API call should look as the following:

POST /api/1/applications/5878f3173d06cd26897ed1e3/launch

There are different options one can pass within the request body to achieve different scenarios.

How to launch the application with default parameters and options?

Just pass an empty JSON in the request body:

{}

How to launch the application overriding some or all application parameters?

Consider overriding parameter input.app-tier-size with value 2 and parameters input.db-app-fork and input.web-app-fork with the dieu repository name. So pass the desired parameter values within the parameters object in the request JSON:

{
  "parameters": {
    "input.app-tier-size": "2",
    "input.db-app-fork": "dieu",
    "input.web-app-fork": "dieu"
  }
}

Those parameters which are not overridden in the request will keep their default values.

How to launch the application with a specific instance name?

Pass the instanceName option with the desired instance name:

{
  "instanceName": "FooBar MainApp"
}

How to launch the application inside a particular environment?

Pass the environmentId option with the desired environment ID:

{
  "environmentId": "58cffa453d0626fa613fa3e8"
}

How to launch a particular revision of the application?

Pass ID of the desired revision in the revisionId option:

{
  "revisionId": "58cbfa417ceaee703d3c047e"
}

How to launch the application with a particular manifest version?

Pass the version option with the desired manifest version as int value:

{
  "version": 5
}

How to configure the application’s submodule when launching the application?

Pass the db section enclosed into the submodules section and specify the desired launch options there:

{
  "submodules": {
    "db": {
      "revisionId": "58f8aafc7cea350dd8c16203",
      "manifestVersion": 7
    }
  }
}

How to specify submodule parameters directly when launching the application?

As for the Main Application example, it is not possible to specify the parameters input.app-fork and input.app-branch of the db submodule directly, since they’re mapped to the configuration parameters input.db-app-fork and input.db-app-branch of the main application in its manifest:

application:
  ...
  interfaces:
    ...
    input:
      db-app-fork:   bind(db#input.app-fork)
      db-app-branch: bind(db#input.app-branch)

Thus, these parameters can only be specified through the corresponding main application parameters, as shown in the example above.

On the other hand, if those parameters of the db submodule were not mapped to the parameters of the main application, then it would be possible to pass their values in the launch application request under the submodules section, as shown in the example below:

{
  "submodules": {
    "db": {
      "parameters": {
        "input.app-fork": "dieu",
        "input.app-branch": "master"
      }
    }
  }
}

How to reconfigure an application instance?

The instance reconfigure API method can be used to reconfigure a particular application instance. Consider the Main Application is launched and its instance has got ID 58d52fdf3d06d07984223bb6. In this case to reconfigure the instance use the following API call:

PUT /api/1/instances/58d52fdf3d06d07984223bb6/configuration

There are several reconfiguration options available.

How to change the instance configuration parameters?

To reset all the instance configuration parameters to their default values defined in the current manifest version, omit the parameters section or pass it as an empty object:

{
  "parameters": {}
}

To change the input.web-app-fork parameter to the value dieu and leave all the other parameters with their default values, send the following request:

{
  "parameters": {
    "input.web-app-fork": "dieu"
  }
}

When the reconfiguration completes, the input.web-app-fork parameter gets the desired value.

Now consider the following request, sent after the one above:

{
  "parameters" : {
    "input.db-app-fork": "dieu"
  }
}

This request changes the input.db-app-fork parameter to the value dieu, but simultaneously resets the previously changed input.web-app-fork to its original value qubell. To keep the new value of the input.web-app-fork parameter, use the following request instead:

{
  "parameters" : {
    "input.db-app-fork": "dieu",
    "input.web-app-fork": "dieu"
  }
}

Thus, all the parameters which have to keep their current values should be specified in the parameters section.

Note

To get actual values of all instance parameters issue the instance status API call and examine the response’s parameters section.

How to change parameters of the instance’s submodules?

As for the Main Application example, it is not possible to reconfigure the parameters input.app-fork and input.app-branch of the db submodule directly, since they’re mapped to the corresponding parameters of the main application in its manifest:

application:
  ...
  interfaces:
    ...
    input:
      db-app-fork:   bind(db#input.app-fork)
      db-app-branch: bind(db#input.app-branch)

Thus, these parameters can only be reconfigured through the main application parameters, as shown in the examples above.

On the other hand, if those parameters of the db submodule were not mapped to the parameters of the main application, then it would be possible to pass their values in the reconfigure instance request under the submodules section, as shown in the example below:

{
  "submodules": {
    "db": {
      "parameters": {
        "input.app-fork": "dieu",
        "input.app-branch": "master"
      }
    }
  }
}

How to reconfigure the instance manifest version?

There’s the manifestVersion option for reconfiguring versions of launched applications and modules. To change the manifest version of the Main Application instance to value 5, send the following request:

{
  "manifestVersion": 5
}

When the reconfiguration completes, all the instance parameters will be reset to their default values defined in the target manifest version. To prevent some parameters from changing, pass these parameters with their current values along with the manifestVersion option. For example, to keep input.db-app-fork at the value dieu, the request should looks like:

{
  "manifestVersion": 5,
  "parameters": {
    "input.db-app-fork": "dieu"
  }
}

When this request completes, the input.db-app-fork parameter will save its value dieu, but the input.web-app-fork parameter will be reset to its default value qubell.

The reconfiguration API also allows changing manifest versions of submodule instances. For example, to reconfigure the Database submodule instance to manifest version 6, send the following request:

{
  "submodules": {
    "db": {
      "manifestVersion": 6
    }
  }
}

Again, if it is necessary to keep current values of some instance parameters, these parameters should be defined in the parameters section within the same request body.

How to reconfigure the instance to another revision?

To reconfigure the instance to another revision, the revisionId option can be used:

{
  "revisionId": "58d92d1f3d0606faedb47e9f"
}

This reconfiguration request will apply to the instance those manifest versions and parameters which are stored in the specified revision. To override one or more manifest versions and instance parameters with direct values, define them explicitly along with the desired revision ID:

{
  "revisionId": "58d92d1f3d0606faedb47e9f",
  "parameters": {
    "input.db-app-fork": "abel"
  },
  "submodules": {
    "db": {
      "manifestVersion": 6
    }
  }
}

The request above will reconfigure the instance to the specified revision, but will override the input.db-app-fork instance property and the db submodule manifest version.