The Engine API is an HTTP API used by the command-line client to communicate with the daemon. It can also be used by third-party software to control the daemon.
It consists of various components in this repository:
api/swagger.yaml
A Swagger definition of the API.api/types/
Types shared by both the client and server, representing various objects, options, responses, etc. Most are written manually, but some are automatically generated from the Swagger definition. See #27919 for progress on this.cli/
The command-line client.client/
The Go client used by the command-line client. It can also be used by third-party Go programs.daemon/
The daemon, which serves the API.The API is defined by the Swagger definition in api/swagger.yaml
. This definition can be used to:
The API documentation is generated entirely from api/swagger.yaml
. If you make updates to the API, edit this file to represent the change in the documentation.
The file is split into two main sections:
definitions
, which defines re-usable objects used in requests and responsespaths
, which defines the API endpoints (and some inline objects which don't need to be reusable)To make an edit, first look for the endpoint you want to edit under paths
, then make the required edits. Endpoints may reference reusable objects with $ref
, which can be found in the definitions
section.
There is hopefully enough example material in the file for you to copy a similar pattern from elsewhere in the file (e.g. adding new fields or endpoints), but for the full reference, see the Swagger specification.
swagger.yaml
is validated by hack/validate/swagger
to ensure it is a valid Swagger definition. This is useful when making edits to ensure you are doing the right thing.
When you make edits to swagger.yaml
, you may want to check the generated API documentation to ensure it renders correctly.
Run make swagger-docs
and a preview will be running at http://localhost
. Some of the styling may be incorrect, but you'll be able to ensure that it is generating the correct documentation.
The production documentation is generated by vendoring swagger.yaml
into docker/docker.github.io.