AMP Cluster REST API

Overview and Design Goals

This document details the beta Cluster API it currently covers only the initial use-cases. Much longer term, we hope that it will become (or inform) the basis of the API for “truly clustered AMP” with features such as auto-sharding.

API Documentation

Authentication

The Authentication method used is basic authentication, with credentials set through the AMP Cluster blueprint. For making API requests, the authentication username and password should be set in the request header. To do this in curl for example:

curl --user name:password http://endpoint/v1/cluster/version

Version: GET /v1/cluster/version

Returns:

• 200: Status ok

Response:

{
    "version": "1.9.1"    
}

Deploy an app: POST /v1/cluster/applications?tagName=tagValue

Returns:

• 201: if created

The request body is a normal YAML app, e.g.:

services:
- type: org.apache.brooklyn.entity.machine.MachineEntity

Example response:

{
    "kind": "ClusterApplication",
    "applicationId": "afiejafefil",
    "ampNodeUri": "https://amp1.example.org",
    "labels": { "tagName": "tagValue" },
    "creationDate": "2017-03-29T21:31:02+0000"
}

Listing of apps

All apps: GET /v1/cluster/applications/

Returns:

• 200: json for all the apps

Example response:

{
    "kind": "ClusterApplicationList",
    "items": [
        {
            "kind": "ClusterApplication",
            "applicationId": "afiejafefil",
            "ampNodeUri": "https://amp1.example.org",
            "creationDate": "2017-03-29T21:31:02+0000"
            "labels": {
                "test-label": "test-label",
                "test-label2": "test-company"
            }
        }
    ]
}

Single app: GET /v1/cluster/applications/${app-id}

Returns:

• 200: json for the given app
• 404 if not found

Example response:

{
    "kind": "ClusterApplication",
    "applicationId": "ruf89yeoy8",
    "ampNodeUri": "http://104.155.106.130:8081",
    "creationDate": "2017-05-17T13:59:24+0000",
    "labels": {
        "test-label": "test-label",
        "test-label2": "test-company"
    }
}

Search for apps: GET /v1/cluster/applications?filter=label [in|matches] ([value1,value2|regex])&filter=...

Example searches:

/v1/cluster/applications?filter=department in (development,finance)
/v1/cluster/applications?filter=testLabel in (.+test)
/v1/cluster/applications?filter=department in (development,finance)&testLabel in (.+test)

Returns:

• 200: json for the matching apps (including empty list if no matches)
• 400: if invalid regex

Example response:

{
    "kind": "ClusterApplication",
    "applicationId": "ruf89yeoy8",
    "ampNodeUri": "http://104.155.106.130:8081",
    "creationDate": "2017-05-17T13:59:24+0000",
    "labels": {
        "test-label": "test-label",
        "test-label2": "test-company"
    }
}

Catalog management

These operations affect all Worker AMPs in the cluster.

Add YAML to Catalog: POST /v1/cluster/catalog

Returns:

• 201: if created

The request body is a normal YAML catalog item, e.g.:

brooklyn.catalog:
  id: my-new-app
  version: 1.0.0
  itemType: entity
  item:
    type: org.apache.brooklyn.entity.machine.MachineEntity

Request headers:

• Content-Type: application/x-yaml

Response is a cut-down version of what AMP returns currently:

Example response:

{
    "kind": "CatalogItemIdList",
    "items": [
        "my-new-app:1.0.0"
    ]
}

Add zip/bundle to Catalog: POST /v1/cluster/catalog

Returns:

• 201: if created

The request body is zip or bundle (as with AMP).

Request headers:

• Content-Type: application/x-zip

Response is the same as for adding yaml-based catalog items (i.e. a list of the catalog item ids that were added).

Managing list of Worker AMPs (Internal)

This part of the API is potentially temporary; it may well be moved into an external placement strategy; this is internal only.

Add Worker AMP to Cluster: PUT /v1/cluster/nodes/${id}

Returns:

• 200: if joined successfully

Example request body:

{
    "uri": "https://amp2.example.org",
    "username": "amp",
    "password": "pa55wOrd"
}

Remove Worker AMP from Cluster: DELETE /v1/cluster/nodes/${id}

Returns:

• 200: if deleted successfully
• 404: if AMP not known about

List Worker AMPs: GET /v1/cluster/nodes

Returns:

• 200

Example response:

{
    "kind": "ClusterNodeList",
    "items": [
        {
            "kind": "ClusterNode",
            "uri": "https://amp1.example.org"
        },
        {
            "kind": "ClusterNode",
            "uri": "https://amp2.example.org"
        }
    ]
}