| # Engine API | |
| [](https://pkg.go.dev/github.com/moby/moby/api) | |
|  | |
| [](https://goreportcard.com/report/github.com/moby/moby/api) | |
| [](https://scorecard.dev/viewer/?uri=github.com/moby/moby) | |
| [](https://www.bestpractices.dev/projects/10989) | |
| 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](https://github.com/moby/moby/issues/27919) for progress on this. | |
| - `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. | |
| ## Swagger definition | |
| The API is defined by the [Swagger](http://swagger.io/specification/) definition in `api/swagger.yaml`. This definition can be used to: | |
| 1. Automatically generate documentation. | |
| 2. Automatically generate the Go server and client. (A work-in-progress.) | |
| 3. Provide a machine readable version of the API for introspecting what it can do, automatically generating clients for other languages, etc. | |
| ## Updating the API documentation | |
| 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. | |
| Documentation for each API version can be found in the [docs directory](docs/README.md), which also provides a [CHANGELOG.md](docs/CHANGELOG.md). | |
| The file is split into two main sections: | |
| - `definitions`, which defines re-usable objects used in requests and responses | |
| - `paths`, 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](https://github.com/moby/moby/issues/27919). | |
| `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. | |
| ## Viewing the API documentation | |
| 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:9000`. 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/docs](https://github.com/docker/docs). |