Stack API spec

[egeldenhuys]

Closes #57

The rendered spec can be viewed here

Rendered using

npm install -g aglio
aglio -i docks.apib --theme-template triple -o stack-api-spec.html

Themes can be viewed in the Aglio Repository

[egeldenhuys]

I'm still not sure how we will implement the update functionality but we'll get to it.

The most complex part will be to reverse the docker inspect, which will also require discovering all services related to a stack. From there we can use docker stack deploy which will update the stack, given a docker-compose file

[egeldenhuys]

I realise the endpoint for retrieving a reversed docker-compose.yml for a stack is missing.

Rough Draft:

### Get Docker Compose File [GET /stacks/{stackName}/stackfile]

+ Paramaters
    + stackName (string) - Unique stack name

+ Response 200 (application/json)
        {
            "data": {
                "stackFile": "IyBEZXBsb3kgdG...V09SRD1leGFtcGxl"
            }
        }

+ Response 404
    Stack does not exist

    + Body

The reason for having GET /stacks/{stackName}/stackfile instead of GET /stacks/{stackName is that generating the stack file will be an expensive operation and should only be used when required.

The Deploy New Stack endpoint documentation looks strange, I will also fix that,

[annamarieHelberg]

This looks amazing! Thank you for implementing this!

[egeldenhuys]

@annamarieHelberg Note that this is only the contract between front-end and back-end, the real work still has to be done :laughing:

[egeldenhuys]

When returning tasks we also need to conform to the existing Docker API data structure

TODO:

• [x] Return Services according to Docker API
• [x] Return Tasks according to Docker API
• [ ] Add endpoint to get stack file

[egeldenhuys]

The schema for /stacks/{stackName}/services will follow https://docs.docker.com/engine/api/v1.37/#operation/ServiceList with the addition of being wrapped in "data": [<SERVICES>]

The schema for /stacks/{stackName}/tasks will follow https://docs.docker.com/engine/api/v1.37/#operation/TaskList with the addition of being wrapped in "data": [<TASKS>]

I do not see a good reason for duplicating the data structure in the documentation. If we were using the same specification format (Swagger) as Docker API, this would be a quick fix

[egeldenhuys]

Changes have been implemented in the spec. Rendered spec can be viewed here