github.com/technosophos/deis@v1.7.1-0.20150915173815-f9005256004b/docs/reference/api-v1.1.rst

:title: Controller API v1.1
:description: The v1.1 REST API for Deis' Controller

Controller API v1.1
===================

This is the v1.1 REST API for the :ref:`Controller`.


What's New
----------

**New!** All controller responses now return the ``X_DEIS_API_VERSION`` header.

**New!** All controller responses now return the ``X_DEIS_PLATFORM_VERSION`` header.

**New!** Users see a 404 response when modifying applications they are unauthorized to see.

**New!** Responses returned from the scheduler are properly formatted JSON responses.


Authentication
--------------


Register a New User
```````````````````

Example Request:

.. code-block:: console

    POST /v1/auth/register/ HTTP/1.1
    Host: deis.example.com
    Content-Type: application/json

    {
        "username": "test",
        "password": "opensesame",
        "email": "test@example.com"
    }

Optional Parameters:

.. code-block:: console

    {
        "first_name": "test",
        "last_name": "testerson"
    }

Example Response:

.. code-block:: console

    HTTP/1.1 201 CREATED
    X_DEIS_API_VERSION: 1.1
    X_DEIS_PLATFORM_VERSION: 1.4.1
    Content-Type: application/json

    {
        "id": 1,
        "last_login": "2014-10-19T22:01:00.601Z",
        "is_superuser": true,
        "username": "test",
        "first_name": "test",
        "last_name": "testerson",
        "email": "test@example.com",
        "is_staff": true,
        "is_active": true,
        "date_joined": "2014-10-19T22:01:00.601Z",
        "groups": [],
        "user_permissions": []
    }


Log in
``````

Example Request:

.. code-block:: console

    POST /v1/auth/login/ HTTP/1.1
    Host: deis.example.com
    Content-Type: application/json

    {"username": "test", "password": "opensesame"}

Example Response:

.. code-block:: console

    HTTP/1.1 200 OK
    X_DEIS_API_VERSION: 1.1
    X_DEIS_PLATFORM_VERSION: 1.4.1
    Content-Type: application/json

    {"token": "abc123"}


Cancel Account
``````````````

Example Request:

.. code-block:: console

    DELETE /v1/auth/cancel/ HTTP/1.1
    Host: deis.example.com
    Authorization: token abc123

Example Response:

.. code-block:: console

    HTTP/1.1 204 NO CONTENT
    X_DEIS_API_VERSION: 1.1
    X_DEIS_PLATFORM_VERSION: 1.4.1


Applications
------------


List all Applications
`````````````````````

Example Request:

.. code-block:: console

    GET /v1/apps HTTP/1.1
    Host: deis.example.com
    Authorization: token abc123

Example Response:

.. code-block:: console

    HTTP/1.1 200 OK
    X_DEIS_API_VERSION: 1.1
    X_DEIS_PLATFORM_VERSION: 1.4.1
    Content-Type: application/json

    {
        "count": 1,
        "next": null,
        "previous": null,
        "results": [
            {
                "created": "2014-01-01T00:00:00UTC",
                "id": "example-go",
                "owner": "test",
                "structure": {},
                "updated": "2014-01-01T00:00:00UTC",
                "url": "example-go.example.com",
                "uuid": "de1bf5b5-4a72-4f94-a10c-d2a3741cdf75"
            }
        ]
    }


Create an Application
`````````````````````

Example Request:

.. code-block:: console

    POST /v1/apps/ HTTP/1.1
    Host: deis.example.com
    Content-Type: application/json
    Authorization: token abc123

Optional parameters:

.. code-block:: console

    {"id": "example-go"}


Example Response:

.. code-block:: console

    HTTP/1.1 201 CREATED
    X_DEIS_API_VERSION: 1.1
    X_DEIS_PLATFORM_VERSION: 1.4.1
    Content-Type: application/json

    {
        "created": "2014-01-01T00:00:00UTC",
        "id": "example-go",
        "owner": "test",
        "structure": {},
        "updated": "2014-01-01T00:00:00UTC",
        "url": "example-go.example.com",
        "uuid": "de1bf5b5-4a72-4f94-a10c-d2a3741cdf75"
    }


Destroy an Application
``````````````````````

Example Request:

.. code-block:: console

    DELETE /v1/apps/example-go/ HTTP/1.1
    Host: deis.example.com
    Authorization: token abc123

Example Response:

.. code-block:: console

    HTTP/1.1 204 NO CONTENT
    X_DEIS_API_VERSION: 1.1
    X_DEIS_PLATFORM_VERSION: 1.4.1


List Application Details
````````````````````````

Example Request:

.. code-block:: console

    GET /v1/apps/example-go/ HTTP/1.1
    Host: deis.example.com
    Authorization: token abc123

Example Response:

.. code-block:: console

    HTTP/1.1 200 OK
    X_DEIS_API_VERSION: 1.1
    X_DEIS_PLATFORM_VERSION: 1.4.1
    Content-Type: application/json

    {
        "created": "2014-01-01T00:00:00UTC",
        "id": "example-go",
        "owner": "test",
        "structure": {},
        "updated": "2014-01-01T00:00:00UTC",
        "url": "example-go.example.com",
        "uuid": "de1bf5b5-4a72-4f94-a10c-d2a3741cdf75"
    }


Retrieve Application Logs
`````````````````````````

Example Request:

.. code-block:: console

    GET /v1/apps/example-go/logs/ HTTP/1.1
    Host: deis.example.com
    Authorization: token abc123

Example Response:

.. code-block:: console

    HTTP/1.1 200 OK
    X_DEIS_API_VERSION: 1.1
    X_DEIS_PLATFORM_VERSION: 1.4.1
    Content-Type: text/plain

    "16:51:14 deis[api]: test created initial release\n"


Run one-off Commands
````````````````````

.. code-block:: console

    POST /v1/apps/example-go/run/ HTTP/1.1
    Host: deis.example.com
    Content-Type: application/json
    Authorization: token abc123

    {"command": "echo hi"}

Example Response:

.. code-block:: console

    HTTP/1.1 200 OK
    X_DEIS_API_VERSION: 1.1
    X_DEIS_PLATFORM_VERSION: 1.4.1
    Content-Type: application/json

    {"rc": 0, "output": "hi"}


Containers
----------


List all Containers
```````````````````

Example Request:

.. code-block:: console

    GET /v1/apps/example-go/containers/ HTTP/1.1
    Host: deis.example.com
    Authorization: token abc123

Example Response:

.. code-block:: console

    HTTP/1.1 200 OK
    X_DEIS_API_VERSION: 1.1
    X_DEIS_PLATFORM_VERSION: 1.4.1
    Content-Type: application/json

    {
        "count": 1,
        "next": null,
        "previous": null,
        "results": [
            {
                "owner": "test",
                "app": "example-go",
                "release": "v2",
                "created": "2014-01-01T00:00:00UTC",
                "updated": "2014-01-01T00:00:00UTC",
                "uuid": "de1bf5b5-4a72-4f94-a10c-d2a3741cdf75",
                "type": "web",
                "num": 1,
                "state": "up"
            }
        ]
    }


List all Containers by Type
```````````````````````````

Example Request:

.. code-block:: console

    GET /v1/apps/example-go/containers/web/ HTTP/1.1
    Host: deis.example.com
    Authorization: token abc123

Example Response:

.. code-block:: console

    HTTP/1.1 200 OK
    X_DEIS_API_VERSION: 1.1
    X_DEIS_PLATFORM_VERSION: 1.4.1
    Content-Type: application/json

    {
        "count": 1,
        "next": null,
        "previous": null,
        "results": [
            {
                "owner": "test",
                "app": "example-go",
                "release": "v2",
                "created": "2014-01-01T00:00:00UTC",
                "updated": "2014-01-01T00:00:00UTC",
                "uuid": "de1bf5b5-4a72-4f94-a10c-d2a3741cdf75",
                "type": "web",
                "num": 1,
                "state": "up"
            }
        ]
    }


Scale Containers
````````````````

Example Request:

.. code-block:: console

    POST /v1/apps/example-go/scale/ HTTP/1.1
    Host: deis.example.com
    Content-Type: application/json
    Authorization: token abc123

    {"web": 3}

Example Response:

.. code-block:: console

    HTTP/1.1 204 NO CONTENT
    X_DEIS_API_VERSION: 1.1
    X_DEIS_PLATFORM_VERSION: 1.4.1


Configuration
-------------


List Application Configuration
``````````````````````````````

Example Request:

.. code-block:: console

    GET /v1/apps/example-go/config/ HTTP/1.1
    Host: deis.example.com
    Authorization: token abc123

Example Response:

.. code-block:: console

    HTTP/1.1 200 OK
    X_DEIS_API_VERSION: 1.1
    X_DEIS_PLATFORM_VERSION: 1.4.1
    Content-Type: application/json

    {
        "owner": "test",
        "app": "example-go",
        "values": {},
        "memory": {},
        "cpu": {},
        "tags": {},
        "created": "2014-01-01T00:00:00UTC",
        "updated": "2014-01-01T00:00:00UTC",
        "uuid": "de1bf5b5-4a72-4f94-a10c-d2a3741cdf75"
    }


Create new Config
`````````````````

Example Request:

.. code-block:: console

    POST /v1/apps/example-go/config/ HTTP/1.1
    Host: deis.example.com
    Content-Type: application/json
    Authorization: token abc123

    {"values": {"HELLO": "world", "PLATFORM: "deis"}}

Example Response:

.. code-block:: console

    HTTP/1.1 201 CREATED
    X_DEIS_API_VERSION: 1.1
    X_DEIS_PLATFORM_VERSION: 1.4.1
    Content-Type: application/json
    X-Deis-Release: 3

    {
        "owner": "test",
        "app": "example-go",
        "values": {
            "DEIS_APP": "example-go",
            "DEIS_RELEASE": "v3",
            "HELLO": "world",
            "PLATFORM": "deis"

        },
        "memory": {},
        "cpu": {},
        "tags": {},
        "created": "2014-01-01T00:00:00UTC",
        "updated": "2014-01-01T00:00:00UTC",
        "uuid": "de1bf5b5-4a72-4f94-a10c-d2a3741cdf75"
    }


Unset Config Variable
`````````````````````

Example Request:

.. code-block:: console

    POST /v1/apps/example-go/config/ HTTP/1.1
    Host: deis.example.com
    Content-Type: application/json
    Authorization: token abc123

    {"values": {"HELLO": null}}

Example Response:

.. code-block:: console

    HTTP/1.1 201 CREATED
    X_DEIS_API_VERSION: 1.1
    X_DEIS_PLATFORM_VERSION: 1.4.1
    Content-Type: application/json
    X-Deis-Release: 4

    {
        "owner": "test",
        "app": "example-go",
        "values": {
            "DEIS_APP": "example-go",
            "DEIS_RELEASE": "v4",
            "PLATFORM": "deis"
       },
        "memory": {},
        "cpu": {},
        "tags": {},
        "created": "2014-01-01T00:00:00UTC",
        "updated": "2014-01-01T00:00:00UTC",
        "uuid": "de1bf5b5-4a72-4f94-a10c-d2a3741cdf75"
    }


Domains
-------


List Application Domains
````````````````````````

Example Request:

.. code-block:: console

    GET /v1/apps/example-go/domains/ HTTP/1.1
    Host: deis.example.com
    Authorization: token abc123

Example Response:

.. code-block:: console

    HTTP/1.1 200 OK
    X_DEIS_API_VERSION: 1.1
    X_DEIS_PLATFORM_VERSION: 1.4.1
    Content-Type: application/json

    {
        "count": 1,
        "next": null,
        "previous": null,
        "results": [
            {
                "app": "example-go",
                "created": "2014-01-01T00:00:00UTC",
                "domain": "example.example.com",
                "owner": "test",
                "updated": "2014-01-01T00:00:00UTC"
            }
        ]
    }


Add Domain
``````````

Example Request:

.. code-block:: console

    POST /v1/apps/example-go/domains/ HTTP/1.1
    Host: deis.example.com
    Authorization: token abc123

    {'domain': 'example.example.com'}

Example Response:

.. code-block:: console

    HTTP/1.1 201 CREATED
    X_DEIS_API_VERSION: 1.1
    X_DEIS_PLATFORM_VERSION: 1.4.1
    Content-Type: application/json

    {
        "app": "example-go",
        "created": "2014-01-01T00:00:00UTC",
        "domain": "example.example.com",
        "owner": "test",
        "updated": "2014-01-01T00:00:00UTC"
    }



Remove Domain
`````````````

Example Request:

.. code-block:: console

    DELETE /v1/apps/example-go/domains/example.example.com HTTP/1.1
    Host: deis.example.com
    Authorization: token abc123

Example Response:

.. code-block:: console

    HTTP/1.1 204 NO CONTENT
    X_DEIS_API_VERSION: 1.1
    X_DEIS_PLATFORM_VERSION: 1.4.1


Builds
------


List Application Builds
```````````````````````

Example Request:

.. code-block:: console

    GET /v1/apps/example-go/builds/ HTTP/1.1
    Host: deis.example.com
    Authorization: token abc123

Example Response:

.. code-block:: console

    HTTP/1.1 200 OK
    X_DEIS_API_VERSION: 1.1
    X_DEIS_PLATFORM_VERSION: 1.4.1
    Content-Type: application/json

    {
        "count": 1,
        "next": null,
        "previous": null,
        "results": [
            {
                "app": "example-go",
                "created": "2014-01-01T00:00:00UTC",
                "dockerfile": "FROM deis/slugrunner RUN mkdir -p /app WORKDIR /app ENTRYPOINT [\"/runner/init\"] ADD slug.tgz /app ENV GIT_SHA 060da68f654e75fac06dbedd1995d5f8ad9084db",
                "image": "example-go",
                "owner": "test",
                "procfile": {
                    "web": "example-go"
                },
                "sha": "060da68f",
                "updated": "2014-01-01T00:00:00UTC",
                "uuid": "de1bf5b5-4a72-4f94-a10c-d2a3741cdf75"
            }
        ]
    }


Create Application Build
````````````````````````

Example Request:

.. code-block:: console

    POST /v1/apps/example-go/builds/ HTTP/1.1
    Host: deis.example.com
    Content-Type: application/json
    Authorization: token abc123

    {"image": "deis/example-go:latest"}

Example Response:

.. code-block:: console

    HTTP/1.1 201 CREATED
    X_DEIS_API_VERSION: 1.1
    X_DEIS_PLATFORM_VERSION: 1.4.1
    Content-Type: application/json
    X-Deis-Release: 4

    {
        "app": "example-go",
        "created": "2014-01-01T00:00:00UTC",
        "dockerfile": "",
        "image": "deis/example-go:latest",
        "owner": "test",
        "procfile": {},
        "sha": "",
        "updated": "2014-01-01T00:00:00UTC",
        "uuid": "de1bf5b5-4a72-4f94-a10c-d2a3741cdf75"
    }


Releases
--------


List Application Releases
`````````````````````````

Example Request:

.. code-block:: console

    GET /v1/apps/example-go/releases/ HTTP/1.1
    Host: deis.example.com
    Authorization: token abc123

Example Response:

.. code-block:: console

    HTTP/1.1 200 OK
    X_DEIS_API_VERSION: 1.1
    X_DEIS_PLATFORM_VERSION: 1.4.1
    Content-Type: application/json

    {
        "count": 3,
        "next": null,
        "previous": null,
        "results": [
            {
                "app": "example-go",
                "build": "202d8e4b-600e-4425-a85c-ffc7ea607f61",
                "config": "ed637ceb-5d32-44bd-9406-d326a777a513",
                "created": "2014-01-01T00:00:00UTC",
                "owner": "test",
                "summary": "test changed nothing",
                "updated": "2014-01-01T00:00:00UTC",
                "uuid": "de1bf5b5-4a72-4f94-a10c-d2a3741cdf75",
                "version": 3
            },
            {
                "app": "example-go",
                "build": "202d8e4b-600e-4425-a85c-ffc7ea607f61",
                "config": "95bd6dea-1685-4f78-a03d-fd7270b058d1",
                "created": "2014-01-01T00:00:00UTC",
                "owner": "test",
                "summary": "test deployed 060da68",
                "updated": "2014-01-01T00:00:00UTC",
                "uuid": "de1bf5b5-4a72-4f94-a10c-d2a3741cdf75",
                "version": 2
            },
            {
                "app": "example-go",
                "build": null,
                "config": "95bd6dea-1685-4f78-a03d-fd7270b058d1",
                "created": "2014-01-01T00:00:00UTC",
                "owner": "test",
                "summary": "test created initial release",
                "updated": "2014-01-01T00:00:00UTC",
                "uuid": "de1bf5b5-4a72-4f94-a10c-d2a3741cdf75",
                "version": 1
            }
        ]
    }


List Release Details
````````````````````

Example Request:

.. code-block:: console

    GET /v1/apps/example-go/releases/v1/ HTTP/1.1
    Host: deis.example.com
    Authorization: token abc123

Example Response:

.. code-block:: console

    HTTP/1.1 200 OK
    X_DEIS_API_VERSION: 1.1
    X_DEIS_PLATFORM_VERSION: 1.4.1
    Content-Type: application/json

    {
        "app": "example-go",
        "build": null,
        "config": "95bd6dea-1685-4f78-a03d-fd7270b058d1",
        "created": "2014-01-01T00:00:00UTC",
        "owner": "test",
        "summary": "test created initial release",
        "updated": "2014-01-01T00:00:00UTC",
        "uuid": "de1bf5b5-4a72-4f94-a10c-d2a3741cdf75",
        "version": 1
    }


Rollback Release
````````````````

Example Request:

.. code-block:: console

    POST /v1/apps/example-go/releases/rollback/ HTTP/1.1
    Host: deis.example.com
    Content-Type: application/json
    Authorization: token abc123

    {"version": 1}

Example Response:

.. code-block:: console

    HTTP/1.1 201 CREATED
    X_DEIS_API_VERSION: 1.1
    X_DEIS_PLATFORM_VERSION: 1.4.1
    Content-Type: application/json

    {"version": 5}


Keys
----


List Keys
`````````

Example Request:

.. code-block:: console

    GET /v1/keys/ HTTP/1.1
    Host: deis.example.com
    Authorization: token abc123

Example Response:

.. code-block:: console

    {
    X_DEIS_API_VERSION: 1.1
    X_DEIS_PLATFORM_VERSION: 1.4.1
        "count": 1,
        "next": null,
        "previous": null,
        "results": [
            {
                "created": "2014-01-01T00:00:00UTC",
                "id": "test@example.com",
                "owner": "test",
                "public": "ssh-rsa <...>",
                "updated": "2014-01-01T00:00:00UTC",
                "uuid": "de1bf5b5-4a72-4f94-a10c-d2a3741cdf75"
            }
        ]
    }


Add Key to User
```````````````

Example Request:

.. code-block:: console

    POST /v1/keys/ HTTP/1.1
    Host: deis.example.com
    Authorization: token abc123

    {
        "id": "example",
        "public": "ssh-rsa <...>"
    }

Example Response:

.. code-block:: console

    HTTP/1.1 201 CREATED
    X_DEIS_API_VERSION: 1.1
    X_DEIS_PLATFORM_VERSION: 1.4.1
    Content-Type: application/json

    {
        "created": "2014-01-01T00:00:00UTC",
        "id": "example",
        "owner": "example",
        "public": "ssh-rsa <...>",
        "updated": "2014-01-01T00:00:00UTC",
        "uuid": "de1bf5b5-4a72-4f94-a10c-d2a3741cdf75"
    }


Remove Key from User
````````````````````

Example Request:

.. code-block:: console

    DELETE /v1/keys/example HTTP/1.1
    Host: deis.example.com
    Authorization: token abc123

Example Response:

.. code-block:: console

    HTTP/1.1 204 NO CONTENT
    X_DEIS_API_VERSION: 1.1
    X_DEIS_PLATFORM_VERSION: 1.4.1


Permissions
-----------


List Application Permissions
````````````````````````````

Example Request:

.. code-block:: console

    GET /v1/apps/example-go/perms/ HTTP/1.1
    Host: deis.example.com
    Authorization: token abc123

Example Response:

.. code-block:: console

    HTTP/1.1 200 OK
    X_DEIS_API_VERSION: 1.1
    X_DEIS_PLATFORM_VERSION: 1.4.1
    Content-Type: application/json

    {
        "users": []
    }


Create Application Permission
`````````````````````````````

Example Request:

.. code-block:: console

    POST /v1/apps/example-go/perms/ HTTP/1.1
    Host: deis.example.com
    Authorization: token abc123

    {"username": "example"}

Example Response:

.. code-block:: console

    HTTP/1.1 201 CREATED
    X_DEIS_API_VERSION: 1.1
    X_DEIS_PLATFORM_VERSION: 1.4.1


Remove Application Permission
`````````````````````````````

Example Request:

.. code-block:: console

    POST /v1/apps/example-go/perms/example HTTP/1.1
    Host: deis.example.com
    Authorization: token abc123

Example Response:

.. code-block:: console

    HTTP/1.1 204 NO CONTENT
    X_DEIS_API_VERSION: 1.1
    X_DEIS_PLATFORM_VERSION: 1.4.1

Grant User Administrative Privileges
````````````````````````````````````

.. note::

    This command requires administrative privileges

Example Request:

.. code-block:: console

    POST /v1/admin/perms HTTP/1.1
    Host: deis.example.com
    Authorization: token abc123

    {"username": "example"}

Example Response:

.. code-block:: console

    HTTP/1.1 201 CREATED
    X_DEIS_API_VERSION: 1.1
    X_DEIS_PLATFORM_VERSION: 1.4.1