[Docs fixit] Rename Skaffold API to Skaffold gRPC and HTTP service

[gsquared94]

The side-bar and pages titled Skaffold API can get confused with the skaffold.yaml API. We should consider explicitly renaming all occurrences of Skaffold API to Skaffold gRPC and HTTP service or something similar.
Also change the links from <link>/../api to <link>/../server or <link>/../service

https://skaffold.dev/docs/design/api/
https://skaffold.dev/docs/references/api/

[ahmetb]

I am not sure if people would confuse the skaffold.yaml which is a config file with the API.

The "Skaffold API" term IMO more clearly explains the feature than "Skaffold [...] service". I am currently -1 on this. 👎🏼

[gsquared94]

The "Skaffold API" term IMO more clearly explains the feature than "Skaffold [...] service".

for tilt.dev, "Tiltfile API" is used for the config file schema link. They don't seem to have any Skaffold API equivalent atm.

---

In Skaffold the link for the config file schema is called "Skaffold Pipeline":
https://skaffold.dev/docs/design/

No data to support this, but I'd click Skaffold API first before the other links hoping to get the config file schema details which is obviously much more important (and should be more easily discoverable, #6484) than the API server.

@ahmetb how about Skaffold Meta API or something else to emphasize that it's not the config API?

wdyt @kourtneyshort ?

[kourtneyshort]

If the Skaffold Meta API would be clearer to customers, that sounds good to me. In https://skaffold.dev/docs/references/api/, you link to the other page but I don't think the sentence makes clear that the link is taking them to a different thing. "For a detailed description of the Skaffold API.

So on https://skaffold.dev/docs/references/api/, I'd suggest:

Naming the page something more informative than API
Rephrasing the description to make clear when they've come to the right place and when they should leave e.g.

This section describes the (refer to the API by the same name you give the page) that lets you retreive information about the state of the process and exert fine-grained control over its execution. If you're looking for the config file schema, see the Skaffold API (or whatever the new page title is).

You could also consider adding something here https://skaffold.dev/docs/design/api/ in case someone ends up there in error and should go to the other API

[ahmetb]

Rephrasing the description to make clear when they've come to the right place and when they should leave e.g.

Agreed, I added a similar warning #6503. Happy to take on to fix it that way.

I don't think we need to follow Tilt's way necessarily here. In their case, they have the main interaction method (config file) in the navbar (which you suggest at #6484). For us, the API should be something less discoverable, hence doesn't need that disambiguation IMO.