History

Sebastiaan van Stijn e82b7b2fa0 errdefs: move GetHTTPErrorStatusCode to api/server/httpstatus This reverts the changes made in `2a9c987e5a`, which moved the GetHTTPErrorStatusCode() utility to the errdefs package. While it seemed to make sense at the time to have the errdefs package provide conversion both from HTTP status codes errdefs and the reverse, a side-effect of the move was that the errdefs package now had a dependency on various external modules, to handle conversio of errors coming from those sub-systems, such as; - github.com/containerd/containerd - github.com/docker/distribution - google.golang.org/grpc This patch moves the conversion from (errdef-) errors to HTTP status-codes to a api/server/httpstatus package, which is only used by the API server, and should not be needed by client-code using the errdefs package. The MakeErrorHandler() utility was moved to the API server itself, as that's the only place it's used. While the same applies to the GetHTTPErrorStatusCode func, I opted for keeping that in its own package for a slightly cleaner interface. Why not move it into the api/server/httputils package? The api/server/httputils package is also imported in the client package, which uses the httputils.ParseForm() and httputils.HijackConnection() functions as part of the TestTLSCloseWriter() test. While this is only used in tests, I wanted to avoid introducing the indirect depdencencies outside of the api/server code. Signed-off-by: Sebastiaan van Stijn <github@gone.nl>		2022-03-21 12:22:39 +01:00
..
server	errdefs: move GetHTTPErrorStatusCode to api/server/httpstatus	2022-03-21 12:22:39 +01:00
templates/server	swagger: fix "generated code" comment not in correct format	2019-11-05 11:32:37 -08:00
types	api: filters: return correct status on invalid filters	2022-03-18 09:44:50 +01:00
common.go	API: update API version to v1.42	2021-07-03 18:12:46 +02:00
common_unix.go	Update to Go 1.17.0, and gofmt with Go 1.17	2021-08-24 23:33:27 +02:00
common_windows.go	Add canonical import comment	2018-02-05 16:51:57 -05:00
README.md	API: minor fixes in the README	2017-10-11 16:12:10 +02:00
swagger-gen.yaml	Use a config to generate swagger api types	2016-10-31 11:13:41 -04:00
swagger.yaml	api/types: fix KernelMemory deprecation comment, and omitempty	2022-03-17 09:56:48 +01:00

README.md

Working on the Engine API

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.

Swagger definition

The API is defined by the Swagger definition in api/swagger.yaml. This definition can be used to:

Automatically generate documentation.
Automatically generate the Go server and client. (A work-in-progress.)
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.

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.

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. 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.