Skip to content

API

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

#Lighthouse Remote API

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

Contents:

  1. Docker Control
    1. Exposed endpoints
    2. Examples
  2. Authentication
    1. Exposed endpoints
    2. Examples
  3. Users and Permissions
    1. Exposed endpoints
    2. Examples
  4. Beacons
    1. Exposed endpoints
    2. Examples
  5. Aliases
    1. Exposed endpoints
    2. Examples
  6. Applications
    1. Exposed endpoints

##Docker Control API ###Exposed endpoints

These endpoints forward a request to a Docker instance. Note that:

  • The HostAlias parameter serves as a lookup to the instance’s address.
  • The DockerEndpoint parameter is exactly the request which is sent to the Docker instance.
  • The Payload JSON field is exactly the HTTP request body which is sent to the Docker instance.

See the Docker API for a full list of Docker endpoints.

GET /<HostAlias>/d/<DockerEndpoint> HTTP/1.1
POST /<HostAlias>/d/<DockerEndpoint> HTTP/1.1
Content-Type: application/json

{
    "Payload": "<Docker Request Body>"
}
PUT /<HostAlias>/d/<DockerEndpoint> HTTP/1.1
Content-Type: application/json

{
    "Payload": "<Docker Request Body>"
}
DELETE /<HostAlias>/d/<DockerEndpoint> HTTP/1.1

###Responses: The server will return one of two categories of responses:

  • Status code in the 200 range – these are success responses and return exactly the Docker response.
  • Status code in the 300-500 range – these are error responses and return a JSON error message:
    • Error: The source of the error. For example: docker, control, postgres, etc.
    • Message: An explanation of the error.

###Examples:

A successful GET request:

Request:

GET /a_valid_host/d/version HTTP/1.1

Response:

HTTP/1.1 200 OK
Content-Type: application/json

{ 
    "ApiVersion":"1.12",
    "Arch":"amd64",
    "GitCommit":"990021a",
    "GoVersion":"go1.2.1",
    "KernelVersion":"3.13.0-37-generic",
    "Os":"linux",
    "Version":"1.0.1"
}

A successful POST request

Request:

POST /a_valid_host/d/containers/create HTTP/1.1

{
    "Payload": "<Docker Create Body>"
}

Response:

HTTP/1.1 201 Created
Content-Type: application/json

{ 
    "Id":"e90e34656806",
    "Warnings":[]
}

A failed request to an invalid Docker endpoint

Request:

GET /valid_host/d/bad_endpoint HTTP/1.1

Response:

HTTP/1.1 404 Not Found
Content-Type: application/json

{ 
    "Error":"docker",
    "Message":"404 Not Found"
}

A failed request to an invalid host

Request:

GET /bad_host/d/valid_endpoint HTTP/1.1

Response:

HTTP/1.1 500 Internal Server Error
Content-Type: application/json

{ 
    "Error":"control",
    "Message":"GET request failed"
}

A failed request to a valid endpoint with a server error

Request:

GET /valid_host/d/valid_endpoint HTTP/1.1

Response:

HTTP/1.1 500 Internal Server Error
Content-Type: application/json

{ 
    "Error":"postgres",
    "Message":"Database lookup failed"
}

[TOP]

##Authentication API ###Exposed endpoints

POST /login HTTP/1.1
Content-Type: application/json

{
    "Email":"<Email>",
    "Password":"<Password>"
}
GET /logout HTTP/1.1

###Examples:

Successfully log into the application:

POST /login HTTP/1.1

{
    "Email":"[email protected]",
    "Password":"correct_password"
}

Response:

HTTP/1.1 200 OK
Content-Type: application/json

true

Log in failure due to bad account information:

Request:

POST /login HTTP/1.1

{
    "Email":"[email protected]",
    "Password":"wrong_password"
}

Response:

HTTP/1.1 200 OK
Content-Type: application/json

false

Log out of the application:

Request:

GET /logout HTTP/1.1

Response:

HTTP/1.1 200 OK
Content-Type: application/json

[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]

##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"
}

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
[ "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
[ "127.0.0.1:5001/v1.12" ]

[TOP]

##Beacons 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]

##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