Proposal: Tidy up API URLs

[bfirsh]

Why we should do this

There are various ways we can clean up the API to fit HTTP conventions. This will make it easier to comprehend, easier to use, and generally better organised.

Here are some things that could be changed:

1. We could remove /json from URLs because:
   • They're all JSON anyway.
   • If we want to add different formats, we can use parameters or the Accept header.
   • Consistency with new /networks and /volumes endpoints.
2. We could remove /create from API URLs because POST implies you are creating.
3. We could remove /update from API URLs and use PUT instead.

Why we shouldn't do this

Arguably, this is a pretty big change for a minor improvement in usability and aesthetics. It wouldn't be a breaking change because we can use a new API version, but it is breaking in the sense that people will be forced to update their client libraries to use this API version.

Although this is a minor improvement on the surface, I think people who see this crufty API design will perceive Docker as poor quality, and it is a broken window that encourages more bad design.

How

This is non-trivial, because some other API endpoints need renaming (e.g. /images/search will collide with an image called search). See the failed attempt in #23219 for full details.

The trivial ones:

• Rename GET /containers/json to GET /containers
• Rename GET /containers/(id or name)/json to GET /containers/(id or name)
• Rename POST /containers/(id or name)/update to PUT /containers/(id or name)
• Rename GET /images/json to GET /images
• Rename POST /images/create to POST /images
• Rename GET /images/json to GET /images
• Rename GET /images/(name)/json to GET /images/(name)
• Rename POST /images/create to POST /images
• Rename GET /exec/(id)/json to GET /exec/(id)
• Rename POST /volumes/create to POST /volumes
• Rename POST /networks/create to POST /networks
• Rename POST /services/create to POST /services
• Rename POST /services/(id or name)/update to PUT /services/(id or name)

The ones that are a bit more complex:

• Do something to GET /images/search because it collides with GET /images/(name). We could either:
  • Move it client side, because all it does is query Docker Hub.
  • Give it a different name. e.g. GET /image-search?q=... It's a different resource to daemon images, anyway.
• Rename GET /images/(name)/get to GET /images/(name)?format=tar (GET .../get is not particularly descriptive)
• Rename POST /images/load to POST /images?format=tar
• Rename GET /images/get?names=(name1)&names=(name2) to GET /images?format=tar&name=(name1)&name=(name2). Alternatively, we could remove this entirely because it's probably pretty simple to concatenate the tarballs client-side.

See also

• Proposal for New and Improved Remote API #5893
• Remove /json from API URLs #23219

/cc @justincormack @thaJeztah @vdemeester @cpuguy83

[justincormack]

I am in favour of this. I think that images/search should be renamed as it is a different kind of API as it searches a registry.

The discussion we had before about backwards compatibility of /containers/json vs a container called json I am not sure about. A clean break is nice but not sure if this will break some scripts.

[vdemeester]

ping @thaJeztah @vieux @justincormack @cpuguy83 what is the status here ?

[thaJeztah]

Would still be nice to have, but there's some breaking changes in these (e.g. we'd have to mark json as a reserved name, and disallow creating a container or image with that name), so likely only possible if we switch to SemVer for the API (#31842), and start a 2.x version