URL in REST API spec isn't perfect

[nik9000]

In the rest-api-spec the we have an entry like:

    "documentation": "https://www.elastic.co/guide/en/elasticsearch/reference/master/docs-get.html",

The trouble with these is that we don't tend to update them in release branches. The 5.6 branch has:

    "documentation": "https://www.elastic.co/guide/en/elasticsearch/reference/5.x/docs-get.html",

That link is dead now. Further, 6.4 has:

    "documentation": "http://www.elastic.co/guide/en/elasticsearch/reference/master/docs-get.html",

If we're going to have these urls we should probably keep them up to date. This comes up when folks like @delvedor use those URLs in their generated documentation. They cause the docs build to fail because the referenced page doesn't exist.

Another option is to drop the prefix part of the url an rely on clients to "know" it. That'd be fine when generating documentation because we already have that prefix sitting around in an asciidoc variable but it'd be less nice for other folks that use the documentation.

[nik9000]

I'm not tagging this because I'm not actually sure what tag it should get....

[nik9000]

Some of the URLs just point to files that don't exist. I'll open a PR to fix them.

[elasticmachine]

Pinging @elastic/es-core-infra

[philkra]

Can we adjust the branch specifier in the docs URL to actual branch of the repo? That will solve the dead link problem and downstream consumers will receive a "healthy" URL.

Examples:
branch: 7.x --> "documentation": "http://www.elastic.co/guide/en/elasticsearch/reference/7.x/docs-get.html"
branch: 6.8 --> "documentation": "http://www.elastic.co/guide/en/elasticsearch/reference/6.8/docs-get.html"
branch: master --> "documentation": "http://www.elastic.co/guide/en/elasticsearch/reference/master/docs-get.html"

/cc @elastic/clients-team

[nik9000]

Can we adjust the branch specifier in the docs URL to actual branch of the repo? That will solve the dead link problem and downstream consumers will receive a "healthy" URL.

Sorry, I don't understand.

But you did get me to thinking - maybe the "documentation" should just be the file at the end there. The docs-get.html. The rest should come from the version.

The docs build has a fairly janky way of checking URLs at the moment customized for kibana. I'd always wanted it to have a more generic way but I never got around to it. Maybe we could make a .ci/extract_links script that the docs build count run that'd spit out all the links we want it to check to stdout. It could pick them up and check them.

The advantage of letting the docs build check the links is that it can check them against the current PR. And it can check cross product links. I don't have any clue if its compatible with the new docs work, but it could be a thing. @gtback

[philkra]

Sorry, I was a bit terse. Your suggestion would work too! My goal is that we should have a single source of truth.