From 07816c40b3acabca2c9953c5dd075e2b5e49ddac Mon Sep 17 00:00:00 2001 From: Simran Spiller Date: Fri, 8 Dec 2023 13:43:04 +0100 Subject: [PATCH 1/2] PUT /_admin/license takes a JSON string Add 501 error code and example (values) --- .../3.10/develop/http-api/administration.md | 159 ++++++++++++++++-- .../3.11/develop/http-api/administration.md | 159 ++++++++++++++++-- .../3.12/develop/http-api/administration.md | 159 ++++++++++++++++-- 3 files changed, 429 insertions(+), 48 deletions(-) diff --git a/site/content/3.10/develop/http-api/administration.md b/site/content/3.10/develop/http-api/administration.md index 89540cde3c..04ec36c636 100644 --- a/site/content/3.10/develop/http-api/administration.md +++ b/site/content/3.10/develop/http-api/administration.md @@ -753,16 +753,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: | @@ -776,14 +774,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 @@ -796,6 +803,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 a license upgrade is in progress. + type: boolean + example: false tags: - Administration ``` @@ -836,29 +849,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 diff --git a/site/content/3.11/develop/http-api/administration.md b/site/content/3.11/develop/http-api/administration.md index 2e1ad78c8d..5322167fe9 100644 --- a/site/content/3.11/develop/http-api/administration.md +++ b/site/content/3.11/develop/http-api/administration.md @@ -754,16 +754,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: | @@ -777,14 +775,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 @@ -797,6 +804,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 a license upgrade is in progress. + type: boolean + example: false tags: - Administration ``` @@ -837,29 +850,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 diff --git a/site/content/3.12/develop/http-api/administration.md b/site/content/3.12/develop/http-api/administration.md index 933f28f962..f8e807f75c 100644 --- a/site/content/3.12/develop/http-api/administration.md +++ b/site/content/3.12/develop/http-api/administration.md @@ -734,16 +734,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: | @@ -757,14 +755,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 @@ -777,6 +784,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 a license upgrade is in progress. + type: boolean + example: false tags: - Administration ``` @@ -817,29 +830,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 From 9cadb45e42d07718cf797340b369f640acdfec9f Mon Sep 17 00:00:00 2001 From: Simran Spiller Date: Mon, 11 Dec 2023 12:42:07 +0100 Subject: [PATCH 2/2] Adjust upgrading description --- site/content/3.10/develop/http-api/administration.md | 2 +- site/content/3.11/develop/http-api/administration.md | 2 +- site/content/3.12/develop/http-api/administration.md | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/site/content/3.10/develop/http-api/administration.md b/site/content/3.10/develop/http-api/administration.md index 04ec36c636..e9dffe32c2 100644 --- a/site/content/3.10/develop/http-api/administration.md +++ b/site/content/3.10/develop/http-api/administration.md @@ -806,7 +806,7 @@ paths: example: good upgrading: description: | - Whether a license upgrade is in progress. + Whether the server is performing a database upgrade. type: boolean example: false tags: diff --git a/site/content/3.11/develop/http-api/administration.md b/site/content/3.11/develop/http-api/administration.md index 5322167fe9..f6f330d609 100644 --- a/site/content/3.11/develop/http-api/administration.md +++ b/site/content/3.11/develop/http-api/administration.md @@ -807,7 +807,7 @@ paths: example: good upgrading: description: | - Whether a license upgrade is in progress. + Whether the server is performing a database upgrade. type: boolean example: false tags: diff --git a/site/content/3.12/develop/http-api/administration.md b/site/content/3.12/develop/http-api/administration.md index f8e807f75c..a4b0dcc962 100644 --- a/site/content/3.12/develop/http-api/administration.md +++ b/site/content/3.12/develop/http-api/administration.md @@ -787,7 +787,7 @@ paths: example: good upgrading: description: | - Whether a license upgrade is in progress. + Whether the server is performing a database upgrade. type: boolean example: false tags: