From 1df73828ededae3f588f4b64db8ac5fed65d3b52 Mon Sep 17 00:00:00 2001 From: James Rodewig Date: Mon, 23 Mar 2020 07:36:37 -0400 Subject: [PATCH] [DOCS] Note doc links should be live in REST API JSON specs (#53871) Downstream Elasticsearch clients, such as the Elaticsearch-JS client, use the documentation links in our REST API JSON specifications to create their docs. Using a broken link or linking to yet-to-be-created doc pages can break the docs build for these clients. This PR adds a related note to the README for the REST API JSON Specs. --- rest-api-spec/README.markdown | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/rest-api-spec/README.markdown b/rest-api-spec/README.markdown index 15b3c1494190..e2c3d37f11da 100644 --- a/rest-api-spec/README.markdown +++ b/rest-api-spec/README.markdown @@ -43,7 +43,12 @@ Example for the ["Create Index"](https://www.elastic.co/guide/en/elasticsearch/r The specification contains: * The _name_ of the API (`indices.create`), which usually corresponds to the client calls -* Link to the documentation at the website +* Link to the documentation at the website. + + **IMPORANT:** This should be a _live_ link. Several downstream ES clients use + this link to generate their documentation. Using a broken link or linking to + yet-to-be-created doc pages can break the [Elastic docs + build](https://github.com/elastic/docs#building-documentation). * `stability` indicating the state of the API, has to be declared explicitly or YAML tests will fail * `experimental` highly likely to break in the near future (minor/patch), no bwc guarantees. Possibly removed in the future.