Snap API

Snap exposes a list of RESTful APIs to perform various actions. All of Snap's API requests return JSON-formatted responses, including errors. Any non-2xx HTTP status code may contain an error message. All API URLs listed in this documentation have the endpoint:

http://localhost:8181

API Response Meta

Parameter	Description
code	HTTP status code
message	operation response message
type	operation type
version	API meta version

API Index

1. Authentication
2. Plugin API
3. Plugin Response Parameters
4. Plugin APIs and Examples
5. Metric API
6. Metric Response Parameters
7. Metric APIs and Examples
8. Task API
9. Task API Response Parameters
10. Task APIs and Examples
11. Tribe API
12. Tribe API Response Parameters
13. Tribe APIs and Examples

Authentication

Enabled in snapd

curl -L http://localhost:8181/v1/plugins

Not Authorized

curl -L http://localhost:8181/v1/plugins -u snap
Enter host password for user 'snap':

{
  "meta": {
    "code": 200,
    "message": "Plugin list returned",
    "type": "plugin_list_returned",
    "version": 1
  },
  "body": {}
}

Plugin API

Plugin RESTful APIs provide the functionality to load, unload and retrieve plugin information. You may see plugin APIs along with their request and response attributes as following:

Plugin Response Parameters

Parameter	Description
name	plugin name
version	plugin version
type	plugin type
signed	bool value to indicate if the plugin is signed or not
status	plugin status
loaded_timestamp	time plugin loaded

Plugin APIs and Examples

GET /v1/plugins: List all loaded plugins

Example Request

curl -L http://localhost:8181/v1/plugins

Example Response

{
  "meta": {
    "code": 200,
    "message": "Plugin list returned",
    "type": "plugin_list_returned",
    "version": 1
  },
  "body": {
    "loaded_plugins": [
      {
        "name": "mock",
        "version": 1,
        "type": "collector",
        "signed": false,
        "status": "loaded",
        "loaded_timestamp": 1447977606
      },
      {
        "name": "mock",
        "version": 2,
        "type": "collector",
        "signed": false,
        "status": "loaded",
        "loaded_timestamp": 1447977606
      },
      {
        "name": "passthru",
        "version": 1,
        "type": "processor",
        "signed": false,
        "status": "loaded",
        "loaded_timestamp": 1447977606
      },
      {
        "name": "file",
        "version": 3,
        "type": "publisher",
        "signed": false,
        "status": "loaded",
        "loaded_timestamp": 1447977607
      }
    ]
  }
}

GET /v1/plugins/:type/:name/:version: List plugins for the given type, name, and version

Example Request

curl -L http://localhost:8181/v1/plugins/collector/mock/1

Example Response

{
  "meta": {
    "code": 200,
    "message": "Plugin returned",
    "type": "plugin_returned",
    "version": 1
  },
  "body": {
    "name": "mock",
    "version": 1,
    "type": "collector",
    "signed": false,
    "status": "loaded",
    "loaded_timestamp": 1447977606
  }
}

POST /v1/plugins: Load a plugin

Example Request

curl -X POST -F plugin=@build/plugin/snap-collector-mock http://localhost:8181/v1/plugins

Example Response

{
  "meta": {
    "code": 201,
    "message": "Plugins loaded: mock(collector v1)",
    "type": "plugins_loaded",
    "version": 1
  },
  "body": {
    "loaded_plugins": [
      {
        "name": "mock",
        "version": 1,
        "type": "collector",
        "signed": false,
        "status": "loaded",
        "loaded_timestamp": 1448058077
      }
    ]
  }
}             

DELETE /v1/plugins/:type/:name/:version: Unload a plugin for the given type, name, and version

Example Request

curl -X DELETE http://localhost:8181/v1/plugins/collector/mock/1   

Example Response

{
  "meta": {
    "code": 200,
    "message": "Plugin successfully unloaded (mockv1)",
    "type": "plugin_unloaded",
    "version": 1
  },
  "body": {
    "name": "mock",
    "version": 1,
    "type": "collector"
  }
}     

GET /v1/plugins/:type/:name/:version/config: Retrieve the config for the given type, name, and version plugin

Example Request

curl -L http://localhost:8181/v1/plugins/collector/mock/1/config  

Example Response

{
  "meta": {
    "code": 200,
    "message": "Plugin config item retrieved",
    "type": "config_plugin_item_returned",
    "version": 1
  },
  "body": {}
}                    

Metric API

Snap metric APIs allow you to retrieve all or particular running metric information by invoking different APIs.

Metric Response Parameters

Parameter	Description
last_advertised_timestamp	last time the metric was used
namespace	metric namespace
version	metric version
policy.name	metric policy name
policy.type	policy data type
policy.default	flag to indicate if the policy is default one
policy.required	bool value to indicate if the policy is mandatory

Metric APIs and Examples

GET /v1/metrics: List all collected metrics

Example Request

curl -L http://localhost:8181/v1/metrics

Example Response

{
  "meta": {
    "code": 200,
    "message": "Metric",
    "type": "metrics_returned",
    "version": 1
  },
  "body": [
    {
      "last_advertised_timestamp": 1447977606,
      "namespace": "/intel/mock/*/baz",
      "version": 1
    },
    {
      "last_advertised_timestamp": 1447977606,
      "namespace": "/intel/mock/*/baz",
      "version": 2
    },
    {
      "last_advertised_timestamp": 1447977606,
      "namespace": "/intel/mock/bar",
      "version": 1
    },
    {
      "last_advertised_timestamp": 1447977606,
      "namespace": "/intel/mock/bar",
      "version": 2
    },
    {
      "last_advertised_timestamp": 1447977606,
      "namespace": "/intel/mock/foo",
      "version": 1,
      "policy": [
        {
          "name": "password",
          "type": "string",
          "required": true
        },
        {
          "name": "name",
          "type": "string",
          "default": "bob",
          "required": false
        }
      ]
    },
    {
      "last_advertised_timestamp": 1447977606,
      "namespace": "/intel/mock/foo",
      "version": 2,
      "policy": [
        {
          "name": "name",
          "type": "string",
          "default": "bob",
          "required": false
        },
        {
          "name": "password",
          "type": "string",
          "required": true
        }
      ]
    }
  ]
}

GET /v1/metrics/:namespace: List metrics given metric namespace

Example Request

curl -L http://localhost:8181/v1/metrics/intel/mock/*/baz

Example Response

  "meta": {
    "code": 200,
    "message": "Metric returned",
    "type": "metric_returned",
    "version": 1
  },
  "body": {
    "Metric": {
      "last_advertised_timestamp": 1447977606,
      "namespace": "/intel/mock/*/baz",
      "version": 2
    }
  }
}

Task API

Snap task APIs provide the functionality to create, start, stop, remove, enable, retrieve and watch scheduled tasks.

Task API Response Parameters

Parameter	Description
id	task id defined in UUID
name	task name
deadline	task timeout time
creation_timestamp	task creation time
last_run_timestamp	last running time of a task
hit_count	number of times a task ran
task_state	state of a task
workflow.collect.metrics	map of collected metrics
workflow.collect.config	map of collected metrics configurations
workflow.collect.process	array of processors used in the task
workflow.collect.process.publish	array of publishers used in the task

Task APIs and Examples

GET /v1/tasks: List all scheduled tasks

Example Request

curl -L http://localhost:8181/v1/tasks

Example Response

{
  "meta": {
    "code": 200,
    "message": "Scheduled tasks retrieved",
    "type": "scheduled_task_list_returned",
    "version": 1
  },
  "body": {
    "ScheduledTasks": [
      {
        "id": "f573affa-9326-44a8-a64c-7a0d803d5121",
        "name": "Task-f573affa-9326-44a8-a64c-7a0d803d5121",
        "deadline": "5s",
        "creation_timestamp": 1448004968,
        "last_run_timestamp": 1448004989,
        "hit_count": 20,
        "task_state": "Running"
      }
    ]
  }
}

GET /v1/tasks/:id: Retrieve a task given the task ID

Example Request

curl -L http://localhost:8181/v1/tasks/36cd2bbf-b9ab-495a-b8ab-d9f87fa9b88e

Example Response

{
  "meta": {
    "code": 200,
    "message": "Scheduled task (36cd2bbf-b9ab-495a-b8ab-d9f87fa9b88e) returned",
    "type": "scheduled_task_returned",
    "version": 1
  },
  "body": {
    "id": "36cd2bbf-b9ab-495a-b8ab-d9f87fa9b88e",
    "name": "Task-36cd2bbf-b9ab-495a-b8ab-d9f87fa9b88e",
    "deadline": "5s",
    "workflow": {
      "collect": {
        "metrics": {
          "/intel/mock/*/baz": {
            "version": 0
          },
          "/intel/mock/bar": {
            "version": 0
          },
          "/intel/mock/foo": {
            "version": 0
          }
        },
        "config": {
          "/intel/mock": {
            "password": "secret",
            "user": "root"
          }
        },
        "process": [
          {
            "plugin_name": "passthru",
            "plugin_version": 0,
            "publish": [
              {
                "plugin_name": "file",
                "plugin_version": 0,
                "config": {
                  "file": "/tmp/published"
                }
              }
            ]
          }
        ]
      }
    },
    "schedule": {
      "type": "simple",
      "interval": "1s"
    },
    "creation_timestamp": 1448315384,
    "last_run_timestamp": 1448318130,
    "hit_count": 2743,
    "task_state": "Running"
  }
}

GET /v1/tasks/:id/watch: Watch a task activity stream given a task ID

Example Request

curl -L http://localhost:8181/v1/tasks/f573affa-9326-44a8-a64c-7a0d803d5121/watch

Example Response

{"type":"stream-open","message":"Stream opened"}
{"type":"metric-event","message":"","event":[{"namespace":"/intel/mock/host0/baz","data":77,"source":"egu-mac01.lan","timestamp":"2015-11-19T23:45:41.075611868-08:00"},{"namespace":"/intel/mock/host1/baz","data":68,"source":"egu-mac01.lan","timestamp":"2015-11-19T23:45:41.075613646-08:00"},{"namespace":"/intel/mock/host2/baz","data":65,"source":"egu-mac01.lan","timestamp":"2015-11-19T23:45:41.075615188-08:00"},{"namespace":"/intel/mock/host3/baz","data":75,"source":"egu-mac01.lan","timestamp":"2015-11-19T23:45:41.075616491-08:00"},{"namespace":"/intel/mock/host4/baz","data":76,"source":"egu-mac01.lan","timestamp":"2015-11-19T23:45:41.075618022-08:00"},{"namespace":"/intel/mock/host5/baz","data":86,"source":"egu-mac01.lan","timestamp":"2015-11-19T23:45:41.075619501-08:00"},{"namespace":"/intel/mock/host6/baz","data":82,"source":"egu-mac01.lan","timestamp":"2015-11-19T23:45:41.075620247-08:00"},{"namespace":"/intel/mock/host7/baz","data":81,"source":"egu-mac01.lan","timestamp":"2015-11-19T23:45:41.075620942-08:00"},{"namespace":"/intel/mock/host8/baz","data":88,"source":"egu-mac01.lan","timestamp":"2015-11-19T23:45:41.075621674-08:00"},{"namespace":"/intel/mock/host9/baz","data":85,"source":"egu-mac01.lan","timestamp":"2015-11-19T23:45:41.075623754-08:00"},{"namespace":"/intel/mock/bar","data":69,"source":"egu-mac01.lan","timestamp":"2015-11-19T23:45:41.075630288-08:00"},{"namespace":"/intel/mock/foo","data":87,"source":"egu-mac01.lan","timestamp":"2015-11-19T23:45:41.075635543-08:00"}]}
{"type":"metric-event","message":"","event":[{"namespace":"/intel/mock/host0/baz","data":87,"source":"egu-mac01.lan","timestamp":"2015-11-19T23:45:42.075605924-08:00"},{"namespace":"/intel/mock/host1/baz","data":89,"source":"egu-mac01.lan","timestamp":"2015-11-19T23:45:42.075609242-08:00"},{"namespace":"/intel/mock/host2/baz","data":84,"source":"egu-mac01.lan","timestamp":"2015-11-19T23:45:42.075611747-08:00"},{"namespace":"/intel/mock/host3/baz","data":82,"source":"egu-mac01.lan","timestamp":"2015-11-19T23:45:42.075613786-08:00"}...

POST /v1/tasks: Create a task with the JSON input

Example Request

curl -vXPOST http://localhost:8181/v1/tasks -d @../examples/tasks/mock-file.json --header "Content-Type: application/json"

Example Response

{
  "meta": {
    "code": 201,
    "message": "Scheduled task created (15d4e09c-b4ab-4e92-b85e-9d9697212632)",
    "type": "scheduled_task_created",
    "version": 1
  },
  "body": {
    "id": "15d4e09c-b4ab-4e92-b85e-9d9697212632",
    "name": "Task-15d4e09c-b4ab-4e92-b85e-9d9697212632",
    "deadline": "5s",
    "workflow": {
      "collect": {
        "metrics": {
          "/intel/mock/*/baz": {
            "version": 0
          },
          "/intel/mock/bar": {
            "version": 0
          },
          "/intel/mock/foo": {
            "version": 0
          }
        },
        "config": {
          "/intel/mock": {
            "password": "secret",
            "user": "root"
          }
        },
        "process": [
          {
            "plugin_name": "passthru",
            "plugin_version": 0,
            "publish": [
              {
                "plugin_name": "file",
                "plugin_version": 0,
                "config": {
                  "file": "/tmp/published"
                }
              }
            ]
          }
        ]
      }
    },
    "schedule": {
      "type": "simple",
      "interval": "1s"
    },
    "creation_timestamp": 1448007501,
    "last_run_timestamp": -1,
    "task_state": "Stopped"
  }

PUT /v1/tasks/:id/start: Start a task given a task ID

Example Request

curl -XPUT http://localhost:8181/v1/tasks/7cd4b229-e12c-4b09-985a-b60e76daac90/start

Example Response

{
  "meta": {
    "code": 200,
    "message": "Scheduled task (7cd4b229-e12c-4b09-985a-b60e76daac90) started",
    "type": "scheduled_task_started",
    "version": 1
  },
  "body": {
    "id": "7cd4b229-e12c-4b09-985a-b60e76daac90"
  }
}             

PUT /v1/tasks/:id/stop: Stop a running task given a task ID

Example Request

curl -XPUT http://localhost:8181/v1/tasks/7cd4b229-e12c-4b09-985a-b60e76daac90/stop

Example Response

{
  "meta": {
    "code": 200,
    "message": "Scheduled task (7cd4b229-e12c-4b09-985a-b60e76daac90) stopped",
    "type": "scheduled_task_stopped",
    "version": 1
  },
  "body": {
    "id": "7cd4b229-e12c-4b09-985a-b60e76daac90"
  }
}      

DELETE /v1/tasks/:id: Remove a task from the scheduled task list given a task ID

Example Request

curl -X DELETE http://localhost:8181/v1/tasks/7cd4b229-e12c-4b09-985a-b60e76daac90  

Example Response

{
  "meta": {
    "code": 200,
    "message": "Scheduled task (7cd4b229-e12c-4b09-985a-b60e76daac90) removed",
    "type": "scheduled_task_removed",
    "version": 1
  },
  "body": {
    "id": "7cd4b229-e12c-4b09-985a-b60e76daac90"
  }
}

PUT /v1/tasks/:id/enable: Enable a disabled task given a task ID

Example Request

curl -X PUT http://localhost:8181/v1/tasks/84fd498b-9232-40b7-81bd-ac7e86b1f252/enable  

Example Response

{
  "meta": {
    "code": 500,
    "message": "Task must be disabled",
    "type": "error",
    "version": 1
  },
  "body": {
    "message": "Task must be disabled",
    "fields": {}
  }
}                      

Tribe API

Snap tribe APIs provide the functionality for managing tribe agreements and for tribe members to join or leave tribe contracts.

Tribe API Response Parameters

Parameter	Description
agreements.[agreement].name	agreement name
agreements.[agreement].plug_agreement	plugins loaded for the agreement
agreements.[agreement].task_agreement	agreement scheduled tasks
agreements.members	map of tribe members
agreements.members.[member].tags	map of node properties
agreements.members.[member].name	node name

Tribe APIs and Examples

GET /v1/tribe/agreements: List all tribe agreements

Example Request

curl -L http://localhost:8181/v1/tribe/agreements
curl -L http://localhost:8182/v1/tribe/agreements
curl -L http://localhost:8183/v1/tribe/agreements

Example Response

{
  "meta": {
    "code": 200,
    "message": "Tribe agreements retrieved",
    "type": "tribe_agreement_list_returned",
    "version": 1
  },
  "body": {
    "agreements": {
      "hot-agrement": {
        "name": "hot-agrement",
        "plugin_agreement": {
          "plugins": [
            {
              "name": "file",
              "version": 3,
              "type": 2
            }
          ]
        },
        "task_agreement": {},
        "members": {
          "hawaii": {
            "tags": {
              "rest_api_port": "8182",
              "rest_insecure": "",
              "rest_proto": "http"
            },
            "name": "hawaii"
          },
          "maui": {
            "tags": {
              "rest_api_port": "8183",
              "rest_insecure": "",
              "rest_proto": "http"
            },
            "name": "maui"
          },
          "seed": {
            "tags": {
              "rest_api_port": "8181",
              "rest_insecure": "",
              "rest_proto": "http"
            },
            "name": "seed"
          }
        }
      },
      "warm-agreement": {
        "name": "warm-agreement",
        "plugin_agreement": {},
        "task_agreement": {},
        "members": {
          "hawaii": {
            "tags": {
              "rest_api_port": "8182",
              "rest_insecure": "",
              "rest_proto": "http"
            },
            "name": "hawaii"
          },
          "maui": {
            "tags": {
              "rest_api_port": "8183",
              "rest_insecure": "",
              "rest_proto": "http"
            },
            "name": "maui"
          }
        }
      }
    }
  }
}

POST /v1/tribe/agreements: Create a new tribe agreement

Example Request

curl -X POST http://localhost:8182/v1/tribe/agreements -d '{"name":"cold-agreement"}'

Example Response

{
  "meta": {
    "code": 200,
    "message": "Tribe agreement created",
    "type": "tribe_agreement_created",
    "version": 1
  },
  "body": {
    "agreements": {
      "cold-agreement": {
        "name": "cold-agreement",
        "plugin_agreement": {},
        "task_agreement": {}
      },
      "hot-agrement": {
        "name": "hot-agrement",
        "plugin_agreement": {
          "plugins": [
            {
              "name": "file",
              "version": 3,
              "type": 2
            }
          ]
        },
        "task_agreement": {},
        "members": {
          "hawaii": {
            "tags": {
              "rest_api_port": "8182",
              "rest_insecure": "",
              "rest_proto": "http"
            },
            "name": "hawaii"
          },
          "maui": {
            "tags": {
              "rest_api_port": "8183",
              "rest_insecure": "",
              "rest_proto": "http"
            },
            "name": "maui"
          },
          "seed": {
            "tags": {
              "rest_api_port": "8181",
              "rest_insecure": "",
              "rest_proto": "http"
            },
            "name": "seed"
          }
        }
      }
    }
  }
}                         

GET /v1/tribe/agreements/:name: Retrieve a tribe agreement given the agreement name

Example Request

curl -L http://localhost:8183/v1/tribe/agreements/warm-agreement

Example Response

{
  "meta": {
    "code": 200,
    "message": "Tribe agreement returned",
    "type": "tribe_agreement_returned",
    "version": 1
  },
  "body": {
    "agreement": {
      "name": "warm-agreement",
      "plugin_agreement": {},
      "task_agreement": {},
      "members": {
        "hawaii": {
          "tags": {
            "rest_api_port": "8182",
            "rest_insecure": "",
            "rest_proto": "http"
          },
          "name": "hawaii"
        },
        "maui": {
          "tags": {
            "rest_api_port": "8183",
            "rest_insecure": "",
            "rest_proto": "http"
          },
          "name": "maui"
        }
      }
    }
  }
}

DELETE /v1/tribe/agreements/:name: Remove an agreement given the agreement name

Example Request

curl -X DELETE http://localhost:8183/v1/tribe/agreements/warm-agreement

Example Response

{
  "meta": {
    "code": 200,
    "message": "Tribe agreement deleted",
    "type": "tribe_agreement_deleted",
    "version": 1
  },
  "body": {
    "agreements": {
      "hot-agrement": {
        "name": "hot-agrement",
        "plugin_agreement": {
          "plugins": [
            {
              "name": "file",
              "version": 3,
              "type": 2
            }
          ]
        },
        "task_agreement": {},
        "members": {
          "hawaii": {
            "tags": {
              "rest_api_port": "8182",
              "rest_insecure": "",
              "rest_proto": "http"
            },
            "name": "hawaii"
          },
          "maui": {
            "tags": {
              "rest_api_port": "8183",
              "rest_insecure": "",
              "rest_proto": "http"
            },
            "name": "maui"
          },
          "seed": {
            "tags": {
              "rest_api_port": "8181",
              "rest_insecure": "",
              "rest_proto": "http"
            },
            "name": "seed"
          }
        }
      }
    }
  }
}                                   

PUT /v1/tribe/agreements/:name/join: Join a member node into an agreement given the agreement name

Example Request

curl -X PUT http://localhost:8183/v1/tribe/agreements/warm-agreement/join -d '{"member_name": "maui"}'

Example Response

{
  "meta": {
    "code": 200,
    "message": "Tribe agreement joined",
    "type": "tribe_agreement_joined",
    "version": 1
  },
  "body": {
    "agreement": {
      "name": "warm-agreement",
      "plugin_agreement": {},
      "task_agreement": {},
      "members": {
        "hawaii": {
          "tags": {
            "rest_api_port": "8182",
            "rest_insecure": "",
            "rest_proto": "http"
          },
          "name": "hawaii"
        },
        "maui": {
          "tags": {
            "rest_api_port": "8183",
            "rest_insecure": "",
            "rest_proto": "http"
          },
          "name": "maui"
        }
      }
    }
  }
}

DELETE /v1/tribe/agreements/:name/leave: Remove a member node from an agreement given the agreement name

Example Request

curl -X DELETE http://localhost:8183/v1/tribe/agreements/warm-agreement/leave -d '{"member_name": "maui"}'

Example Response

{
  "meta": {
    "code": 200,
    "message": "Tribe agreement left",
    "type": "tribe_agreement_left",
    "version": 1
  },
  "body": {
    "agreement": {
      "name": "warm-agreement",
      "plugin_agreement": {},
      "task_agreement": {},
      "members": {
        "hawaii": {
          "tags": {
            "rest_api_port": "8182",
            "rest_insecure": "",
            "rest_proto": "http"
          },
          "name": "hawaii"
        }
      }
    }
  }
}         

GET /v1/tribe/members: List all tribe members

Example Request

curl -L http://localhost:8183/v1/tribe/members

Example Response

{
  "meta": {
    "code": 200,
    "message": "Tribe members retrieved",
    "type": "tribe_member_list_returned",
    "version": 1
  },
  "body": {
    "members": [
      "hawaii",
      "seed",
      "maui"
    ]
  }
}

GET /v1/tribe/member/:name: List tribe member information given the node name

Example Request

curl -L http://localhost:8183/v1/tribe/member/maui

Example Response

{
  "meta": {
    "code": 200,
    "message": "Tribe member details retrieved",
    "type": "tribe_member_details_returned",
    "version": 1
  },
  "body": {
    "name": "maui",
    "plugin_agreement": "warm-agreement",
    "tags": {
      "rest_api_port": "8183",
      "rest_insecure": "",
      "rest_proto": "http"
    },
    "task_agreements": null
  }
}