[8.11] [Docs][Maps] Include details about the headers requested and s…

…erved by EMS (#171659) (#172090)

# Backport

This will backport the following commits from `main` to `8.11`:
- [[Docs][Maps] Include details about the headers requested and served
by EMS (#171659)](#171659)

<!--- Backport version: 8.9.7 -->

### Questions ?
Please refer to the [Backport tool
documentation](https://github.com/sqren/backport)

<!--BACKPORT [{"author":{"name":"Jorge
Sanz","email":"[email protected]"},"sourceCommit":{"committedDate":"2023-11-28T16:59:28Z","message":"[Docs][Maps]
Include details about the headers requested and served by EMS
(#171659)\n\nFixes #129751\r\n\r\n## Summary\r\n\r\nExtends the EMS
documentation to detail request and response headers the\r\nbrowser
sends to EMS resources and includes also a minimal `curl`\r\ncommand to
request the response headers for same resource as well.\r\n\r\nI tried
to edit this in a way it does not take the whole page but happy\r\nto
hear feedback or ideas on how to make this easier to
digest.\r\n\r\n\r\nhttps://github.com/elastic/kibana/assets/188264/27e83a5f-4d01-47a8-af2c-3739576bf56e\r\n\r\n\r\nAlso,
I am not sure if this is something worth adding to our release\r\nnotes
:thinking:","sha":"0a7299b0ac2aadfe47aa374002636341a032a6ed","branchLabelMapping":{"^v8.12.0$":"main","^v(\\d+).(\\d+).\\d+$":"$1.$2"}},"sourcePullRequest":{"labels":["release_note:skip","docs","backport:all-open","v8.12.0"],"number":171659,"url":"https://github.com/elastic/kibana/pull/171659","mergeCommit":{"message":"[Docs][Maps]
Include details about the headers requested and served by EMS
(#171659)\n\nFixes #129751\r\n\r\n## Summary\r\n\r\nExtends the EMS
documentation to detail request and response headers the\r\nbrowser
sends to EMS resources and includes also a minimal `curl`\r\ncommand to
request the response headers for same resource as well.\r\n\r\nI tried
to edit this in a way it does not take the whole page but happy\r\nto
hear feedback or ideas on how to make this easier to
digest.\r\n\r\n\r\nhttps://github.com/elastic/kibana/assets/188264/27e83a5f-4d01-47a8-af2c-3739576bf56e\r\n\r\n\r\nAlso,
I am not sure if this is something worth adding to our release\r\nnotes
:thinking:","sha":"0a7299b0ac2aadfe47aa374002636341a032a6ed"}},"sourceBranch":"main","suggestedTargetBranches":[],"targetPullRequestStates":[{"branch":"main","label":"v8.12.0","labelRegex":"^v8.12.0$","isSourceBranch":true,"state":"MERGED","url":"https://github.com/elastic/kibana/pull/171659","number":171659,"mergeCommit":{"message":"[Docs][Maps]
Include details about the headers requested and served by EMS
(#171659)\n\nFixes #129751\r\n\r\n## Summary\r\n\r\nExtends the EMS
documentation to detail request and response headers the\r\nbrowser
sends to EMS resources and includes also a minimal `curl`\r\ncommand to
request the response headers for same resource as well.\r\n\r\nI tried
to edit this in a way it does not take the whole page but happy\r\nto
hear feedback or ideas on how to make this easier to
digest.\r\n\r\n\r\nhttps://github.com/elastic/kibana/assets/188264/27e83a5f-4d01-47a8-af2c-3739576bf56e\r\n\r\n\r\nAlso,
I am not sure if this is something worth adding to our release\r\nnotes
:thinking:","sha":"0a7299b0ac2aadfe47aa374002636341a032a6ed"}}]}]
BACKPORT-->

Co-authored-by: Jorge Sanz <[email protected]>

docs/maps/connect-to-ems.asciidoc

@@ -3,17 +3,58 @@
 
 :ems-docker-repo: docker.elastic.co/elastic-maps-service/elastic-maps-server-ubi8
 :ems-docker-image: {ems-docker-repo}:{version}
+:ems-headers-url: https://deployment-host
 
 https://www.elastic.co/elastic-maps-service[Elastic Maps Service (EMS)] is a service that hosts
 tile layers and vector shapes of administrative boundaries.
 If you are using Kibana's out-of-the-box settings, Maps is already configured to use EMS.
 
+[float]
+=== Domains
+
 EMS requests are made to the following domains:
 
-* tiles.maps.elastic.co
-* vector.maps.elastic.co
+* Tile Service: `tiles.maps.elastic.co`
+* File Service: `vector.maps.elastic.co`
+
+[float]
+=== Headers
+
+Find below examples of the request and response headers from Kibana and a minimal `curl` request example showing the response headers sent by each service.
+
+WARNING: These headers may change without further notice at anytime and are shared for reference.
+
+[float]
+==== EMS Tile Service
+
+The EMS Tile Service provides basemaps in three different styles as the default background for Maps visualizations. The basemaps use https://www.openstreetmap.org/about[OpenStreetMap] data following the https://openmaptiles.org/[OpenMapTiles] schema and can be explored at https://maps.elastic.co[maps.elastic.co].
+
+Headers for the Tile Service JSON manifest describing the basemaps available.
+
+include::headers/tile-json.asciidoc[]
+
+Headers for a vector tile asset in _protobuffer_ format from the Tile Service.
+
+include::headers/tile-pbf.asciidoc[]
+
+Headers for an sprite image asset from the Tile Service
+
+include::headers/tile-png.asciidoc[]
+
+
+[float]
+==== EMS File Service
+
+EMS File Service provides the administrative boundaries used for <<maps-add-choropleth-layer,choropleth mapping>> as static assets in GeoJSON or TopoJSON formats and can be explored at https://maps.elastic.co[maps.elastic.co].
+
+Headers for the File Service JSON manifest that declares all the datasets available.
+
+include::headers/file-json.asciidoc[]
+
+Headers for a sample Dataset from the File Service in TopoJSON format.
+
+include::headers/file-data.asciidoc[]
 
-Maps makes requests directly from the browser to EMS.
 
 [float]
 === Disable Elastic Maps Service

docs/maps/headers/file-data.asciidoc

@@ -0,0 +1,131 @@
+
+++++
+<div class="tabs" data-tab-group="file-data-tab-group-name">
+  <div role="tablist" aria-label="Request and response to the File Service for Dataset">
+    <button role="tab"
+            aria-selected="true"
+            aria-controls="file-data-tab-group-curl"
+            id="file-data-group-curl">
+      Curl example
+    </button>
+    <button role="tab"
+            aria-selected="false"
+            aria-controls="file-data-tab-group-request"
+            id="file-data-group-request"
+            tabindex="-1">
+      Request
+    </button>
+    <button role="tab"
+            aria-selected="false"
+            aria-controls="file-data-tab-group-response"
+            id="file-data-group-response"
+            tabindex="-2">
+      Response
+    </button>
+  </div>
+  <div tabindex="0"
+       role="tabpanel"
+       id="file-data-tab-group-curl"
+       aria-labelledby="file-data-group-curl">
+++++
+[%collapsible]
+====
+[source,bash,subs="attributes"]
+----------------------------------
+curl -I 'https://vector.maps.elastic.co/files/world_countries_v7.topo.json?elastic_tile_service_tos=agree&my_app_name=kibana&my_app_version={version}' \
+-H 'User-Agent: curl/7.81.0' \
+-H 'Accept: */*' \
+-H 'Accept-Encoding: gzip, deflate, br'
+----------------------------------
+
+Server response
+
+[source,regex]
+----------------------------------
+HTTP/2 200 
+x-guploader-uploadid: ABPtcPpmMffchVgfHIr-SSC00WORo145oV-1q0asjqRvjLV_7cIgyfLRfofXV-BG7huMYABFypblcgdgXRBARhpo2c88ow
+x-goog-generation: 1689593325442971
+x-goog-metageneration: 1
+x-goog-stored-content-encoding: gzip
+x-goog-stored-content-length: 587241
+content-encoding: gzip
+x-goog-hash: crc32c=OcROeg==
+x-goog-hash: md5=8KKIwD6wbKa3YYXTnnFcZw==
+x-goog-storage-class: MULTI_REGIONAL
+accept-ranges: bytes
+content-length: 587241
+access-control-allow-origin: *
+access-control-expose-headers: Authorization, Content-Length, Content-Type, Date, Server, Transfer-Encoding, X-GUploader-UploadID, X-Google-Trace, accept, elastic-api-version, kbn-name, kbn-version, origin
+server: UploadServer
+date: Tue, 21 Nov 2023 14:22:16 GMT
+expires: Tue, 21 Nov 2023 15:22:16 GMT
+cache-control: public, max-age=3600,no-transform
+age: 2202
+last-modified: Mon, 17 Jul 2023 11:28:45 GMT
+etag: "f0a288c03eb06ca6b76185d39e715c67"
+content-type: application/json
+alt-svc: h3=":443"; ma=2592000,h3-29=":443"; ma=2592000
+----------------------------------
+====
+++++
+  </div>
+  <div tabindex="1"
+       role="tabpanel"
+       id="file-data-tab-group-request"
+       aria-labelledby="file-data-group-request"
+       hidden="">
+++++
+[source,regex,subs="attributes"]
+----------------------------------
+Host: vector.maps.elastic.co
+User-Agent: Mozilla/5.0 (X11; Ubuntu; Linux x86_64; rv:109.0) Gecko/20100101 Firefox/119.0
+Accept: */*
+Accept-Language: en-US,en;q=0.5
+Accept-Encoding: gzip, deflate, br
+Referer: {ems-headers-url}/app/maps/map
+Origin: {ems-headers-url}
+Connection: keep-alive
+Sec-Fetch-Dest: empty
+Sec-Fetch-Mode: cors
+Sec-Fetch-Site: cross-site
+Pragma: no-cache
+Cache-Control: no-cache
+----------------------------------
+++++
+  </div>
+  <div tabindex="2"
+       role="tabpanel"
+       id="file-data-tab-group-response"
+       aria-labelledby="file-data-group-response"
+       hidden="">
+++++
+[source,regex]
+----------------------------------
+x-guploader-uploadid: ABPtcPqIDSg5tyavvwwtJQa8a8iycoXOCkHBp_2YJbJJnQgb5XMD7nFwRUogg00Ou27VFIs95v7L99OMnvXR1bcb9RW-xQ
+x-goog-generation: 1689593325442971
+x-goog-metageneration: 1
+x-goog-stored-content-encoding: gzip
+x-goog-stored-content-length: 587241
+content-encoding: gzip
+x-goog-hash: crc32c=OcROeg==
+x-goog-hash: md5=8KKIwD6wbKa3YYXTnnFcZw==
+x-goog-storage-class: MULTI_REGIONAL
+accept-ranges: bytes
+content-length: 587241
+access-control-allow-origin: *
+access-control-expose-headers: Authorization, Content-Length, Content-Type, Date, Server, Transfer-Encoding, X-GUploader-UploadID, X-Google-Trace, accept, elastic-api-version, kbn-name, kbn-version, origin
+server: UploadServer
+date: Tue, 21 Nov 2023 12:16:01 GMT
+expires: Tue, 21 Nov 2023 13:16:01 GMT
+cache-control: public, max-age=3600,no-transform
+age: 29
+last-modified: Mon, 17 Jul 2023 11:28:45 GMT
+etag: "f0a288c03eb06ca6b76185d39e715c67"
+content-type: application/json
+alt-svc: h3=":443"; ma=2592000,h3-29=":443"; ma=2592000
+X-Firefox-Spdy: h2
+----------------------------------
+++++
+  </div>
+</div>
+++++

docs/maps/headers/file-json.asciidoc

@@ -0,0 +1,132 @@
+
+++++
+<div class="tabs" data-tab-group="file-json-tab-group-name">
+  <div role="tablist" aria-label="Request and response to the File Service for a JSON Asset">
+    <button role="tab"
+            aria-selected="true"
+            aria-controls="file-json-tab-group-curl"
+            id="file-json-group-curl"
+            >
+      Curl example
+    </button>
+    <button role="tab"
+            aria-selected="false"
+            aria-controls="file-json-tab-group-request"
+            id="file-json-group-request"
+            tabindex="-1">
+      Request
+    </button>
+    <button role="tab"
+            aria-selected="false"
+            aria-controls="file-json-tab-group-response"
+            id="file-json-group-response"
+            tabindex="-2">
+      Response
+    </button>
+  </div>
+  <div tabindex="0"
+       role="tabpanel"
+       id="file-json-tab-group-curl"
+       aria-labelledby="file-json-group-curl">
+++++
+[%collapsible]
+====
+[source,bash,subs="attributes"]
+----------------------------------
+curl -I 'https://vector.maps.elastic.co/v{minor-version}/manifest?elastic_tile_service_tos=agree&my_app_name=kibana&my_app_version={version}' \
+-H 'User-Agent: curl/7.81.0' \
+-H 'Accept: */*' \
+-H 'Accept-Encoding: gzip, deflate, br'
+----------------------------------
+
+Server response
+
+[source,regex]
+----------------------------------
+HTTP/2 200 
+x-guploader-uploadid: ABPtcPp_BvMdBDO5jVlutETVHmvpOachwjilw4AkIKwMrOQJ4exR9Eln4g0LkW3V_LLSEpvjYLtUtFmO0Uwr61XXUhoP_A
+x-goog-generation: 1689593295246576
+x-goog-metageneration: 1
+x-goog-stored-content-encoding: gzip
+x-goog-stored-content-length: 108029
+content-encoding: gzip
+x-goog-hash: crc32c=T5gVpw==
+x-goog-hash: md5=6F8KWV8VTdx8FsN2iFehow==
+x-goog-storage-class: MULTI_REGIONAL
+accept-ranges: bytes
+content-length: 108029
+access-control-allow-origin: *
+access-control-expose-headers: Authorization, Content-Length, Content-Type, Date, Server, Transfer-Encoding, X-GUploader-UploadID, X-Google-Trace, accept, elastic-api-version, kbn-name, kbn-version, origin
+server: UploadServer
+date: Tue, 21 Nov 2023 14:25:07 GMT
+expires: Tue, 21 Nov 2023 15:25:07 GMT
+cache-control: public, max-age=3600,no-transform
+age: 2170
+last-modified: Mon, 17 Jul 2023 11:28:15 GMT
+etag: "e85f0a595f154ddc7c16c3768857a1a3"
+content-type: application/json
+alt-svc: h3=":443"; ma=2592000,h3-29=":443"; ma=2592000
+----------------------------------
+====
+++++
+  </div>
+  <div tabindex="1"
+       role="tabpanel"
+       id="file-json-tab-group-request"
+       aria-labelledby="file-json-group-request"
+       hidden="">
+++++
+[source,regex,subs="attributes"]
+----------------------------------
+Host: vector.maps.elastic.co
+User-Agent: Mozilla/5.0 (X11; Ubuntu; Linux x86_64; rv:109.0) Gecko/20100101 Firefox/119.0
+Accept: */*
+Accept-Language: en-US,en;q=0.5
+Accept-Encoding: gzip, deflate, br
+Referer: {ems-headers-url}/app/maps/map
+Origin: {ems-headers-url}
+Connection: keep-alive
+Sec-Fetch-Dest: empty
+Sec-Fetch-Mode: cors
+Sec-Fetch-Site: cross-site
+Pragma: no-cache
+Cache-Control: no-cache
+----------------------------------
+++++
+  </div>
+  <div tabindex="2"
+       role="tabpanel"
+       id="file-json-tab-group-response"
+       aria-labelledby="file-json-group-response"
+       hidden="">
+++++
+[source,regex]
+----------------------------------
+x-guploader-uploadid: ABPtcPoUFrCmjBeebnfRxSZp44ZHsZ-_iQg7794RU1Z7Lb2cNNxXsMRkIDa5s7VBEfyehvo-_9rcm1A3HfYW8geguUxKrw
+x-goog-generation: 1689593295246576
+x-goog-metageneration: 1
+x-goog-stored-content-encoding: gzip
+x-goog-stored-content-length: 108029
+content-encoding: gzip
+x-goog-hash: crc32c=T5gVpw==
+x-goog-hash: md5=6F8KWV8VTdx8FsN2iFehow==
+x-goog-storage-class: MULTI_REGIONAL
+accept-ranges: bytes
+content-length: 108029
+access-control-allow-origin: *
+access-control-expose-headers: Authorization, Content-Length, Content-Type, Date, Server, Transfer-Encoding, X-GUploader-UploadID, X-Google-Trace, accept, elastic-api-version, kbn-name, kbn-version, origin
+server: UploadServer
+date: Tue, 21 Nov 2023 11:24:45 GMT
+expires: Tue, 21 Nov 2023 12:24:45 GMT
+cache-control: public, max-age=3600,no-transform
+age: 3101
+last-modified: Mon, 17 Jul 2023 11:28:15 GMT
+etag: "e85f0a595f154ddc7c16c3768857a1a3"
+content-type: application/json
+alt-svc: h3=":443"; ma=2592000,h3-29=":443"; ma=2592000
+X-Firefox-Spdy: h2
+----------------------------------
+++++
+  </div>
+</div>
+++++