From e1726fff5681ab4f98f4f26e703bc9ea5ebacbc9 Mon Sep 17 00:00:00 2001
From: James Rodewig <james.rodewig@elastic.co>
Date: Thu, 14 Nov 2019 07:59:56 -0500
Subject: [PATCH] [DOCS] Reformat update license API docs (#48967)

Makes a few changes to better align the update license API docs with
the [API reference template][0].

Changes:

* Replaces POST with PUT in several snippet examples.
  While both are valid, PUT is a bit more RESTful.

* Removes leading slashes (/) from all snippets.

* Relocates and retitles the 'Authorization' section to 'Prerequisites'.

* Replaces explicit titles with the appropriate API reference template
  attributes.

* Replaces unneeded `[float]` tags with explicit anchors.

Closes #35341

[0]: https://github.com/elastic/docs/blob/master/shared/api-ref-ex.asciidoc
---
 .../licensing/update-license.asciidoc         | 56 ++++++++++---------
 1 file changed, 29 insertions(+), 27 deletions(-)

diff --git a/docs/reference/licensing/update-license.asciidoc b/docs/reference/licensing/update-license.asciidoc
index 268e0b768b5..e286107ef6c 100644
--- a/docs/reference/licensing/update-license.asciidoc
+++ b/docs/reference/licensing/update-license.asciidoc
@@ -8,13 +8,25 @@
 
 This API enables you to update your license.
 
-[float]
-==== Request
+[[update-license-api-request]]
+==== {api-request-title}
 
-`PUT /_license`
+`PUT _license`
 
-[float]
-==== Description
+`POST _license`
+
+[[update-license-api-prereqs]]
+==== {api-prereq-title}
+
+If {es} {security-features} are enabled, you need `manage` cluster privileges to
+install the license.
+
+If {es} {security-features} are enabled and you are installing a gold or platinum
+license, you must enable TLS on the transport networking layer before you
+install the license. See <<configuring-tls>>.
+
+[[update-license-api-desc]]
+==== {api-description-title}
 
 You can update your license at runtime without shutting down your nodes.
 License updates take effect immediately.  If the license you are installing does
@@ -25,39 +37,29 @@ request with the `acknowledge` parameter set to `true`.
 For more information about the different types of licenses, see
 https://www.elastic.co/subscriptions.
 
-[float]
-==== Query Parameters
+[[update-license-api-query-params]]
+==== {api-query-parms-title}
 
 `acknowledge`::
-  (boolean) Specifies whether you acknowledge the license changes. The default
+  (Optional, boolean)
+  Specifies whether you acknowledge the license changes. The default
   value is `false`.
 
-[float]
-==== Request Body
+[[update-license-api-request-body]]
+==== {api-request-body-title}
 
 `licenses`::
-  (array) A sequence of one or more JSON documents containing the license
-  information.
+  (Required, array)
+  A sequence of one or more JSON documents containing the license information.
 
-
-[float]
-==== Authorization
-
-If {es} {security-features} are enabled, you need `manage` cluster privileges to
-install the license.
-
-If {es} {security-features} are enabled and you are installing a gold or platinum
-license, you must enable TLS on the transport networking layer before you
-install the license. See <<configuring-tls>>.
-
-[float]
-==== Examples
+[[update-license-api-example]]
+==== {api-examples-title}
 
 The following example updates to a basic license:
 
 [source,console]
 ------------------------------------------------------------
-POST /_license
+PUT _license
 {
   "licenses": [
     {
@@ -133,7 +135,7 @@ To complete the update, you must re-submit the API request and set the
 
 [source,console]
 ------------------------------------------------------------
-POST /_license?acknowledge=true
+PUT _license?acknowledge=true
 {
   "licenses": [
     {