# ZeroRobot API documentation version 0.0.1

API of the ZeroRobot, used for management and communication between ZeroRobots

### Extended documentation

https://github.com/Jumpscale/0-robot/tree/master/docs

### /blueprints

A blueprint is a description of which service you want to create and what action you want to add to a task list.

#### /blueprints post

post

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.

#### /templates get post

get

List all the templates available to the ZeroRobot

post

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.

#### /services get post

get

List all the services known by the ZeroRobot.

post

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.

#### /services/{service_guid} get put delete

get

Get the detail of a service

put

Upgrade a service from one version to another

delete

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.

#### delete /services/{service_guid}

Delete a service

### URI Parameters

- service_guid: required (string)

## HTTP status code 204

Service deleted successfully

#### /services/{service_guid}/actions get

get

List all the possible action a service can do.

#### get /services/{service_guid}/actions

List all the possible action a service can do.

### URI Parameters

- service_guid: required (string)

## HTTP status code 200

### Body

Media type: application/json

Type: array of Action

Items: Action

- name: required (string)
- arguments: (array of )

#### /services/{service_guid}/task_list get post

A task list is all the actions that are scheduled for a service

get

Return all the action in the task list

post

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
    }

#### /services/{service_guid}/task_list/{task_guid} get

get

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.