Set-Cookie:canopy-login-session=<COOKIE_VALUE>

200 OK
{
    "result" : "ok",
    "username" : <USERNAME>,
    "email" : <EMAIL>
}

200 OK
{
    "result" : "ok",
    "username" : "leela",
    "email" : "leela@planetexpress.com"
}

POST /api/logout

{
    "result" : "ok"
}

GET /api/user/self

{
    "result" : "ok",
    "validated" : <VALIDATED>,
    "username" : <USERNAME>,
    "email" : <EMAIL>,
}

POST /api/user/self
{
    "email" : <NEW_EMAIL>,
    "old_password" : <OLD_PASSWORD>,
    "new_password" : <NEW_PASSWORD>
}

{
    "result" : "ok",
    "username" : <USERNAME>,
    "email" : <EMAIL>,
}

200 OK
{
    "result" : "ok",
}

POST /api/create_devices
{
    "quanitity" : <QUANTITY>
    "friendly_names" : [<FRIENDLY_NAME>, ...]
}

{
    "result" : "ok",
    "count" : <COUNT>,
    "devices" : [ {
        "friendly_name" : <FRIENDLY_NAME>,
        "device_id" : <UUID>,
        "device_secret_key" : <DEVICE_SECRET_KEY>
    }, ... ]
}

TBD: Should there be a way to archive/suspend a device?

DELETE /api/device/<UUID>

DELETE /api/device/d5c827d2-1ba7-4da6-b87b-0864f0969fa8

DELETE /api/device/self

200 OK
{
    "result" : "ok",
}

GET /api/user/self/devices?
    filter=<FILTER>
    &sort=<SORT>
    &limit=<LIMIT>

<FILTER> is an expression encoded as a string that evaluates to a boolean value.

A <TERM> corresponds to a single boolean test. A "value test" has the form:

<VARIABLE> <RELATION> <VALUE>

temperature >= 50.8

A "variable presence test" has the form:

HAS <VARIABLE>

HAS humidity

The ! operator inverts the following TERM.

!(HAS humidity)
!(temperature < 10)

<TERM> && <TERM>
<TERM> || <TERM>

temperature >= 50.8 && temperature < 90.5

!(temperature >= 50.8 && temperature < 90.5) || HAS humidity

<SORT> is a sequence of comma-separated keys specifying the sort order. The highest priority key comes first, followed by tie breakers. By default ascending order is used. To sort by a key in descending order, add ! before the key. For sort order determination, a missing cloud variable comes before the minimum value (i.e. at the front of the list when ascending, at the end of the list when descending).

This example sorts by temperature (ascending) then, to break ties, humidity (descending)

temperature,!humidity

limit=<start>,<count>

limit=0,50

{
    "result" : "ok",
    "count" : <COUNT>,
    "devices" : [ {
        "device_id" : <UUID>,
        "friendly_name" : <FRIENDLY_NAME>,
        "status" : {
            "ws_connected" : <WS_CONNECTED>,
            "active_status" : <ACTIVE_STATUS>,
            "last_activity_time" : <LAST_ACTIVITY_TIME>,
        },
    }, ...  ]
}

GET /api/device/<UUID>?
    timestamps=<TIMESTAMPS>

GET /api/device/d5c827d2-1ba7-4da6-b87b-0864f0969fa8?timestamps=rfc3339

GET /api/device/self?
    timestamps=<TIMESTAMPS>

The /api/device/<UUID> form of the request obtains a specific device by UUID. The requester (i.e. the authenticated User or Device) must have permission to access the specified Device, otherwise an error will occur.

The second form of the request obtains the currently authenticated device (i.e. the device whose credentials were supplied via BASIC AUTH). It returns an error if User credentials are supplied.

TBD [If the provided device credentials are unknown to the remote, and the server supports anonymous devices, then a new anonymous device will be created. If the first form of the request is used, then an anonymous device will only be created if the UUID in the URI matches the UUID in the credentials, otherwise an error will occur.]

The following query parameters are accepted

POST /api/device/<UUID>
{
    "friendly_name" : string,
    "location_note" : string
}

All fields are optional and omitted fields will be left unchanged.

This may be combined with Add/Update Cloud Var Metadata and Update Cloud Var Values into a single request.

This request may be combined with Declare Cloud Variable and Set Cloud Variable Values into a single request.

Before using a Cloud Variable you must declare it, specifying its name, direction, datatype and other metadata properties. The first time a cloud variable name is declared for a particular device, a cloud variable gets created, but not set. Declaring a cloud variable is an idempotent operation, meaning that subsequent identical declarations will have no effect. However, attempts to redeclare a named cloud variable with different datatype or direction will fail unless you delete it first.

POST /api/device/<UUID>
{
    "var_decls" : {
        <VAR_DECL> : <VAR_PROPERTIES>,
        ...
    }
}

POST /api/device/d5c827d2-1ba7-4da6-b87b-0864f0969fa8
{
    "var_decls" : {
        "out float32 temperature" : { },
        "out float32 humidity" : { },
        "in int8 dimmer_brightness" : { },
        "in bool reboot_now" : { },
        ...
    }
}

A <VAR_DECL> is a string with the following format:

"<DIRECTION> <TYPE> <NAME>"

"out float32 temperature"

TBD reserved values?

The <VAR_PROPERTIES> is an object specifying additional metadata for the cloud variable. At this time it must be an empty object {} reserved for future use.

This request may be combined with Update Device Properties and Update Cloud Var Value into a single request.

To set Cloud Variable values, use:

POST /api/device/<UUID>
{
    "vars" : {
        <VAR_NAME> : value,
        ...
    }
}

POST /api/device/d5c827d2-1ba7-4da6-b87b-0864f0969fa8
{
    "vars" : {
        "temperature" : 43.0,
        "humidity" : 32.41,
        "dimmer_level" : 4,
        "happy" : true
        ...
    }
}

The datatype of the value must match the datatype of the Cloud Variable.

This request may be combined with Update Device Properties and Declare Cloud Variable into a single request.

GET /api/user/self/orgs

GET /api/org/<ORG_NAME>/members

Only members of the organization are authorized to make this request.

POST /api/org/<ORG_NAME>/members
{
    "add_member" : {
       "user" : <USERNAME_OR_EMAIL>,
    }
}

Only owners of the Organization are authorized to make this request.

POST /api/org/<ORG_NAME>/members
{
    "remove_member" : <USERNAME_OR_EMAIL>,
}

This request will also remove the member from all of the Organization's Teams that they are on.

Only owners of the Organization are authorized to make this request.

This request may be combined with an Add Member request, in which case addition occurs before removal.

GET /api/org/<ORG_NAME>/teams

Only members of the Organization are authorized to make this request.

POST /api/org/<ORG_NAME>/create_team
{
    "name" : <TEAM_NAME>
    "url_alias" : <TEAM_URL_ALIAS>
}

Only owners of the Organization are authorized to make this request.

DELETE /api/org/<ORG_NAME>/team/<TEAM_URL_ALIAS>

Only owners of the Organization are authorized to make this request.

GET /api/org/<ORG_NAME>/team/<TEAM_URL_ALIAS>/members

Only members of the organization are authorized to make this request.

POST /api/org/<ORG_NAME>/team/<TEAM_URL_ALIAS>/members
{
    "add_member" : {
       "user" : <USERNAME_OR_EMAIL>,
    }
}

Only owners of the Organization are authorized to make this request.

Only members of the Organization may be added to the Team.