HTTP methods for RESTful services are discussed below.
- GET retrieves information or resources.
- POST can either create, update resources, or take action.
- PUT is the same as POST for this.
- DELETE will take action and typically be STOP or DELETE.
Engine authentication
The controller creates an agent by creating a security token upon registration of engine instances. The agent or engine instance will include its token in the "Authorization" request header using the Bearer scheme. The controller then creates an engine instance.
HTTP response codes
Errors will be returned as part of the HTTP response message. The response body will be in JSON format with the following fields:
- ErrorId, String: The error ID
- ErrorDescription, String: Information describing the type of error
- ErrorDetail: Any relevant information as part of the error such as IDs.
| HTTP Code | Description |
|---|
| 201 Created | Node registered correctly. Sent in Body. |
| 400 Bad Request | Request not in appropriate format or missing information. |
| 401 Not Authorized | The APIs are not authenticated. |
| 408 Client Timeout | The client timed out in sending information. The client can repeat the request. |
| 409 Conflict | Engine instance is already registered. |
| 415 Unsupported Media Type | The request sent a non supported payload type such as XML instead of JSON. |
| 429 Too Many Requests | The server has too many requests currently. The server will use the Header Retry-After with seconds to try again. This will follow https://tools.ietf.org/html/rfc6585 |
| 500 Internal Error | There should be no 500 errors. |
Engine instance APIs
Engines can be managed through the API. For more details, see the engine and engine_instance endpoints on this page.
Host APIs
| HTTP Method | API | Description |
|---|
| POST | /host/register | The agent will use this to register a new host with the controller. The agent will send information about the host, the docker containers running and related statistics. |
| POST | /host/{HostId}/updatestatus | The agent will use this to update the controller with current information on the host including how much CPU, RAM, and GPU are available. The controller will respond with here are the containers to launch and containers to terminate. The controller may also tell the agent to terminate the host. |
| POST | /host{HostId}/terminate | Directs the controller to mark the host for deletion. This will be communicated to the host on the next update status request. |
| GET | /host/{HostId}/detail | Provides information about the host. |
| GET | /host/{HostId}/status | Provides information on the last status update for the host. |
| POST | /host/{HostId}/drain | Updates the host into draining status. No engines running on that host will be given new work. |
