Changelog and docs for image and container endpoints

CHANGELOG.md

@@ -1,3 +1,5 @@
+* Add endpoints to manage images and containers locally [Pablo]
+* Only use bodyParser for endpoints that need it [Pablo]
 * Add RESIN_APP_ID variable [Pablo]
 * Increase delta request timeout to 15 minutes [Pablo]
 

docs/API.md

@@ -484,3 +484,128 @@ $ curl -X POST --header "Content-Type:application/json" \
 	--data '{"deviceId": <deviceId>, "appId": <appId>, "method": "GET"}' \
 	"https://api.resin.io/supervisor/v1/apps/<appId>"
 ```
+
+<hr>
+
+## API endpoints for image and container management
+
+Supervisor 1.9 introduces these endpoints to allow users to create images and containers from the app. These endpoints are designed to be
+as close as possible to the corresponding endpoints from the Docker Remote API. We chose this approach instead of just exposing the docker socket
+because we need the supervisor to track the containers and images to avoid cleaning them up unwantedly.
+
+All examples are shown as posted from the app on the device, as this is the intended use, but the API proxy works like with the other endpoints.
+
+Refer to the [Docker API docs](https://docs.docker.com/engine/reference/api/docker_remote_api_v1.22) for detailed descriptions of request parameters and response formats.
+
+### POST /v1/images/create
+
+Works like [/images/create from the Docker API](https://docs.docker.com/engine/reference/api/docker_remote_api_v1.22/#create-an-image).
+Allows the creation of images by pulling them from a registry or from a tar archive.
+
+#### Example:
+
+Creating an image from a tarball:
+```bash
+$ curl -X POST --data-binary @hello-master.tar \
+	"$RESIN_SUPERVISOR_ADDRESS/v1/images/create?fromSrc=-&repo=hello&tag=master&apikey=$RESIN_SUPERVISOR_API_KEY"
+```
+
+Pulling from DockerHub:
+```bash
+$ curl -X POST \
+	"$RESIN_SUPERVISOR_ADDRESS/v1/images/create?fromImage=alpine&tag=latest&apikey=$RESIN_SUPERVISOR_API_KEY"
+```
+
+<hr>
+
+### DELETE /v1/images/:name
+
+Deletes image with name `name`. Works like [DELETE /images/(name) from the Docker API](https://docs.docker.com/engine/reference/api/docker_remote_api_v1.22/#remove-an-image).
+Will only work if `name` is sent as the `repo:tag` used for creating the image.
+
+#### Example:
+
+```bash
+$ curl -X DELETE \
+	"$RESIN_SUPERVISOR_ADDRESS/v1/images/hello:master?apikey=$RESIN_SUPERVISOR_API_KEY"
+```
+
+<hr>
+
+### GET /v1/images
+
+Works like [GET /images/json from the Docker API](https://docs.docker.com/engine/reference/api/docker_remote_api_v1.22/#list-images).
+
+#### Example:
+
+```bash
+$ curl -X GET \
+	"$RESIN_SUPERVISOR_ADDRESS/v1/images?apikey=$RESIN_SUPERVISOR_API_KEY"
+```
+
+<hr>
+
+### POST /v1/containers/create
+
+Works like [/containers/create from the Docker API](https://docs.docker.com/engine/reference/api/docker_remote_api_v1.22/#create-a-container).
+Can only be used with `Image` specifying a `repo:tag` created with /v1/images/create.
+
+#### Example:
+
+```
+$ curl -X POST --data '{"Image":"alpine:latest","Cmd":["sh","-c", "while true; do echo hi; sleep 5; done"]}' -H "Content-Type: application/json" \
+	"$RESIN_SUPERVISOR_ADDRESS/v1/containers/create?apikey=$RESIN_SUPERVISOR_API_KEY"
+```
+
+<hr>
+
+### POST /v1/containers/:id/start
+
+Starts a container. Works like [/containers/(id)/start from the Docker API](https://docs.docker.com/engine/reference/api/docker_remote_api_v1.22/#start-a-container).
+The id can be extracted from the response of /v1/containers/create.
+
+#### Example:
+
+```
+$ curl -X POST \
+	"$RESIN_SUPERVISOR_ADDRESS/v1/containers/ac072860f31a9df31dea72f8418d193e6af257b4fed4008f86097200fba45966/start?apikey=$RESIN_SUPERVISOR_API_KEY"
+```
+
+<hr>
+
+### POST /v1/containers/:id/stop
+
+Stops a container. Works like [/containers/(id)/stop from the Docker API](https://docs.docker.com/engine/reference/api/docker_remote_api_v1.22/#stop-a-container).
+As with start, the id can be extracted from the response of /v1/containers/create.
+
+#### Example:
+
+```
+$ curl -X POST \
+	"$RESIN_SUPERVISOR_ADDRESS/v1/containers/ac072860f31a9df31dea72f8418d193e6af257b4fed4008f86097200fba45966/stop?apikey=$RESIN_SUPERVISOR_API_KEY"
+```
+
+<hr>
+
+### DELETE /v1/containers/:id
+
+Deletes a container. Works like [DELETE /containers/(id) from the Docker API](https://docs.docker.com/engine/reference/api/docker_remote_api_v1.22/#remove-a-container).
+The id can be extracted from the response of /v1/containers/create.
+
+#### Example:
+
+```
+$ curl -X DELETE \
+	"$RESIN_SUPERVISOR_ADDRESS/v1/containers/ac072860f31a9df31dea72f8418d193e6af257b4fed4008f86097200fba45966?apikey=$RESIN_SUPERVISOR_API_KEY"
+```
+
+### GET /v1/containers
+
+Lists containers. Works like [GET /containers/json from the Docker API](https://docs.docker.com/engine/reference/api/docker_remote_api_v1.22/#list-containers).
+
+#### Example:
+
+```
+$ curl -X GET \
+	"$RESIN_SUPERVISOR_ADDRESS/v1/containers?apikey=$RESIN_SUPERVISOR_API_KEY"
+```