Proposal: Rename "Docker Remote API" to "Docker Engine API"

[bfirsh]

Reasoning

As part of my work to improve the API documentation I realised that "Docker Remote API" is a bit of a confusing name. The Docker Registry serves the Docker Registry API, Docker Cloud serves the Docker Cloud API, Docker Hub has (had?) the Docker Hub API, Docker Trusted Registry has the Docker Trusted Registry API, but Engine is the odd one out.

As far as I can see, it's a historical artefact from when "Docker" was just the Engine. We've since added other APIs, and the original was never given a distinctive name.

Besides consistency, here are some reasons for the change:

1. "Remote" is redundant – all HTTP APIs are remote. "Docker API" would collide with other Docker APIs, hence "Docker Engine API".
2. When you want to find the API for the Engine, it's not immediately clear that you should be looking for the "Remote API". (And vice versa, "Remote API" does not make it immediately obvious that it's the thing the Engine exposes.)
3. The information architecture in the documentation is a bit weird, because "Remote API" doesn't comfortably sit under "Engine".

Implementation

The only place we reference it seems to be in the documentation and CLI docs, so looks like we can just do a big ol' search and replace.

The only breakage I can think of is if people search for "Docker Remote API" on Google and the documentation doesn't turn up. To counteract this, we can leave it as the "Remote API" in old versions of the API documentation, and add "Remote API" to the keywords of the latest API docs. Or, just a bit of copy like: "In version X of Docker and below, the Engine API was called the Docker Remote API."

/cc @dnephin @johndmulhausen @icecrime @shykes

[johndmulhausen]

+1 to this idea. "Remote API" sounds like a separate product entirely.

[dnephin]

I agree

[bfirsh]

Another thought: There was a time when the Remote API spanned multiple products (Engine and Swarm), which is probably why the name felt correct in the past. Now with Swarm integrated into Engine, Engine is the only thing that exposes the API, so it is much simpler and more sensible for it to be called "Engine API".

[johndmulhausen]

So, it's obviously quite easy to do this in the docs; is that the main place where the phrase "Remote API" is defined, or would more significant code changes need to take place?

[bfirsh]

@johndmulhausen Yep, all in docs.

It doesn't seem to be controversial, so I'll do it as part of my PR for API docs against docker/docker.github.io.

[thaJeztah]

@bfirsh this will need changes to the docs in docker/docker as well (which talks about the "remote API"