ZeroRobot API documentation version 0.0.1
API of the ZeroRobot, used for management and communication between ZeroRobots
Extended documentation
/blueprints
A blueprint is a description of which service you want to create and what action you want to add to a task list.
Execute a blueprint on the ZeroRobot
post /blueprints
Execute a blueprint on the ZeroRobot
Body
Media type: application/json
Type: object
Properties- content: required (object)
Example:
{
"content": {
"node__node1": {
"ip": "192.168.1.10",
"hostname": "node1"
},
"actions": {
"template": "node",
"service": "node1",
"action": "start"
}
}
}HTTP status code 200
Blueprint executed successfully Which mean all the service have been created and all actions added to the task list
Body
Media type: application/json
Type: array of Task
Items: Task
- action_name: required (string)
- args: (object)
- template_name: required (string)
- service_name: required (string)
- service_guid: required (string)
- guid: required (string)
unique ID of the task
- state: required (one of new, ok, running, error)
a task that is waiting to be executed is in state new. a task that being executed is in state running a task that executed successfully is in state ok a task that failed to execute and/or is being retried is in state error.
- created: required (integer)
timestamp at the time the task was created
- duration: (number)
duration of the execution of the task
- eco: (object)
In case the task failed with an exception, description of the exception
- appname: required (string)
- epoch: required (integer)
- errormessagePub: required (string)
- type: required (string)
- state: required (string)
- data: (object)
- jid: required (integer)
- masterjid: required (integer)
- errormessage: required (string)
- uniquekey: required (string)
- category: required (string)
- exceptionclassname: required (string)
- funcfilename: required (string)
- closetime: required (integer)
- level: required (integer)
- _limit: required (integer)
- lasttime: required (integer)
- code: required (string)
- guid: required (string)
- tags: required (string)
- funclinenr: required (integer)
- _traceback: required (string)
- funcname: required (string)
- pid: required (integer)
- occurrences: required (integer)
- result: (string)
serialized version of the result of the task
/templates
Templates are the source of the services. A service is just an instance of a template. To be able to create services, you need to first make some template available to the ZeroRobot by cloning a git repository that contains template. Once the templates are available, you can send blueprint with the description of which service to create.
List all the templates available to the ZeroRobot
Clone a template repository and make the templates available to the ZeroRobot
get /templates
List all the templates available to the ZeroRobot
HTTP status code 200
Body
Media type: application/json
Type: array of Template
Items: Template
- uid: required (string)
This is the unique identifier of a template. A tempate UID is identify by the url fo the git repository from where it comes from. There are different informations extracted from
- the host
- the account
- the repository name
- the name of the template itself
- a version
- host: required (string)
- account: required (string)
- repository: required (string)
- name: required (string)
- version: required (string)
post /templates
Clone a template repository and make the templates available to the ZeroRobot
Body
Media type: application/json
Type: object
Properties- url: required (string)
URL of the git repository to clone. Need to be under one of these format
- git@github.com:account/repository.git
- https://github.com/account/repository.git
- branch: (string - default: master)
branch of the repository to clone. If not specified, default to master
Example:
{
"url": "https://github.com/account/repository.git",
"branch": "master"
}HTTP status code 201
Template successfully added
Body
Media type: application/json
Type: array of Template
Items: Template
- uid: required (string)
This is the unique identifier of a template. A tempate UID is identify by the url fo the git repository from where it comes from. There are different informations extracted from
- the host
- the account
- the repository name
- the name of the template itself
- a version
- host: required (string)
- account: required (string)
- repository: required (string)
- name: required (string)
- version: required (string)
/services
Services are the core of the ZeroRobot. It is the services that hold state, data and execute actions.
List all the services known by the ZeroRobot.
create a new service
get /services
List all the services known by the ZeroRobot.
Query Parameters
- name: (string)
Filter on the name of the service
Example:
myservicename - template_uid: (string)
Filter on the complete template UID of the service
Example:
github.com/jumpscale/0-robot/node/0.0.1 - template_host: (string)
Filter on the host part of the template UID of the service
Example:
github.com - template_account: (string)
Filter on the account part of the template UID of the service
Example:
jumpscale - template_repo: (string)
Filter on the repository part of the template UID of the service
Example:
0-robot - template_name: (string)
Filter on the name part of the template UID of the service
Example:
node - template_version: (string)
Filter on the version part of the template UID of the service
Example:
0.0.1
HTTP status code 200
Body
Media type: application/json
Type: array of Service
Items: Service
- template: required (string)
This is the UID of a template
- version: required (string)
- guid: required (string)
- name: required (string)
- state: required (array of ServiceState)
Items: ServiceState
- category: required (string)
- tag: required (string)
- state: required (one of ok, error, warning, skipped)
Example:
{ "category": "network", "tag": "local-tcp-443", "state": "ok" }
post /services
create a new service
Body
Media type: application/json
Type: object
Properties- template: required (string)
This is UID of a template
- name: (string)
- data: (object)
Instance data used to create the service
Example:
{
"template": "github.com/jumpscale/0-robot/node/1.0.1",
"name": "vm1",
"data": {
"cpu_nr": 2,
"memory": 1024
}
}HTTP status code 201
Service created successfully
Headers
- Location: required (string)
URL to the created service resource
Body
Media type: application/json
Type: object
Properties- template: required (string)
This is the UID of a template
- version: required (string)
- guid: required (string)
- name: required (string)
- state: required (array of ServiceState)
Items: ServiceState
- category: required (string)
- tag: required (string)
- state: required (one of ok, error, warning, skipped)
Example:
{ "category": "network", "tag": "local-tcp-443", "state": "ok" }
Example:
{
"guid": "7040fda3-08e1-4109-829c-925a907809f9",
"template": "github.com/jumpscale/0-robot/node/0.0.1",
"version": "1.0.1",
"name": "node1",
"state": [
{
"category": "network",
"tag": "local-tcp-6379",
"state": "ok"
},
{
"category": "network",
"tag": "local-http-80",
"state": "ok"
},
{
"category": "data",
"tag": "db",
"state": "ok"
}
]
}HTTP status code 400
Bad request. Could be because the template asked doesn't exist or the request is not properly formatted body: type: Error
HTTP status code 409
Conflict, a service with this name already exists in this ZeroRobot.
Get the detail of a service
Upgrade a service from one version to another
Delete a service
get /services/{service_guid}
Get the detail of a service
URI Parameters
- service_guid: required (string)
HTTP status code 200
Body
Media type: application/json
Type: object
Properties- template: required (string)
This is the UID of a template
- version: required (string)
- guid: required (string)
- name: required (string)
- state: required (array of ServiceState)
Items: ServiceState
- category: required (string)
- tag: required (string)
- state: required (one of ok, error, warning, skipped)
Example:
{ "category": "network", "tag": "local-tcp-443", "state": "ok" }
Example:
{
"guid": "7040fda3-08e1-4109-829c-925a907809f9",
"template": "github.com/jumpscale/0-robot/node/0.0.1",
"version": "1.0.1",
"name": "node1",
"state": [
{
"category": "network",
"tag": "local-tcp-6379",
"state": "ok"
},
{
"category": "network",
"tag": "local-http-80",
"state": "ok"
},
{
"category": "data",
"tag": "db",
"state": "ok"
}
]
}HTTP status code 404
Service with this guid not found
Body
Media type: application/json
Type: object
Properties- code: required (integer)
error code
- message: required (string)
Human friendly error message
- stack_trace: (string)
optional stack_trace attached with the error.
put /services/{service_guid}
Upgrade a service from one version to another
URI Parameters
- service_guid: required (string)
Body
Media type: application/json
Type: object
Properties- template: required (string)
UID of a template of the new version
Example:
{
"template": "github.com/jumpscale/0-robot/node/0.0.2"
}HTTP status code 200
Service upgraded successfully
Body
Media type: application/json
Type: object
Properties- template: required (string)
This is the UID of a template
- version: required (string)
- guid: required (string)
- name: required (string)
- state: required (array of ServiceState)
Items: ServiceState
- category: required (string)
- tag: required (string)
- state: required (one of ok, error, warning, skipped)
Example:
{ "category": "network", "tag": "local-tcp-443", "state": "ok" }
Example:
{
"guid": "7040fda3-08e1-4109-829c-925a907809f9",
"template": "github.com/jumpscale/0-robot/node/0.0.1",
"version": "1.0.1",
"name": "node1",
"state": [
{
"category": "network",
"tag": "local-tcp-6379",
"state": "ok"
},
{
"category": "network",
"tag": "local-http-80",
"state": "ok"
},
{
"category": "data",
"tag": "db",
"state": "ok"
}
]
}HTTP status code 404
Service with this guid not found or template version not found
Body
Media type: application/json
Type: object
Properties- code: required (integer)
error code
- message: required (string)
Human friendly error message
- stack_trace: (string)
optional stack_trace attached with the error.
List all the possible action a service can do.
A task list is all the actions that are scheduled for a service
Return all the action in the task list
Add a task to the task list
get /services/{service_guid}/task_list
Return all the action in the task list
URI Parameters
- service_guid: required (string)
Query Parameters
- all: required (string)
If specified, return also the tasks that are done. If not specified, only return the task waiting to be executed type: bool required: false default: false
HTTP status code 200
Body
Media type: application/json
Type: array of Task
Items: Task
- action_name: required (string)
- args: (object)
- template_name: required (string)
- service_name: required (string)
- service_guid: required (string)
- guid: required (string)
unique ID of the task
- state: required (one of new, ok, running, error)
a task that is waiting to be executed is in state new. a task that being executed is in state running a task that executed successfully is in state ok a task that failed to execute and/or is being retried is in state error.
- created: required (integer)
timestamp at the time the task was created
- duration: (number)
duration of the execution of the task
- eco: (object)
In case the task failed with an exception, description of the exception
- appname: required (string)
- epoch: required (integer)
- errormessagePub: required (string)
- type: required (string)
- state: required (string)
- data: (object)
- jid: required (integer)
- masterjid: required (integer)
- errormessage: required (string)
- uniquekey: required (string)
- category: required (string)
- exceptionclassname: required (string)
- funcfilename: required (string)
- closetime: required (integer)
- level: required (integer)
- _limit: required (integer)
- lasttime: required (integer)
- code: required (string)
- guid: required (string)
- tags: required (string)
- funclinenr: required (integer)
- _traceback: required (string)
- funcname: required (string)
- pid: required (integer)
- occurrences: required (integer)
- result: (string)
serialized version of the result of the task
post /services/{service_guid}/task_list
Add a task to the task list
URI Parameters
- service_guid: required (string)
Body
Media type: application/json
Type: object
Properties- action_name: required (string)
- args: (object)
Example:
{
"action_name": "start",
"args": {
"foo": "bar"
}
}HTTP status code 201
Task added to the task list successfully
Headers
- Location: required (string)
description URL to the created task resource
Body
Media type: application/json
Type: object
Properties- action_name: required (string)
- args: (object)
- template_name: required (string)
- service_name: required (string)
- service_guid: required (string)
- guid: required (string)
unique ID of the task
- state: required (one of new, ok, running, error)
a task that is waiting to be executed is in state new. a task that being executed is in state running a task that executed successfully is in state ok a task that failed to execute and/or is being retried is in state error.
- created: required (integer)
timestamp at the time the task was created
- duration: (number)
duration of the execution of the task
- eco: (object)
In case the task failed with an exception, description of the exception
- appname: required (string)
- epoch: required (integer)
- errormessagePub: required (string)
- type: required (string)
- state: required (string)
- data: (object)
- jid: required (integer)
- masterjid: required (integer)
- errormessage: required (string)
- uniquekey: required (string)
- category: required (string)
- exceptionclassname: required (string)
- funcfilename: required (string)
- closetime: required (integer)
- level: required (integer)
- _limit: required (integer)
- lasttime: required (integer)
- code: required (string)
- guid: required (string)
- tags: required (string)
- funclinenr: required (integer)
- _traceback: required (string)
- funcname: required (string)
- pid: required (integer)
- occurrences: required (integer)
- result: (string)
serialized version of the result of the task
Example:
{
"template_name": "github.com/account/repository/master/node.zero-os",
"service_name": "node1",
"service_guid": "10b0c69f-0f72-4e41-b146-4e10997024f8",
"action_name": "start",
"guid": "07f38c46-056b-420d-8964-6efd3f493fe5",
"state": "new",
"args": {
"foo": "bar"
},
"created": 1512038654
}Retrieve the detail of a task
get /services/{service_guid}/task_list/{task_guid}
Retrieve the detail of a task
URI Parameters
- service_guid: required (string)
- task_guid: required (string)
HTTP status code 200
Body
Media type: application/json
Type: object
Properties- action_name: required (string)
- args: (object)
- template_name: required (string)
- service_name: required (string)
- service_guid: required (string)
- guid: required (string)
unique ID of the task
- state: required (one of new, ok, running, error)
a task that is waiting to be executed is in state new. a task that being executed is in state running a task that executed successfully is in state ok a task that failed to execute and/or is being retried is in state error.
- created: required (integer)
timestamp at the time the task was created
- duration: (number)
duration of the execution of the task
- eco: (object)
In case the task failed with an exception, description of the exception
- appname: required (string)
- epoch: required (integer)
- errormessagePub: required (string)
- type: required (string)
- state: required (string)
- data: (object)
- jid: required (integer)
- masterjid: required (integer)
- errormessage: required (string)
- uniquekey: required (string)
- category: required (string)
- exceptionclassname: required (string)
- funcfilename: required (string)
- closetime: required (integer)
- level: required (integer)
- _limit: required (integer)
- lasttime: required (integer)
- code: required (string)
- guid: required (string)
- tags: required (string)
- funclinenr: required (integer)
- _traceback: required (string)
- funcname: required (string)
- pid: required (integer)
- occurrences: required (integer)
- result: (string)
serialized version of the result of the task
Example:
{
"template_name": "github.com/account/repository/master/node.zero-os",
"service_name": "node1",
"service_guid": "10b0c69f-0f72-4e41-b146-4e10997024f8",
"action_name": "start",
"guid": "07f38c46-056b-420d-8964-6efd3f493fe5",
"state": "new",
"args": {
"foo": "bar"
},
"created": 1512038654
}HTTP status code 404
Not task found in the task list with this guid
Body
Media type: application/json
Type: object
Properties- code: required (integer)
error code
- message: required (string)
Human friendly error message
- stack_trace: (string)
optional stack_trace attached with the error.