Applications API

Note ApplicationIds used in endpoints can be either names or Ids. Application names are enforced to be unique.

About Streams

All endpoints marked with [STREAM] may return streams of the following form. In all cases, if the returned status code is 200, a stream is returned. Otherwise an error of the standard form is returned.

Update Object

{
    Status   ("OK", "Warning", "Error", "Starting", "Complete", "Finalized")
    Method   ("GET", "POST", "PUT", "DELETE")
    Endpoint ("containers/create", ...)
    Message  ("", "<Warning Reason>, "<Endpoint>", ...)
    Code
    Instance ("myInstance.com:5000/v1.12")
    Item     (0 to Total)
    Total
}

• Warnings are not considered fatal to the request, the request will complete normally unless an Error is seen.
• If an Error appears in the stream, its cause can be found by looking at the message:

• If Message is "", the error was from Docker. The Code field will give Docker's status.
• Otherwise the error was from Lighthouse and is explained by the text in the field.

• Item's are appended to the stream when they complete, they may not be in numerical order.
• The last entry of any stream will have Status: Finalized. This update will always appear (even if no other updates appear) and the stream should not be considered complete until it is received.

Stream example

{"Status":"Starting", "Method":"DELETE", "Endpoint":"containers/my_app", "Message":"Deleting old container", "Code":0, "Instance":"", "Item":0, "Total":4}
{"Status":"OK", "Method":"DELETE", "Endpoint":"containers/my_app", "Message":"", "Code":404, "Instance":"instance0.com", "Item":0, "Total":4}
{"Status":"Warning", "Method":"DELETE", "Endpoint":"containers/my_app", "Message":"No such container", "Code":404, "Instance":"instance2.com", "Item":2, "Total":4}
{"Status":"Error", "Method":"DELETE", "Endpoint":"containers/my_app", "Message":"", "Code":400, "Instance":"instance1.com", "Item":1, "Total":4}
{"Status":"Error", "Method":"DELETE", "Endpoint":"containers/my_app", "Message":"host unreachable", "Code":500, "Instance":"instance3.com", "Item":3, "Total":4}
{"Status":"Complete", "Method":"DELETE", "Endpoint":"containers/my_app", "Message":"Deleting old container", "Code":0, "Instance":"", "Item":4, "Total":4}
{"Status":"Finalized", "Method":"", "Endpoint":"", "Message":"", "Code":0, "Instance":"", "Item":0, "Total":0}

Create a new application [STREAM]

Result

• The application "MyNewApplication" is created
• The current user is given ownership of the application (permissions can be modified using /users endpoints)
• The application is only started if the "Start" query parameter is set
• If "ForcePull" is set, instances will be instructed to pull images before running. Otherwise the endpoint will return an error if an instance is missing an image

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

{
    "Name" : "MyNewApplication",
    "Command" : { "... Docker command fields ..." },
    "Instances" : [
        "instance1.org",
        "instance2.com",
        "192.168.1.100:5000"
    ]
}

Return Codes

• 200: Request processed, check stream for errors
• 400: Missing or invalid parameter
• 500: Server error

Start an application [STREAM]

POST /applications/start/<Id>

Return Codes

• 200: Request processed, check stream for errors
• 403: Current user is not authorized to edit application
• 404: Unknown application
• 500: Server error

Stop an application [STREAM]

POST /application/stop/<Id>

Return Codes

• 200: Request processed, check stream for errors
• 403: Current user is not authorized to edit application
• 404: Unknown application
• 500: Server error

Update an application [STREAM]

Result

• "instance3.org" is added to the application and "instance1.com" is removed
• All existing containers of the application are removed and recreated
• The application resumes its original state (stopped or started)

Note

• If "Restart" is set, all instances containers are stopped and restarted
• Otherwise if "Command" is not given, running containers will not be stopped (unless they are removed from the application of course)

PUT /applications/update/<Id>?restart=<Boolean>

{
    "Command" : { "... Docker command fields ..." },
    "Add" : [ "instance3.org" ],
    "Remove" : [ "instance1.com" ]
}

Return Codes

• 200: Request processed, check stream for errors
• 204: Success, no deployment initiated
• 403: Current user is not authorized to edit application
• 404: Unknown application
• 500: Server error

Revert an application

Note

• If "Target" is >= 0 the application is reverted to the given Deployment Id.
• If "Target" is < 0 the application is reverted by that many deployments
• The default value of "Target" is -1

PUT /applications/revert/<Id>?target=<DeploymentId>&forcePull=<Boolean>

Return Codes

• 200: Request processed, check stream for errors
• 400: If target >= 0, target deployment is not associated with application. Otherwise not enough deployments to perform a rollback.
• 403: Current user is not authorized to edit application
• 404: Unknown application or target
• 500: Server error

List applications

GET /applications/list

Return Codes

• 200: Success
• 500: Server error

Example response Note

• "Date" may not be this nicely formatted, it depends how the database stores it
• "Creator" refers to the user that created the latest deployment, not the original creator

[
    {
        "Id": 1,
        "CurrentDeployment": 1,
        "Name": "myApplication",
        "Instances": [
            "127.0.0.1:5001/v1.12"
        ]
    }
]

Get application deployment history

GET /applications/list/<Id>?count=<Integer>

Return Codes

• 200: Success
• 404: Unknown application
• 500: Server error

Example response

Note

• "Count" or fewer deployments are returned
• "Id" refers to the DeploymentId, not the ApplicationId - these Ids may be used in reverts
• These will likely come in a sorted order (either earliest or latest first, again depending on the database)

[
    {
        "Id" : 42,
        "Creator" : "admin@gmail.com",
        "Date" : "03/14/15 9:26:53 PM",
        "Image" : "product:v1"
    },
    {
        "Id" : 41,
        "Creator" : "user@gmail.com",
        "Date" : "01/04/14 2:01:25 PM",
        "Image" : "product:v2"
    }
]