Proposal for New and Improved Remote API

[saden1]

The current Remote API has a number issues (#5722, #5278, #2786, #3037, #1011, #3622, #2949, etc) that make it award to use. I propose that the following issues be addressed in a new version of the API. This new API will breaking but I believe going forward the benefit of these changes will outweigh the cost IMHO.

1. Change POST request that don't have payload to GET requests.
2. Utilize Server-Side-Events for blocking operations and use JSON data for event data.
3. Standardize error response and return a JSON object that encapsulates error messages.
4. Avoid using "/json" in request URL and instead rely on "Accept" header.
5. Return appropriate Content-Type header information.
6. Use "camelCase" or "PascalCase" for JSON property names but not both.
7. For PascalCase, two letter property names should not be capitalized (Change "ID" to "Id", and "OS" to "Os"). Doing so would make the JSON easier to process.
8. Stream content type should be specific. If returning octet-stream that's a gzip file then use "application/gzip) (RFC 6713)
9. Break the Remote API documentation page into smaller pages.
10. Add JSON schema definitions for JSON objects.
11. Add HATEOAS support?

I have started a new repository wiki page to track this proposal. I have also done a first take on revamping the List Containers request and would love feedback.

https://github.com/saden1/docker-api/wiki/List-Containers

Is this something the docker team is interested in doing?

[jamtur01]

Sounds like something core team should comment on @shykes @crosbymichael @vieux @CrEaK

[dnephin]

10. Add JSON schema definitions for JSON objects.

+1, #7669 is related to this, I propose a json schema in the http://swagger.io/ format would be great. Allows you to take advantage of the existing tooling (UI, editor, try calls from the browser, validation, etc)

[wouterd]

RE 1: I would let the intent of the call be reflected in the HTTP method, not so much the requirement of a body.

So GETs should only "get" stuff, not have side effects.
DELETEs should delete things
POSTs / PUTs should add/replace things.

Also, the path should not include the "method" if it is implied by the method, even further: the path shouldn't include verbs at all.

So to create a container, I would do a POST to /containers, not a post to /containers/create.

An interesting one is starting containers, we could "post" a command in "json" form to a container, but that would seriously make it annoying to "explore" the API. Maybe "POST" to a /container/{id}/startRequest path.

I think the apigee API book is really good at giving a consistent approach to designing web APIs.

[posita]

See also #13240 which cites the following additional issues:

• Don't forget about the object in the .../json files in the x-tar archives produced by the various .../get methods
• Some objects use different names to represent the same information, e.g.:
  • ParentId (e.g., /images/{image_id}/inspect) vs. Parent (e.g., /images/json) vs. parent (e.g., in the {image_id}/json files present in the x-tar stream from /images/{image_id}/get)
• Some objects are missing values, e.g.:
  • Comment and VirtualSize are present in /images/{image_id}/inspect, but missing from the {image_id}/json files

[LK4D4]

Still an issue.

[Relequestual]

Does #31842 (comment) superseed your expectation of usin JSON Schema?

[AkihiroSuda]

closing as this one seems stalled