HTTP API: Add missing defaults/enums, fix mistakes #718

Simran-B · 2025-06-24T06:44:06Z

Description

TODOs:

If the default value depends on a startup option, should we refrain from specifying one in the OpenAPI description?
For example, replicationFactor is 1 by default in a cluster (and ignored in single server), but this depends on the --cluster.default-replication-factor startup options for user collections and on --cluster.system-replication-factor for system collections. If the startup options aren't set, then the default is indeed 1, but otherwise it has the value of the respective startup option. Should we therefore omit default: 1 and describe how the default value is determined in description? --> Describe in description how the default is determined. If we do this as a separate paragraph and like Default: Controlled by the --foo.bar` startup option, then it's also quick to find.
POST /_api/cursor:
- maxNumberOfPlans default? Internally 128 but controlled by --query.optimizer-max-plans
- maxRuntime default controlled by --query.max-runtime
- allowDirtyReads: default false? Duplicate remark from x-arango-allow-dirty-read header that it's ignored when run as part of Stream Transaction?
PUT /_db/{database-name}/_api/query-cache/properties: mention related startup options? (Copy from getting the cache config, or move?)
POST /_db/{database-name}/_api/transaction/begin: maxTransactionSize controlled by --transaction.streaming-max-transaction-size - note that this feature has been added in 3.12!

Upstream PRs

3.10:
3.11:
3.12:
3.13:

arangodb-docs-automation · 2025-06-24T06:44:09Z

Deploy Preview Available Via
https://deploy-preview-718--docs-hugo.netlify.app

site/content/3.11/develop/http-api/databases.md

…mention startup options, add missing slowStreamingQueryThreshold option

…p-api-2025-06-24

…ding

details parameter would require polymorphic response description (array or object) but we cannot render this at the moment

Missing defaults, add uniqueItems property for indexes, fix type/structure mistakes, reword some descriptions Certain endpoints like for transactions would require multiple types (string or array of strings), but we cannot render that yet

…p-api-2025-06-24

nerpaula · 2025-08-05T14:12:18Z

site/content/3.13/develop/http-api/users.md

              properties:
                user:
                  description: |
                    The name of the user as a string. This is mandatory.
                  type: string
                passwd:
                  description: |
-                    The user password as a string. If not specified, it will default to an empty
+                    The user password as a string. If not specified, it default to an empty


Suggested change

The user password as a string. If not specified, it default to an empty

The user password as a string. If not specified, it defaults to an empty

nerpaula · 2025-08-05T14:14:20Z

site/content/3.12/develop/http-api/users.md

              properties:
                user:
                  description: |
                    The name of the user as a string. This is mandatory.
                  type: string
                passwd:
                  description: |
-                    The user password as a string. If not specified, it will default to an empty
+                    The user password as a string. If not specified, it default to an empty


Suggested change

The user password as a string. If not specified, it default to an empty

The user password as a string. If not specified, it defaults to an empty

nerpaula · 2025-08-05T14:19:21Z

site/content/3.12/develop/http-api/databases.md

@@ -267,10 +278,10 @@ paths:
                      type: number
                users:
                  description: |
-                    An array of user objects. The users will be granted *Administrate* permissions
-                    for the new database. Users that do not exist yet will be created.
+                    An array of user objects. The users is granted *Administrate* permissions


Suggested change

An array of user objects. The users is granted *Administrate* permissions

An array of user objects. The user is granted *Administrate* permissions

nerpaula · 2025-08-05T14:20:08Z

site/content/3.11/develop/http-api/databases.md

@@ -269,10 +280,10 @@ paths:
                      type: number
                users:
                  description: |
-                    An array of user objects. The users will be granted *Administrate* permissions
-                    for the new database. Users that do not exist yet will be created.
+                    An array of user objects. The users is granted *Administrate* permissions


Suggested change

An array of user objects. The users is granted *Administrate* permissions

An array of user objects. The user is granted *Administrate* permissions

nerpaula · 2025-08-05T14:20:34Z

site/content/3.13/develop/http-api/databases.md

@@ -267,10 +278,10 @@ paths:
                      type: number
                users:
                  description: |
-                    An array of user objects. The users will be granted *Administrate* permissions
-                    for the new database. Users that do not exist yet will be created.
+                    An array of user objects. The users is granted *Administrate* permissions


Suggested change

An array of user objects. The users is granted *Administrate* permissions

An array of user objects. The user is granted *Administrate* permissions

nerpaula

Few typos to fix, other than that LGTM

HTTP API: Add some missing defaults/enums

2b62569

Simran-B self-assigned this Jun 24, 2025

cla-bot bot added the cla-signed label Jun 24, 2025

Simran-B commented Jun 24, 2025

View reviewed changes

site/content/3.11/develop/http-api/databases.md Outdated Show resolved Hide resolved

Simran-B commented Jun 24, 2025

View reviewed changes

site/content/3.11/develop/http-api/databases.md Outdated Show resolved Hide resolved

Simran-B added 9 commits June 24, 2025 17:03

More defaults, formatting, rev parameter in Gharial vertex/edge ops, …

bc56f4a

…mention startup options, add missing slowStreamingQueryThreshold option

Merge branch 'main' of https://github.com/arangodb/docs-hugo into htt…

4effde0

…p-api-2025-06-24

Named graphs: Remove docs for superfluous rev query param, some rewor…

7d44cef

…ding

Rewording, missing defaults

8269355

Index API: Backport changes to 3.11

6209ca5

Apply rewording to JS API docs

ba8466b

Rework concept page about key generators, add padded and uuid

0994f5d

Users: passwd is not mandatory, PUT resets access levels

5c2979c

Fix shard IDs example and missing response description

4d82664

details parameter would require polymorphic response description (array or object) but we cannot render this at the moment

Simran-B changed the title ~~HTTP API: Add some missing defaults/enums~~ HTTP API: Add missing defaults/enums, fix mistakes Jul 16, 2025

Simran-B added the 9 Waiting for CI label Jul 16, 2025

Simran-B added 5 commits August 4, 2025 14:06

maxTransactionSize not available in 3.11

3486d75

CSS: Make the version selector gray instead of green

74ccea8

Unify release notes

474dbbf

Finish up improvements to OpenAPI descriptions

db40dd9

Missing defaults, add uniqueItems property for indexes, fix type/structure mistakes, reword some descriptions Certain endpoints like for transactions would require multiple types (string or array of strings), but we cannot render that yet

Merge branch 'main' of https://github.com/arangodb/docs-hugo into htt…

3264abb

…p-api-2025-06-24

Simran-B requested a review from nerpaula August 4, 2025 12:18

nerpaula reviewed Aug 5, 2025

View reviewed changes

nerpaula approved these changes Aug 5, 2025

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

HTTP API: Add missing defaults/enums, fix mistakes #718

HTTP API: Add missing defaults/enums, fix mistakes #718

Uh oh!

Simran-B commented Jun 24, 2025 •

edited

Loading

Uh oh!

arangodb-docs-automation bot commented Jun 24, 2025

Uh oh!

Uh oh!

Uh oh!

nerpaula Aug 5, 2025

Uh oh!

nerpaula Aug 5, 2025

Uh oh!

nerpaula Aug 5, 2025

Uh oh!

nerpaula Aug 5, 2025

Uh oh!

nerpaula Aug 5, 2025

Uh oh!

nerpaula left a comment

Uh oh!

Uh oh!

	The user password as a string. If not specified, it default to an empty
	The user password as a string. If not specified, it defaults to an empty

	An array of user objects. The users is granted Administrate permissions
	An array of user objects. The user is granted Administrate permissions

HTTP API: Add missing defaults/enums, fix mistakes #718

Are you sure you want to change the base?

HTTP API: Add missing defaults/enums, fix mistakes #718

Uh oh!

Conversation

Simran-B commented Jun 24, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Upstream PRs

Uh oh!

arangodb-docs-automation bot commented Jun 24, 2025

Uh oh!

Uh oh!

Uh oh!

nerpaula Aug 5, 2025

Choose a reason for hiding this comment

Uh oh!

nerpaula Aug 5, 2025

Choose a reason for hiding this comment

Uh oh!

nerpaula Aug 5, 2025

Choose a reason for hiding this comment

Uh oh!

nerpaula Aug 5, 2025

Choose a reason for hiding this comment

Uh oh!

nerpaula Aug 5, 2025

Choose a reason for hiding this comment

Uh oh!

nerpaula left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Simran-B commented Jun 24, 2025 •

edited

Loading