REST API

Nirmata provides a REST API for easy integration, using a language of your choice. The API provides support for all operations that can be performed from the Nirmata HTML 5 web application.

API Compatibility

The API is currently in development and is likely to change. Although we will strive to maintain compatibility, some changes may break existing integrations.

API Basics

The Nirmata API model is composed of resources. Each resource type is described by a class and is made up of attributes and relations. Each resource has a modelIndex that indicates its class, and a uri that describes how it can be queried. At runtime, each resource can contain relations to other resources. The relations can be parent-child relations or reference relations.

The Nirmata API is accessible at:

Note: trying the API URL in a browser will return an empty page, as the required HTTP headers are not specified. You can use a REST client, like Postman (http://www.getpostman.com/), to try and learn the API.

Authentication

To authenticate your account, you can use HTTP BASIC authentication or an API Key:

Authorization BASIC <Bas64 user:password>

or:

Authorization NIRMATA-API <your api key>

Since the Nirmata API is only accessible via HTTPS, your credentials are sent over an encrypted connection.

To manage your API Key, login to Nirmata and navigate to Settings -> Account -> Generate API Key. An API key is associated with a User account. When you authenticate an application using the API key, it will get the role and priviliges associated with the account.

A best practice recommendation is to create separare accounts for each application, and provide the minimum required role and priviliges to the account.

Operations

Operation HTTP Method URI Syntax Description
Create POST /{modelIndex} Creates a new resource. The modelIndex is the resource name.
/{parent}/{id}/{relation} Create a new resource, as child of the ‘{parent}/{id}’ resource
Retrieve GET /{modelIndex} Returns all resources of type specified by ‘modelIndex’
/{modelIndex}/{id} Returns a single resource
Update PUT /{modelIndex}/{id} Updates a resource
Delete DELETE /{modelIndex}/{id} Deletes a resource
Discover OPTIONS / Returns the class definitions for all resources
/{modelIndex} Returns the class definition for a single resource

HTTP Response Status Codes

The following table lists common HTTP response codes used by the API:

HTTP Status Code Description
200 The operation succeeded
401 The user authentication failed
403 The request was not permitted
406 The request results in an invalid configuration
500 The request caused a server error

Resources

The following resources are available via the API:

  • Root
  • Application
  • EnvironmentType
  • ContainerType
  • ResourceSelectionPolicy
  • ResourceSelectionRule
  • CloudProvider
  • HostGroup
  • Host
  • Container
  • Service
  • Environment
  • ServiceInstance
  • ServicePort
  • ServiceSpec
  • Registry
  • LaunchConfiguration
  • VSphereConfig
  • VCloudConfig
  • OpenStackConfig
  • AzureConfig
  • WebHook
  • ScalingPolicy
  • DesiredService
  • ScalingRule
  • ServiceInstanceAction
  • ServiceAffinityRule
  • ServiceScalingRule
  • RoutingPolicy
  • RoutingRule
  • GatewayRoute
  • GatewayPolicy
  • GatewayRule

HTTP Headers

The following HTTP headers are required:

Header Sample Description
Authorization NIRMATA-API <api-key> API key based authentication
Accept application/json Specifies request for JSON data

URL Parameters

URL Parameters are used to control the returned JSON data.

mode

The mode parameter is used to control the JSON output format for a GET request. Here are the allowed values:
  • normal
  • export
  • exportDetails

In the normal mode the JSON data for each object contains all attributes and relations are output as links. In the export mode the JSON data contains all attributes and child relation objects are directly embedded into the parent. Reference relations are represented as links, and also contain the unique attributes of the referred to object. The mode parameter can be applied to all GET requests and can be combined with other parameters. The export mode is useful when an entire sub-document needs to be retrieved and stored externally. For example, the following query will export the full {model} as JSON:

GET http://www.nirmata.io/api/applications/{id}?mode=export
Accept: application/json

The exportDetails mode also includes meta-data fields and relations to external entities (outside of the target document).

query

The query parameter is used to control which objects are included in a JSON response. The query data is specified as a JSON object. The query parameter can be applied to any GET request that returns multiple objects. For example the following query returns all service instances that have attribute state with the value failed:

GET  http://www.nirmata.io/api/serviceInstances?query={"state":"failed"}
Accept: application/json

Multiple attributes can be specified for a logical AND operation:

GET  http://www.nirmata.io/api/applications/api/serviceInstances?query={"state":"failed", "serviceRef":"01101AKAJAL10107252418HG"}
Accept: application/json

fields

The fields parameter is used to control which fields, of an resource, should be included in the JSON response. The fields parameter can be applied to any GET request. The fields parameter value is specified as a single field name, or a comma separated list of field names, that should be included in the response.

For example, this query returns only the id and state fields of all ServiceInstance resources:

GET  http://www.nirmata.io/api/serviceInstances?fields=id,state
Accept: application/json

excludeFields

The excludeFields parameter is used to exclude one or more fields from the response. The excludeFields parameter can be applied to any GET request. The fields parameter value is specified as a single field name, or a comma separated list of field names, that should be excluded from the response.

For example, this query excludes the state field from ServiceInstance resources:

GET  http://www.nirmata.io/api/serviceInstances?excludeFields=state
Accept: application/json

count

The count parameter is used to specify the maximum number of resources to be returned. It can be used when querying a relation, a list of resources, or using a query parameter. A positive value is expected. When not specified, all matching resources are returned. For example the following query returns up to 100 instances of the resource serviceInstances that have attribute state with the value up:

GET  http://www.nirmata.io/api/serviceInstances?count=100&query={"state":"up"}
Accept: application/json

start

The start parameter is used to specify the start index in a list of resources. It can be used when querying a relation, a list of resources, or using a query parameter. A positive value is expected. When not specified a value of 0 is assumed. For example the following query returns instances 100-200 (or less) of the resource serviceInstances that have attribute state with the value up:

GET  http://www.nirmata.io/api/serviceInstances&query={"state":"up"}
Accept: application/json

Common Endpoints

All resources implement a few common endpoints for querying related resources:

descendants

Returns all descendants of a model type. The full URL is of the form:

/{service}/api/{model}/{id}/descendants/{model}

Note that the descendants keyword is optional. So the following is an equivalent query to retrieve all direct or sub-descendants:

/{service}/api/{model}/{id}/{model}

ancestors

Returns all ancestors (parents and their parents) of a model instance. The full URL is of the form:

/{service}/api/{model}/{id}/ancestors

ancestor

Returns an ancestors of a model instance, that matches the provided model type. The full URL is of the form:

/{service}/api/{model}/{id}/ancestor/{model}

currentAlarms

Returns all current (active and not-cleared) alarms of a model instance:

/{service}/api/{model}/{id}/currentAlarms

currentAlarmCounts

Returns the count of all current (active and not-cleared) alarms of a model instance:

/{service}/api/{model}/{id}/currentAlarmCounts

Service Instance Error Codes

The API user can retrieve a failed Service Instance and read the errorCode field in order to get more details about the error. This field can take the following values:

Error Code Description
NoError The Service Instance is not in failed state
UnknownError Unknown error
ServiceInstanceFailure Service instance failed: unknown reason
InternalError Internal error
ContainerFailed Container failed on host
ContainerCreationError Failed to create container on host
ContainerNotRunning Container found in non running state on host
ContainerNotFound No container found on the host
NoSuitableHost Container placement failed: couldn’t find suitable host
DependencyInjectionError Dependency injection error
VolumeCreationFailed Failed to create storage volume on host
NetworkCreationFailed Failed to create network on host
MemoryLimitReached Container exited abruptly, memory limit reached
HostNotConnectedAndUnreachable Host not connected and unreachable through cloud provider
HostNotConnected Host not connected
PullImageFailed Failed to pull image
NoSaceLeftOnHost No space left on host
HealthCheckFailed Health check failed

Sample Operations

Get all applications

Request:

GET /api/applications
Accept: application/json
Authorization: NIRMATA-API <key>

Response Headers:

HTTP/1.1 200 OK
...

Response Body:

[
 {
     "id": "1696d434-0e97-4428-8875-e53069ea418b",
     "service": "Config",
     "modelIndex": "Application",
     "uri": "/config/api/applications/1696d434-0e97-4428-8875-e53069ea418b",
     "parent": {
         "id": "132eb66a-1c78-4a3e-a096-3ce9c57aefec",
         "service": "Config",
         "modelIndex": "Root",
         "uri": "/config/api/roots/132eb66a-1c78-4a3e-a096-3ce9c57aefec",
         "childRelation": "applications"
     },
     "createdBy": "damien",
     "createdOn": 1421778225729,
     "versionName": "latest",
     "versions": [],
     "name": "shopme-damien",
     "description": "A Microservices architecture style shopping application.",
     "services": [
         {
             "id": "fbd5098b-a096-41f0-9f95-a012b9c86d96",
             "service": "Config",
             "modelIndex": "Service",
             "uri": "/config/api/services/fbd5098b-a096-41f0-9f95-a012b9c86d96"
         },
         {
             "id": "eb3b740e-96e8-45ff-b981-76300d491f86",
             "service": "Config",
             "modelIndex": "Service",
             "uri": "/config/api/services/eb3b740e-96e8-45ff-b981-76300d491f86"
         },
         {
             "id": "587d997f-c931-4c5c-a6a4-08787b273884",
             "service": "Config",
             "modelIndex": "Service",
             "uri": "/config/api/services/587d997f-c931-4c5c-a6a4-08787b273884"
         },
         {
             "id": "cb28c6fd-1583-4151-b76c-c7ef07255670",
             "service": "Config",
             "modelIndex": "Service",
             "uri": "/config/api/services/cb28c6fd-1583-4151-b76c-c7ef07255670"
         },
         {
             "id": "2a14cb82-82e9-4d95-a087-8471c131a5c2",
             "service": "Config",
             "modelIndex": "Service",
             "uri": "/config/api/services/2a14cb82-82e9-4d95-a087-8471c131a5c2"
         },
         {
             "id": "738ffeb1-3829-4488-b310-56e33d7c3181",
             "service": "Config",
             "modelIndex": "Service",
             "uri": "/config/api/services/738ffeb1-3829-4488-b310-56e33d7c3181"
         },
         {
             "id": "4cfda00b-0781-4f73-b08d-40c1cfb96952",
             "service": "Config",
             "modelIndex": "Service",
             "uri": "/config/api/services/4cfda00b-0781-4f73-b08d-40c1cfb96952"
         },
         {
             "id": "589dda7c-908a-468e-81be-dd63ba9a3fa9",
             "service": "Config",
             "modelIndex": "Service",
             "uri": "/config/api/services/589dda7c-908a-468e-81be-dd63ba9a3fa9"
         },
         {
             "id": "8cace559-8024-44e9-9e7b-a61263361358",
             "service": "Config",
             "modelIndex": "Service",
             "uri": "/config/api/services/8cace559-8024-44e9-9e7b-a61263361358"
         },
         {
             "id": "0f1daa18-0493-4fbc-aadf-9a2a26134f6d",
             "service": "Config",
             "modelIndex": "Service",
             "uri": "/config/api/services/0f1daa18-0493-4fbc-aadf-9a2a26134f6d"
         },
         {
             "id": "edb40d39-5578-4353-9649-22cbe7554822",
             "service": "Config",
             "modelIndex": "Service",
             "uri": "/config/api/services/edb40d39-5578-4353-9649-22cbe7554822"
         }
     ],
     "webHooks": [],
     "serviceAffinityRules": [],
     "serviceScalingRules": [],
     "environments": [],
     "gateway": [
         {
             "id": "cb28c6fd-1583-4151-b76c-c7ef07255670",
             "service": "Config",
             "modelIndex": "Service",
             "uri": "/config/api/services/cb28c6fd-1583-4151-b76c-c7ef07255670"
         }
     ]
 },
     ...
]

Get Service Details

The mode parameter is used to export all relations.

Request:

GET /api/services/fbd5098b-a096-41f0-9f95-a012b9c86d96?mode=exportDetails
Accept: application/json
Authorization: NIRMATA-API <key>

Response Headers:

HTTP/1.1 200 OK
...

Response Body:

{
"id": "fbd5098b-a096-41f0-9f95-a012b9c86d96",
"service": "Config",
"modelIndex": "Service",
"uri": "/config/api/services/fbd5098b-a096-41f0-9f95-a012b9c86d96",
"parent": {
    "id": "1696d434-0e97-4428-8875-e53069ea418b",
    "service": "Config",
    "modelIndex": "Application",
    "uri": "/config/api/applications/1696d434-0e97-4428-8875-e53069ea418b",
    "childRelation": "services"
},
"createdBy": "damien",
"createdOn": 1421778225744,
"versionName": "latest",
"versions": [],
"name": "orders",
"imageRepository": "nirmata/orders",
"serviceSpec": [
    {
        "id": "64917ec6-19cb-4abe-826e-a4a35716f5b6",
        "service": "Config",
        "modelIndex": "ServiceSpec",
        "uri": "/config/api/serviceSpecs/64917ec6-19cb-4abe-826e-a4a35716f5b6",
        "parent": {
            "id": "fbd5098b-a096-41f0-9f95-a012b9c86d96",
            "service": "Config",
            "modelIndex": "Service",
            "uri": "/config/api/services/fbd5098b-a096-41f0-9f95-a012b9c86d96",
            "childRelation": "serviceSpec"
        },
        "createdBy": "damien",
        "createdOn": 1421778225755,
        "versionName": "latest",
        "versions": [],
        "runCommand": "",
        "properties": [],
        "hostname": "",
        "volumeMappings": [],
        "isPrivileged": false,
        "volumesFrom": [],
        "dns": [],
        "networkMode": "bridge",
        "enableServiceNetworking": true,
        "portMappings": [
            {
                "id": "9630c407-003e-4a63-8ba4-2be42be7709e",
                "service": "Config",
                "modelIndex": "ServicePort",
                "uri": "/config/api/servicePorts/9630c407-003e-4a63-8ba4-2be42be7709e",
                "parent": {
                    "id": "64917ec6-19cb-4abe-826e-a4a35716f5b6",
                    "service": "Config",
                    "modelIndex": "ServiceSpec",
                    "uri": "/config/api/serviceSpecs/64917ec6-19cb-4abe-826e-a4a35716f5b6",
                    "childRelation": "portMappings"
                },
                "createdBy": "damien",
                "createdOn": 1421778225769,
                "versionName": "latest",
                "versions": [],
                "containerPort": 80,
                "type": "TCP",
                "hostPort": 0,
                "name": "HTTP"
            }
        ]
    }
],
"gatewayRoutes": [
    {
        "id": "d20f0221-5a1a-48e0-a586-3f91b3333856",
        "service": "Config",
        "modelIndex": "GatewayRoute",
        "uri": "/config/api/gatewayRoutes/d20f0221-5a1a-48e0-a586-3f91b3333856",
        "parent": {
            "id": "fbd5098b-a096-41f0-9f95-a012b9c86d96",
            "service": "Config",
            "modelIndex": "Service",
            "uri": "/config/api/services/fbd5098b-a096-41f0-9f95-a012b9c86d96",
            "childRelation": "gatewayRoutes"
        },
        "createdBy": "damien",
        "createdOn": 1421778225788,
        "versionName": "latest",
        "versions": [],
        "type": "urlRoute",
        "route": "/orders"
    }
],
"containerType": [
    {
        "id": "ffeb8b87-2d61-4144-ac23-ead227fb6c1b",
        "service": "Config",
        "modelIndex": "ContainerType",
        "uri": "/config/api/containerTypes/ffeb8b87-2d61-4144-ac23-ead227fb6c1b",
        "name": "512mb"
    }
],
"dependsOn": [],
"requiredBy": [
    {
        "id": "cce2798b-f92f-49d3-afae-625aea3f77fd",
        "service": "Config",
        "modelIndex": "Service",
        "uri": "/config/api/services/cce2798b-f92f-49d3-afae-625aea3f77fd",
        "name": "customer"
    },
    {
        "id": "eb3b740e-96e8-45ff-b981-76300d491f86",
        "service": "Config",
        "modelIndex": "Service",
        "uri": "/config/api/services/eb3b740e-96e8-45ff-b981-76300d491f86",
        "name": "customer"
    }
],
"serviceInstances": [],
"desiredServices": [],
"serviceAffinityRules": [],
"serviceScalingRules": [],
"gatewayApplication": []
}

Create an Application

Request:

POST https://www.nirmata.io/api/applications/
Accept: application/json
Authorization: NIRMATA-API <key>

{
    "name": "MyApp",
    "description": "this is a sample application"
}

A successful POST returns the complete resource as its result:

Response Headers:

HTTP/1.1 200 OK
...

Response Body:

{
  "id" : "c7bf4bfa-346e-44f8-b62c-9b8fdf5c1980",
  "service" : "Config",
  "modelIndex" : "Application",
  "uri" : "/config/api/applications/c7bf4bfa-346e-44f8-b62c-9b8fdf5c1980",
  "parent" : {
    "id" : "132eb66a-1c78-4a3e-a096-3ce9c57aefec",
    "service" : "Config",
    "modelIndex" : "Root",
    "uri" : "/config/api/roots/132eb66a-1c78-4a3e-a096-3ce9c57aefec",
    "childRelation" : "applications"
  },
  "createdBy" : "jim",
  "createdOn" : 1422318766175,
  "versionName" : "latest",
  "versions" : [ ],
  "name" : "MyApp",
  "description" : "this is a sample application",
  "services" : [ ],
  "webHooks" : [ ],
  "serviceAffinityRules" : [ ],
  "serviceScalingRules" : [ ],
  "environments" : [ ],
  "gateway" : [ ]
}

Delete an Application

Request:

DELETE /api/applications/c7bf4bfa-346e-44f8-b62c-9b8fdf5c1980
Accept: application/json
Authorization: NIRMATA-API <key>

Response Headers:

HTTP/1.1 200 OK
...

Response Body:

{}

Get the ID of an Application named ‘hello-world’

Request:

GET /api/applications?query={"name": "hello-world"}&fields={"include":"id"}
Accept: application/json
Authorization: NIRMATA-API <key>

Response Headers:

HTTP/1.1 200 OK
...

Response Body:

[
    {
        "id": "8032f2ce-eae0-402b-8d80-2a47717b52ef"
    }
]

Get all Environment IDs and names

Request:

GET /api/environments?fields=id,name
Accept: application/json
Authorization: NIRMATA-API <key>

Response Headers:

HTTP/1.1 200 OK
...

Response Body:

[
    {
        "id": "f9594d4a-605e-4ced-a9d0-4c00c4b5abf3",
        "name": "workflow"
    },
    {
        "id": "dd333b0f-0e63-4644-aedc-8871f026a028",
        "name": "zookeeper"
    },
    {
        "id": "dee56b58-792c-4a43-bc51-2b3785868858",
        "name": "test21"
    }
]

Create a new Environment

Request:

POST /api/environments/
Accept: application/json
Authorization: NIRMATA-API <key>

{
  "name": "testEnvironment",
  "environmentType": {"name": "AWS"},
  "application": {"name": "hello-world"}
}
Note the different ways you can specify a relation in the JSON. For a 1-1 relationship you can:
  1. Specify an ID as a JSON string, as done for application in the above example
  2. Specify an object with fields that can be used to match the relation. In the example above, we use the name field for the EnvironmentType.

Response Headers:

HTTP/1.1 200 OK
...

Response Body:

{
  "id" : "bf24dc3f-c729-4c8b-911c-991aab09df70",
  "service" : "Config",
  "modelIndex" : "Environment",
  "uri" : "/config/api/environments/bf24dc3f-c729-4c8b-911c-991aab09df70",
  "parent" : {
    "id" : "132eb66a-1c78-4a3e-a096-3ce9c57aefec",
    "service" : "Config",
    "modelIndex" : "Root",
    "uri" : "/config/api/roots/132eb66a-1c78-4a3e-a096-3ce9c57aefec",
    "childRelation" : "environments"
  },
  "createdBy" : "jim",
  "createdOn" : 1422319764842,
  "versionName" : "latest",
  "versions" : [ ],
  "name" : "testEnvironment",
  "serviceInstances" : [ ],
  "desiredServices" : [ ],
  "scalingPolicy" : [ {
    "id" : "55a3399a-5ed0-499e-aa6c-ef06984a8b69",
    "service" : "Config",
    "modelIndex" : "ScalingPolicy",
    "uri" : "/config/api/scalingPolicies/55a3399a-5ed0-499e-aa6c-ef06984a8b69"
  } ],
  "routingPolicy" : [ {
    "id" : "65d60c9c-f98b-4a81-84ef-3a0865164af9",
    "service" : "Config",
    "modelIndex" : "RoutingPolicy",
    "uri" : "/config/api/routingPolicies/65d60c9c-f98b-4a81-84ef-3a0865164af9"
  } ],
  "gatewayPolicy" : [ ],
  "environmentType" : [ {
    "id" : "9d789292-5911-47d3-b4dd-c66bb1f64858",
    "service" : "Config",
    "modelIndex" : "EnvironmentType",
    "uri" : "/config/api/environmentTypes/9d789292-5911-47d3-b4dd-c66bb1f64858"
  } ],
  "application" : [ {
    "id" : "8032f2ce-eae0-402b-8d80-2a47717b52ef",
    "service" : "Config",
    "modelIndex" : "Application",
    "uri" : "/config/api/applications/8032f2ce-eae0-402b-8d80-2a47717b52ef"
  } ]
}

Create a new Environment with environment variables, labels, and Gateway rules

Request Headers:

POST /api/environments/
Accept: application/json
Authorization: NIRMATA-API <key>

Request Body:

{
    "name": "helloOpenStack3",
    "environmentType": {"name": "openstack-private-cloud"},
    "application": {"name": "hello-world"},
    "desiredServices" : [
        {"name": "helloworld:latest", "serviceRef": {"name": "helloworld"}, "tag": "latest" },
        {"name": "hello-world-gateway:latest", "serviceRef": {"name": "hello-world-gateway"}, "tag": "latest" }
    ],
    "environmentVariables": [
        { "key": "DATABASE", "value": "mydb.cluster1.com", "desiredServices": [{"name": "helloworld:latest"}] },
        { "key": "TYPE", "value": "staging", "desiredServices": [] }
    ],
    "labelSelectors": [
        {
            "labelSelectorItem": [{"key": "LOCATION", "operator": "equals", "values": ["Denver"]}],
            "desiredServices": [{"name": "helloworld:latest"}]
        }
    ],
    "gatewayPolicy": [
        {
            "redirectHttp": false,
            "rules": [
                {
                    "type": "urlRoute",
                    "route": "/helloworld",
                    "toService": "helloworld",
                    "toTag": "",
                    "toPort": 8080,
                    "toPortType": "HTTP",
                    "targetUrl": "",
                    "stickySessions": true
                }
            ]
        }
    ]
}

Response Headers:

HTTP/1.1 200 OK
...

Response Body:

{
  "id" : "392f7627-4add-4231-8e2f-7f4faabad0dd",
  "service" : "Config",
  "modelIndex" : "Environment",
  "uri" : "/config/api/environments/392f7627-4add-4231-8e2f-7f4faabad0dd",
  "parent" : {
    "id" : "132eb66a-1c78-4a3e-a096-3ce9c57aefec",
    "service" : "Config",
    "modelIndex" : "Root",
    "uri" : "/config/api/roots/132eb66a-1c78-4a3e-a096-3ce9c57aefec",
    "childRelation" : "environments"
  },
  "createdBy" : "jim@nirmata.com",
  "createdOn" : 1451973613713,
  "versionName" : "latest",
  "versions" : [ ],
  "name" : "helloOpenStack3",
  "state" : "pending",
  "status" : [ ],
  "serviceInstances" : [ ],
  "desiredServices" : [ {
    "id" : "69212ca9-ecd9-4636-ac6a-1269790cf986",
    "service" : "Config",
    "modelIndex" : "DesiredService",
    "uri" : "/config/api/desiredServices/69212ca9-ecd9-4636-ac6a-1269790cf986"
  }, {
    "id" : "fe56d2a3-c1d6-43f2-a857-b766c6a18335",
    "service" : "Config",
    "modelIndex" : "DesiredService",
    "uri" : "/config/api/desiredServices/fe56d2a3-c1d6-43f2-a857-b766c6a18335"
  } ],
  "scalingPolicy" : [ {
    "id" : "128bc9f5-da9a-437b-8b3f-b825eaf8a949",
    "service" : "Config",
    "modelIndex" : "ScalingPolicy",
    "uri" : "/config/api/scalingPolicies/128bc9f5-da9a-437b-8b3f-b825eaf8a949"
  } ],
  "routingPolicy" : [ {
    "id" : "f66208cc-b27e-4cac-912f-d9b624efb10b",
    "service" : "Config",
    "modelIndex" : "RoutingPolicy",
    "uri" : "/config/api/routingPolicies/f66208cc-b27e-4cac-912f-d9b624efb10b"
  } ],
  "gatewayPolicy" : [ {
    "id" : "3a37f07f-1c83-4e7c-8e93-f0c4813438b8",
    "service" : "Config",
    "modelIndex" : "GatewayPolicy",
    "uri" : "/config/api/gatewayPolicies/3a37f07f-1c83-4e7c-8e93-f0c4813438b8"
  } ],
  "clusters" : [ ],
  "updatePolicy" : [ {
    "id" : "6302d966-7a12-4237-968c-94dc3f9ddc81",
    "service" : "Config",
    "modelIndex" : "UpdatePolicy",
    "uri" : "/config/api/updatePolicies/6302d966-7a12-4237-968c-94dc3f9ddc81"
  } ],
  "labelSelectors" : [ {
    "id" : "29905746-5792-45bf-8d12-0d98416af33a",
    "service" : "Config",
    "modelIndex" : "DesiredServiceLabelSelector",
    "uri" : "/config/api/labelSelectors/29905746-5792-45bf-8d12-0d98416af33a"
  } ],
  "environmentVariables" : [ {
    "id" : "69777ea7-806d-489a-8ba0-3e46ef5c1e0c",
    "service" : "Config",
    "modelIndex" : "EnvironmentVariable",
    "uri" : "/config/api/environmentVariables/69777ea7-806d-489a-8ba0-3e46ef5c1e0c"
  }, {
    "id" : "cccaeb71-5a5f-45d1-ad44-08d4a8e3e977",
    "service" : "Config",
    "modelIndex" : "EnvironmentVariable",
    "uri" : "/config/api/environmentVariables/cccaeb71-5a5f-45d1-ad44-08d4a8e3e977"
  } ],
  "environmentType" : [ {
    "id" : "d1383ef4-ee02-46eb-9c98-fd9a4d975eed",
    "service" : "Config",
    "modelIndex" : "EnvironmentType",
    "uri" : "/config/api/environmentTypes/d1383ef4-ee02-46eb-9c98-fd9a4d975eed"
  } ],
  "application" : [ {
    "id" : "7eb02867-dc89-44fc-81f3-3cea699377d9",
    "service" : "Config",
    "modelIndex" : "Application",
    "uri" : "/config/api/applications/7eb02867-dc89-44fc-81f3-3cea699377d9"
  } ]
}

Get Services in an Environment

Request:

GET /api/environments/dee56b58-792c-4a43-bc51-2b3785868858/desiredServices?fields=name,id
Accept: application/json
Authorization: NIRMATA-API <key>

Response Headers:

HTTP/1.1 200 OK
...

Response Body:

[
    {
        "id": "d0ca8e5e-815d-42e4-b85a-2dff6afb395c",
        "name": "orders:latest"
    },
    {
        "id": "7fae24aa-51e0-4f48-8cf9-43f4587bce27",
        "name": "customer:latest"
    },
    {
        "id": "ca2d9888-4e18-4209-952f-73b1ece9c02c",
        "name": "catalog:latest"
    },
    {
        "id": "66474274-5800-44b2-8c7d-ad4c8265ab04",
        "name": "ratings:latest"
    },
    {
        "id": "ed243ae3-77ff-458b-ae70-21643a328b34",
        "name": "recommendations:latest"
    }
]

Delete a Service Instance

Request:

DELETE /api/serviceInstances/1c98b95b-29bc-4c2b-a0e0-8f46a353115e
Accept: application/json
Authorization: NIRMATA-API <key>

Response Headers:

HTTP/1.1 200 OK
...

Response Body:

{}

Delete all instances of a Service

You can easily combine multiple operations using a programming language, scripting, or command line tools like JQ:

#!/bin/bash

# Environment ID and Service name:tag are passed in
EnvId=$1

BaseUrl="https://nirmata.io/config/api"
ApiKey=<apikey>
Accept="Accept: application/json"
Auth="Authorization: NIRMATA-API $ApiKey"

curl -H "$Accept" -H "$Auth" $BaseUrl/environments/$EnvId/desiredServices?fields=name,id,serviceInstances | \
    jq -r --arg ServiceName "$2" '.[] | select(.name == $ServiceName) | .serviceInstances | .[] .id' |  \
    xargs -I% curl -X DELETE -H "$Accept" -H "$Auth" $BaseUrl/serviceInstances/%
The bash script does the following:
  1. Gets the service instances for an environment
  2. Filters service instances for a specific service name
  3. Pipes the matching IDs to a API call to delete the matching service instances

Add a Service to an Environment

Request:

POST /api/environments/70e12f6e-9961-40d1-92eb-2d8db1c37b34/desiredServices
Accept: application/json
Authorization: NIRMATA-API <key>

{
    "name": "catalog:blue",
    "tag": "blue",
    "serviceRef": {"name": "catalog"}
}

Response Headers:

HTTP/1.1 200 OK
...

Response Body:

{
    "id" : "3b45c735-4e71-41ad-9c96-ca5b46b28d88",
    "service" : "Config",
    "modelIndex" : "DesiredService",
    "uri" : "/config/api/desiredServices/3b45c735-4e71-41ad-9c96-ca5b46b28d88",
    "parent" : {
    "id" : "70e12f6e-9961-40d1-92eb-2d8db1c37b34",
    "service" : "Config",
    "modelIndex" : "Environment",
    "uri" : "/config/api/environments/70e12f6e-9961-40d1-92eb-2d8db1c37b34",
    "childRelation" : "desiredServices"
    },
    "createdBy" : "jim@nirmata.com",
    "createdOn" : 1450667141749,
    "versionName" : "latest",
    "versions" : [ ],
    "tag" : "blue",
    "lastStateChange" : 0,
    "startImageUpdateQuietPeriod" : 0,
    "name" : "catalog:blue",
    "actions" : [ ],
    "imageUpdateEvent" : [ ],
    "serviceRef" : [ {
    "id" : "8f7c848f-b7cc-4dd6-805c-5fe2462c555c",
    "service" : "Config",
    "modelIndex" : "Service",
    "uri" : "/config/api/services/8f7c848f-b7cc-4dd6-805c-5fe2462c555c"
    } ],
    "scalingRule" : [ ],
    "serviceInstances" : [ ],
    "cluster" : [ ],
    "labelSelectors" : [ ],
    "environmentVariables" : [ ]
}

Get Environment Information

Request:

GET /api/environments?query={"name" :"shop-demo"}&mode=exportDetails&fields=id,name,scalingPolicy,scalingRules,desiredServices
Accept: application/json
Authorization: NIRMATA-API <key>

Response Headers:

HTTP/1.1 200 OK
...

Response Body:

[
    {
        "id": "70e12f6e-9961-40d1-92eb-2d8db1c37b34",
        "name": "shop-demo",
        "desiredServices": [
            {
                "id": "faefb6bf-4eb4-4c84-844c-1486bb7071b4",
                "name": "orders:latest"
            },
            {
                "id": "684b2add-26cb-4873-b6f5-f885a827c017",
                "name": "customer:latest"
            },
            {
                "id": "ec27e08f-c702-4832-bb50-69008393b000",
                "name": "catalog:latest"
            },
            {
                "id": "018f1ca8-b2dd-4c37-a1f7-315d704aa01c",
                "name": "ratings:latest"
            },
            {
                "id": "3dad36c8-12ac-4280-a862-fb1b38bb6ed4",
                "name": "recommendations:latest"
            },
            {
                "id": "2b2f6089-728d-4759-a8c4-f51c98c47077",
                "name": "shop4me-gateway:latest"
            },
            {
                "id": "3b45c735-4e71-41ad-9c96-ca5b46b28d88",
                "name": "catalog:blue"
            }
        ],
        "scalingPolicy": [
            {
                "id": "a9bf6aa3-0d98-401f-b7a8-21965b8f65b5",
                "scalingRules": [
                    {
                        "id": "0c616025-babe-42b3-ba3d-b93f22348baf",
                        "desiredServices": [
                            {
                                "id": "ec27e08f-c702-4832-bb50-69008393b000",
                                "name": "catalog:latest"
                            }
                        ]
                    }
                ]
            }
        ]
    }
]

Scale-up or scale-down a Service

Request:

PUT /api/scalingRules/0c616025-babe-42b3-ba3d-b93f22348baf
Accept: application/json
Authorization: NIRMATA-API <key>

{
    "desiredCount" : 5
}

Response Headers:

HTTP/1.1 200 OK
...

Response Body:

{
  "id" : "0c616025-babe-42b3-ba3d-b93f22348baf",
  "service" : "Config",
  "modelIndex" : "ScalingRule",
  "uri" : "/config/api/scalingRules/0c616025-babe-42b3-ba3d-b93f22348baf",
  "parent" : {
    "id" : "a9bf6aa3-0d98-401f-b7a8-21965b8f65b5",
    "service" : "Config",
    "modelIndex" : "ScalingPolicy",
    "uri" : "/config/api/scalingPolicies/a9bf6aa3-0d98-401f-b7a8-21965b8f65b5",
    "childRelation" : "scalingRules"
  },
  "createdBy" : "jim@nirmata.com",
  "createdOn" : 1450667592016,
  "modifiedBy" : "jim@nirmata.com",
  "modifiedOn" : 1450667690973,
  "versionName" : "latest",
  "versions" : [ ],
  "desiredCount" : 5,
  "autoRecovery" : true,
  "desiredServices" : [ {
    "id" : "ec27e08f-c702-4832-bb50-69008393b000",
    "service" : "Config",
    "modelIndex" : "DesiredService",
    "uri" : "/config/api/desiredServices/ec27e08f-c702-4832-bb50-69008393b000"
  } ]
}

Creating an AWS Host Group from an AMI

Request:

POST /api/cloudProviders/{cloudProviderId}/hostGroups
Accept: application/json
Authorization: NIRMATA-API <key>

{
    "name" : "testHostGroup",
    "desiredCount" : 1,
    "awsConfig" : {
        "awsConfigType" : "ami",
        "region" : "us-west-1",
        "image" : "ami-d8bdebb8",
        "instanceType" : "m3.medium",
        "keypair" : "{keypair name}",
        "storageCapacity" : 30,
        "network" : "subnet-8bf9f0ee",
        "securityGroups" : ["sg-22db3266", "sg-1a38d97f"],
        "userData" : "#!/bin/bash -x \n# Install docker \n# Please verify docker engine installation for your OS: \n#      https://docs.docker.com/engine/installation/ \nsudo curl -sSL https://get.docker.com/ | sh \n\n# Install Nirmata Agent \nsudo curl -sSL https://www.nirmata.io/nirmata-host-agent/setup-nirmata-agent.sh | sudo sh -s -- --cloud aws \n"
    }
}

Response Headers:

HTTP/1.1 200 OK
...

Response Body:

{
  "id" : "3f07601e-57b3-4e2d-b960-7df375653ae5",
  "service" : "Config",
  "modelIndex" : "HostGroup",
  "uri" : "/config/api/hostGroups/3f07601e-57b3-4e2d-b960-7df375653ae5",
  "parent" : {
    "id" : "125b0984-0476-4c76-850c-b857b9ef3fe3",
    "service" : "Config",
    "modelIndex" : "CloudProvider",
    "uri" : "/config/api/cloudProviders/125b0984-0476-4c76-850c-b857b9ef3fe3",
    "childRelation" : "hostGroups"
  },
  "createdBy" : "jim@nirmata.com",
  "createdOn" : 1483757064734,
  "modifiedBy" : "jim@nirmata.com",
  "modifiedOn" : 1483757064734,
  "alarms" : [ ],
  "name" : "testHostGroup",
  "desiredCount" : 1,
  "status" : [ ],
  "usePublicIpAddresses" : false,
  "hosts" : [ ],
  "vSphereConfig" : [ ],
  "openStackConfig" : [ ],
  "vCloudConfig" : [ ],
  "azureConfig" : [ ],
  "ciscoIcfConfig" : [ ],
  "ciscoUcsdConfig" : [ ],
  "digitalOceanConfig" : [ ],
  "profitBricksConfig" : [ ],
  "awsConfig" : [ {
    "id" : "462b263f-858b-437d-a9ac-95a0a63ed2f2",
    "service" : "Config",
    "modelIndex" : "AwsConfig",
    "uri" : "/config/api/awsConfigs/462b263f-858b-437d-a9ac-95a0a63ed2f2"
  } ],
  "googleComputeConfig" : [ ],
  "softLayerConfig" : [ ],
  "resourceSelectionRules" : [ ],
  "hostScalingRule" : [ ]
}

To use a host group, it must be associated with a ResourceSelectionRule. You can create a new ResourceSelectionRule as follows.

Request:

POST /api/cloudProviders/resourceSelectionRules
Accept: application/json
Authorization: NIRMATA-API <key>

Discover the REST API schema

The Nirmata REST API schema can be queried using the HTTP OPTIONS method. Here is a query and JQ filter to obtain all endpoints (model classes):

Request:

curl -X OPTIONS -H "Accept: application/json" -H "Authorization: NIRMATA-API <key>" https://nirmata.io/config/api | jq ".modelClasses | .[] .modelIndex"

Response:

"Root"
"Application"
"EnvironmentType"
"ContainerType"
"ResourceSelectionPolicy"
"ResourceSelectionRule"
"CloudProvider"
"HostGroup"
"Host"
"Container"
"Service"
"Environment"
"ServiceInstance"
"ServicePort"
"ServiceSpec"
"Registry"
"LaunchConfiguration"
"PortRange"
"VSphereConfig"
"OpenStackConfig"
"WebHook"
"ScalingPolicy"
"DesiredService"
"ScalingRule"
"VCloudConfig"
"ServiceInstanceAction"
"ServiceAffinityRule"
"ServiceScalingRule"
"RoutingPolicy"
"RoutingRule"
"GatewayRoute"
"GatewayPolicy"
"GatewayRule"
"AzureConfig"
"DesiredServiceAction"
"PrivateCloud"
"CiscoIcfConfig"
"CiscoUcsdConfig"
"HealthCheck"
"ClusterNode"
"Cluster"
"UpdatePolicy"
"ImageUpdateEvent"
"GatewayConfig"
"ContainerAction"
"DesiredServiceLabelSelector"
"LabelSelectorItem"
"EnvironmentVariable"
"HostAction"
"DigitalOceanConfig"
"ProfitBricksConfig"
"AwsConfig"
"HostScalingRule"

Discover attributes and relations

You can query a single class, to get its attributes and relations.

Request:

curl -X OPTIONS -H "Accept: application/json" -H "Authorization: NIRMATA-API <key>" https://nirmata.io/config/api/ContainerType

Response Body:

{
  "name" : "Config",
  "id" : "d05f7751-8dae-4733-9e14-601d6f3516b3",
  "rootIndex" : "Root",
  "modelClasses" : [ {
    "modelIndex" : "ContainerType",
    "uri" : "/config/api/containerTypes",
    "methods" : [ "OPTIONS", "GET", "POST", "DELETE", "PUT" ],
    "apiLabel" : "containerTypes",
    "isDeleteable" : true,
    "keyField" : "name",
    "parents" : [ "Root" ],
    "attributes" : [ {
      "name" : "name",
      "type" : "String",
      "isRequired" : true,
      "uniqueScope" : "PARENT",
      "isKey" : false,
      "length" : 0
    }, {
      "name" : "description",
      "type" : "String",
      "isRequired" : false,
      "uniqueScope" : "NONE",
      "isKey" : false,
      "length" : 0
    }, {
      "name" : "cpuShares",
      "type" : "Integer",
      "isRequired" : false,
      "uniqueScope" : "NONE",
      "isKey" : false,
      "min" : 0,
      "max" : 1024,
      "default" : 0
    }, {
      "name" : "memory",
      "type" : "Integer",
      "isRequired" : false,
      "uniqueScope" : "NONE",
      "isKey" : false,
      "min" : 0,
      "max" : 64000,
      "default" : 0
    } ],
    "relations" : [ {
      "name" : "resourceSelectionRules",
      "type" : "Reference",
      "relationClass" : "ResourceSelectionRule",
      "cardinality" : {
        "min" : 0,
        "type" : "zeroOrMore"
      },
      "isMany" : true,
      "relationField" : "containerTypes",
      "isStrongReference" : false,
      "uri" : "/config/api/containerTypes/{id}/resourceSelectionRules",
      "methods" : [ "OPTIONS", "GET" ]
    }, {
      "name" : "services",
      "type" : "Reference",
      "relationClass" : "Service",
      "cardinality" : {
        "min" : 0,
        "type" : "zeroOrMore"
      },
      "isMany" : true,
      "relationField" : "containerType",
      "isStrongReference" : false,
      "uri" : "/config/api/containerTypes/{id}/services",
      "methods" : [ "OPTIONS", "GET" ]
    } ]
  } ]
}