Docker Remote API: Documentation is missing and misleading

[ahmetb]

Many fields in the response objects that I actually get in my local calls do not exist in Remote API v1.13 documentation.

And documentation is so bad that there are no types specified.

e.g. it just says:

 "PortSpecs":null,

what is the type of this field? It is just a null in JSON response.

That doesn't make sense. Docs are very vague and it's almost impossible to write a correctly working client without reading other clients and keep testing every single corner case (e.g. you gotta reproduce a case where portspecs is not null by creating a container etc).

This is crazy and will not help things move forward very well.

[ahmetb]

Here's another example, Inspect Container's Config & ContainerConfig objects have an OnBuild field which does not appear in the API docs at all.

{...
  "OnBuild": []
...}

[ahmetb]

My suggestion: you should provide the entire object model for those types you are returning in responses.

Even a godoc.org link to those types would be super helpful in the API docs.

[ahmetb]

Another example: In the response example for the "Get the history of an image" call (v1.13) there is no such fields called Tags or Size but I get a nullable string[] by running it locally.

[ahmetb]

Another example: In the response example for "Inspect container" endpoint, quite a lot of endpoints are either do not appear at all or their type simply cannot be inferred from the example output (or my local docker inspect output for a simple container):

• Name
• ProcessLabel
• Volumes
• VolumesRW
• MountLabel
• HostsPath
• HostnamePath
• ExecDriver
• Driver

all those fields are missing from your example output. Docs are not complete in that sense.

[cpuguy83]

Thanks for looking at this!

Would be awesome if you could make a PR to update the fields you found to be missing.

Docs are in docs/sources/reference/api

[ahmetb]

@cpuguy83 it simply won't fix if I add missing fields. There will be still a lot of misleading parameter descriptions, inconsistent response types, inconsistent naming, inconsistent URL routes. To solve this, the documentation needs a full description of its response types and clear statements of what parameters can take which values and which are mutually exclusive etc. This needs an entire API and docs update. I will try to come up with a proposal soon.

[dnephin]

I've noticed this problem as well. I often have to try and create containers, get them into the correct state, then make an API call to see what the API actually returns. I've also noticed that request parameters are often missing from the documentation, which is significantly harder to find.

There are a couple tools used for this type of documentation that are starting to emerge as possible standards. I think the most popular is http://swagger.io/ which uses json schemas and comes with a lot of excellent tooling. (http://apiblueprint.org/ uses markdown and is probably also worth a mention).

As a solution to this issue, I propose creating swagger schemas as the official remote API documentation.

A swagger schema (with swagger ui) gives you not only excellent documentation, the swagger ui also provides a way to interactive with the docker remote directly from the browser.

[jessfraz]

also see #2583

[ahmetb]

Closing this for the sake of #15188.