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?