Skip to content

API v0.2

Jump to bottom
cmbrose edited this page Apr 26, 2015 · 20 revisions

#Lighthouse Remote API v0.2

Note: Prepend all endpoints with /api/v0.2

All endpoints listed in v0.1 are supported in addition to the following:

Contents:

  1. Beacons
    1. Exposed endpoints
    2. Examples
  2. Aliases
    1. Exposed endpoints
    2. Examples
  3. Users
    1. Exposed endpoints
    2. Examples
  4. Applications
    1. Exposed endpoints

##Beacons API ###Exposed endpoints

These endpoints offer support for connecting to and updating running beacon instances

POST /beacons/create HTTP/1.1
Content-Type: application/json

{
    "Address": "<Beacon address>",
    "Token": "<Beacon token>"
}
PUT /beacons/token/{Instance} HTTP/1.1
Content-Type: application/json

"<Beacon Token>"
GET /beacons/list HTTP/1.1
GET /beacons/list/{Address} HTTP/1.1

###Examples:

Connect to a new beacon:

  • The beacon is located at example.com/mybeacon
  • Only the [email protected] can access the beacon's token

Request:

POST /beacons/create HTTP/1.1
Content-Type: application/json

{
    "Address": "example.com/mybeacon",
    "Token": "MY_TOKEN",
    "Alias": "MyBeacon"
}

Response:

HTTP/1.1 200 OK

Attempting to authorize a user to access an unknown beacon:

Request:

PUT /beacons/user/bad_docker_address/[email protected] HTTP/1.1

Response:

HTTP/1.1 400 BadRequest
databases: given key not found

Requesting a list of known beacons:

Request:

GET /beacons/list HTTP/1.1

Response:

HTTP/1.1 200 OK
[ 
    {
        "Alias" : "MyBeacon", 
        "Address" : "127.0.0.1:5002
    }
]

Requesting a list of instances connected to the beacon at 127.0.0.1:5001:

Request:

GET /beacons/list/127.0.0.1:5002 HTTP/1.1

Response:

HTTP/1.1 200 OK
[
    {
        "Alias" : "MyBeacon.boot2docker",
        "InstanceAddress" : "127.0.0.1:5001/v1.12",
        "Name" : "boot2docker",
        "CanAccessDocker" : true,
        "BeaconAddress" : "127.0.0.1:5002"
    }
]

[TOP]

##Aliases API ###Exposed endpoints

PUT /aliases/{Alias} HTTP/1.1

"Address"

###Examples:

Updating/creating a valid alias:

Request:

PUT /aliases/boot2docker HTTP/1.1

"127.0.0.1:5001/v1.12"

Response:

HTTP/1.1 200 OK

Updating/creating an invalid alias:

Request:

PUT /aliases/boot2docker HTTP/1.1

""

Response:

HTTP/1.1 400 BadRequest

[TOP]

##Users API ###Exposed endpoints

GET /users/list HTTP/1.1
GET /users/{Email} HTTP/1.1
PUT /users/{Email} HTTP/1.1
Content-Type: application/json

{
    "AuthLevel" : 42,
    "Password" : "updated password",
    "Beacons" : {
        "127.0.0.1:5002" : 2,
        "192.168.1.100" : -1
    }
}

Note all fields in the previous endpoint are optional.

POST /users/create HTTP/1.1
Content-Type: application/json

{
    "Email" : "[email protected]",
    "Password" : "N3w P@$$w0rd!!!"
}

An explanation of AuthLevels

There are 2 kinds of AuthLevels associated with all users:

  1. User AuthLevel - this allows a user to see or modify other users
  2. Resource AuthLevel - this allows a user to see or modify resources (like beacons)

User AuthLevels are unbounded in size. A user me see and modify another iff their AuthLevel is strictly greater than the other user. A user may always view and modify themselves.

Resource AuthLevels are a scale of 0 - 2:

  • 0 - can access the resource (e.g. get a beacon token)
  • 1 - can modify a resource (e.g. change token, add/remove users)
  • 2 - owner of resource (same as level 1, but only other owners may modify you)

A resource AuthLevel of -1 may also be specified in which case the user is removed from the resource.

In order to prevent users from giving themselves or other arbitrarily high AuthLevels, a user is only permitted to set AuthLevel <= their own AuthLevel (for both user and resource AuthLevels).

[TOP]

###Examples:

Unless otherwise noted, assume users "admin", "manager", and "employee" exist with AuthLevels 2, 1, 0 respectively and the request is made by "manager".

List all users:

Request

GET /users/list HTTP/1.1

Response

HTTP/1.1 200 OK
["manager", "employee"]

Get user information:

Request

GET /users/employee HTTP/1.1

Response

HTTP/1.1 200 OK
{
    "AuthLevel" : 0,
    "Permissions" : {
        "Beacons" : { }
    }
}

Get user information:

Request

GET /users/admin HTTP/1.1

Response

HTTP/1.1 404 NotFound

Update a user:

Request

After the request is made "employee" has

  • AuthLevel 1
  • Password "updated password"
  • Ownership of the beacon at "127.0.0.1:5002"
  • Revoked permissions for the beacon at "129.168.1.100"
PUT /users/employee HTTP/1.1
Content-Type: application/json

{
    "AuthLevel" : 1,
    "Password" : "updated password",
    "Beacons" : {
        "127.0.0.1:5002" : 2,
        "192.168.1.100" : -1
    }
}

Response

HTTP/1.1 200 OK

Create a new user

Request

POST /users/create HTTP/1.1
Content-Type: application/json

{
    "Email" : "intern",
    "Password" : "lol what is real life"
}

Response

HTTP/1.1 200 OK

[TOP]

##Applications API ###Exposed endpoints

For a more in-depth explanation as well as examples, please see the full applications documentation.

POST /applications/create?start=<Boolean>&forcePull=<Boolean>

{
    "Name" : "MyNewApplication",
    "Command" : { "... Docker command fields ..." },
    "Instances" : [
        "instance1.org",
        "instance2.com",
        "192.168.1.100:5000"
    ]
}
POST /applications/revert/<Id>?target=<DeploymentId>&forcePull=<Boolean>
POST /applications/start/<Id>
POST /applications/stop/<Id>
PUT /applications/update/<Id>?restart=<Boolean> [STREAM]

{
    "Command" : { "... Docker command fields ..." },
    "Add" : [ "instance3.org" ],
    "Remove" : [ "instance1.com" ]
}
GET /applications/list
GET /applications/list/<Id>?count=<Integer>

[TOP]

Clone this wiki locally