BTS-1715 | PUT /_admin/license takes a JSON string (#380)

* PUT /_admin/license takes a JSON string

Add 501 error code and example (values)

* Adjust upgrading description

Author: Simran-B

site/content/3.10/develop/http-api/administration.md

@@ -758,16 +758,14 @@ paths:
         Can be called on single servers, Coordinators, and DB-Servers.
       responses:
         '200':
-          description: ''
+          description: |
+            Returns the license information.
           content:
             application/json:
               schema:
                 type: object
                 required:
-                  - features
                   - license
-                  - version
-                  - status
                 properties:
                   features:
                     description: |
@@ -781,14 +779,23 @@ paths:
                           The `expires` key lists the expiry date as Unix timestamp (seconds since
                           January 1st, 1970 UTC).
                         type: number
+                        example: 1683173040
                   license:
                     description: |
-                      The encrypted license key in Base64 encoding.
+                      The encrypted license key in Base64 encoding, or `"none"`
+                      in the Community Edition.
+                    type: string
+                    example: V0h/W...wEDw==
+                  hash:
+                    description: |
+                      The hash value of the license.
                     type: string
+                    example: 982db5...44f3
                   version:
                     description: |
                       The license version number.
                     type: number
+                    example: 1
                   status:
                     description: |
                       The `status` key allows you to confirm the state of the installed license on a
@@ -801,6 +808,12 @@ paths:
                       - `read-only`: The license is expired over 2 weeks. The instance is now
                         restricted to read-only mode.
                     type: string
+                    example: good
+                  upgrading:
+                    description: |
+                      Whether the server is performing a database upgrade.
+                    type: boolean
+                    example: false
       tags:
         - Administration
 ```
@@ -841,29 +854,143 @@ paths:
             Set to `true` to change the license even if it expires sooner than the current one.
           schema:
             type: boolean
+            default: false
       requestBody:
         content:
           application/json:
             schema:
-              type: object
-              required:
-                - license
-              properties:
-                license:
-                  description: |
-                    The request body has to contain the Base64-encoded string wrapped in double quotes.
-                  type: string
+              description: |
+                The request body has to contain the Base64-encoded string wrapped in double quotes.
+              type: string
+              example: eyJncmFudCI6...(Base64-encoded license string)...
       responses:
-        '400':
-          description: |
-            If the license expires earlier than the previously installed one.
         '201':
           description: |
             License successfully deployed.
+          content:
+            application/json:
+              schema:
+                type: object
+                required:
+                  - result
+                properties:
+                  result:
+                    type: object
+                    required:
+                      - error
+                      - code
+                    properties:
+                      error:
+                        description: |
+                          A flag indicating that no error occurred.
+                        type: boolean
+                        example: false
+                      code:
+                        description: |
+                          The HTTP status code.
+                        type: integer
+                        example: 201
+        '400':
+          description: |
+            If the license expires earlier than the previously installed one,
+            or if the supplied license string is invalid.
+          content:
+            application/json:
+              schema:
+                type: object
+                required:
+                  - error
+                  - code
+                  - errorNum
+                  - errorMessage
+                properties:
+                  error:
+                    description: |
+                      A flag indicating that an error occurred.
+                    type: boolean
+                    example: true
+                  code:
+                    description: |
+                      The HTTP status code.
+                    type: integer
+                    example: 400
+                  errorNum:
+                    description: |
+                      The ArangoDB error number.
+                    type: integer
+                  errorMessage:
+                    description: |
+                      A descriptive error message.
+                    type: string
+        '501':
+          description: |
+            If you try to apply a license in the Community Edition.
+          content:
+            application/json:
+              schema:
+                type: object
+                required:
+                  - error
+                  - code
+                  - errorNum
+                  - errorMessage
+                properties:
+                  error:
+                    description: |
+                      A flag indicating that an error occurred.
+                    type: boolean
+                    example: true
+                  code:
+                    description: |
+                      The HTTP status code.
+                    type: integer
+                    example: 501
+                  errorNum:
+                    description: |
+                      The ArangoDB error number.
+                    type: integer
+                  errorMessage:
+                    description: |
+                      A descriptive error message.
+                    type: string
       tags:
         - Administration
 ```
 
+**Examples**
+
+{{< comment >}}
+Example not generated because it would require a valid license to demonstrate the API.
+{{< /comment >}}
+
+```bash
+curl --header 'accept: application/json' --dump - --data '"eyJncmFudCI6...(Base64-encoded license string)..."' -X PUT http://localhost:8529/_admin/license
+```
+
+{{< expand title="Show output" >}}
+```bash
+HTTP/1.1 201 Created
+content-type: application/json
+cache-control: no-cache, no-store, must-revalidate, pre-check=0, post-check=0, max-age=0, s-maxage=0
+connection: Keep-Alive
+content-length: 37
+content-security-policy: frame-ancestors 'self'; form-action 'self';
+expires: 0
+pragma: no-cache
+server: ArangoDB
+strict-transport-security: max-age=31536000 ; includeSubDomains
+x-arango-queue-time-seconds: 0.000000
+x-content-type-options: nosniff
+
+{
+  "result": {
+    "error": false,
+    "code": 201
+  }
+}
+```
+{{< /expand >}}
+
 ## Shutdown
 
 ### Start the shutdown sequence