Shape of the OpenAPI specification

[daliboris]

Is your feature request related to a problem? Please describe.
I looked at OpenAPI from the perspective of the best practices of the REST API and current OpenAPI looks like an interface between the current eXist-db API and the user.

However, OpenAPI can serve as a new way of looking at an XML database—that is, as a repository of resources that can be manipulated in various ways: creating, modifying, deleting, and so on.

Describe the solution you'd like
I asked AI (qwen3.5-122b) and following results makes sense to me:

Category	Original Endpoint (Path)	New Endpoint (Path)	Reason for Change
System	GET /api/system/info	GET /api/system	Simplification. System information is the primary resource at the /system root.
System	GET /api/system/scheduler	GET /api/system/jobs	Plural (jobs) for a list of tasks. The word "scheduler" implies an action, not a resource.
System	POST /api/test	POST /api/system/tests	Tests are resources executed in the context of the system. Using plural and grouping under system.
Queries	POST /api/query	POST /api/queries	Creating a new query instance is an operation on the queries collection.
Queries	GET /api/query/{id}/results	GET /api/queries/{id}/results	Consistency with the new collection name queries.
Queries	DELETE /api/query/{id}	DELETE /api/queries/{id}	Closing the cursor is an operation on a specific query.
Queries	POST /api/query/{id}/cancel	POST /api/queries/{id}/cancel	The cancel action remains as a sub-resource or action on the query, but the path is now consistent.
Queries	POST /api/eval	POST /api/queries/evaluate	One-off evaluation is a special case of a query. Grouped under the queries collection. Other action endpoints use full verbs or clear nouns (e.g., check-updates, resolve). Using evaluate aligns better with this pattern than the truncated eval.
Language Service	GET /api/langservice/capabilities	GET /api/language-service	Simplified name. The service itself returns its capabilities.
Language Service	POST /api/langservice/diagnostics	POST /api/language-service/analyze	analyze is a clearer description of the action than diagnostics (which is often the output). Alternatively, keep /diagnostics as the result of analysis. Note: To preserve semantics, I propose /analyze.
Language Service	POST /api/langservice/completions	POST /api/language-service/suggest	suggest is more common for code suggestions. Or keep /completions as an LSP specification.
Language Service	POST /api/langservice/hover	POST /api/language-service/hover	Kept, but moved to a new path.
Language Service	POST /api/langservice/signature-help	POST /api/language-service/signatures	Plural, consistency.
Language Service	POST /api/langservice/symbols	POST /api/language-service/symbols	Kept, moved.
Database	GET /api/db	GET /api/resources	db is too generic. The root resource should be resources (or documents).
Database	GET /api/db/resource	GET /api/resources/{path}	Dynamic path via path parameter instead of a separate endpoint for getting content.
Database	PUT /api/db/resource	PUT /api/resources	Storing a resource in the database. The path is determined in the body or query parameter, but the endpoint represents an action over resources. Better option: POST /api/resources for creation, PUT /api/resources/{path} for update.
Database	DELETE /api/db/resource	DELETE /api/resources/{path}	Removing a specific resource.
Database	GET /api/db/collection (in GET)	GET /api/collections/{path}	Getting properties or content of a collection.
Database	POST /api/db/collection	POST /api/collections	Creating a new collection.
Database	DELETE /api/db/collection (in DELETE)	DELETE /api/collections/{path}	Removing a collection.
Database	GET /api/db/properties	GET /api/resources/{path}/metadata	Metadata (properties) are a sub-resource of the source.
Database	POST /api/db/permissions	PATCH /api/resources/{path}/permissions	Updating permissions is a state change of the resource. PATCH is more appropriate than POST.
Database	POST /api/db/copy	POST /api/resources/copy	Copy action at the resource collection level.
Database	POST /api/db/move	POST /api/resources/move	Move action at the resource collection level.
Database	GET /api/db/sync	GET /api/resources/sync	Synchronization stream of resources.
Users	GET /api/users/whoami	GET /api/users/me	Standard REST convention for the current user.
Users	GET /api/users	GET /api/users	Kept (plural).
Groups	GET /api/groups/{name}	GET /api/groups/{name}	Kept.
Groups	DELETE /api/groups/{name}	DELETE /api/groups/{name}	Kept.
Packages	GET /api/packages	GET /api/packages	Kept.
Packages	POST /api/packages/install	POST /api/packages	Installing a package is often interpreted as creating an instance. Alternative: POST /api/packages/deploy. For clarity, I propose POST /api/packages with a body containing source or url.
Packages	GET /api/packages/{name}	GET /api/packages/{name}	Kept.
Packages	DELETE /api/packages/{name}	DELETE /api/packages/{name}	Kept.
Packages	POST /api/packages/update-check	POST /api/packages/check-updates	Clearer action.
Search	GET /api/search	GET /api/search	Kept, but could be GET /api/search/documents.
Site	GET /api/site/apps	GET /api/applications	applications is a fuller name than apps, placed directly under the API root for better accessibility.
Site	GET /api/site/resolve	POST /api/links/resolve	Resolving links is an action. The links group is suitable.

Describe alternatives you've considered
This is just a first attempt, meant to start a discussion. That is, if it's not too late to introduce a new version of OpenAPI.

Additional context
I'm also thinking of merging resources and collections in one endpoint (called collsources or resections :-), or just resources).

I am ready to discuss this proposal, which was prepared by AI, and refine it in greater detail.

[daliboris]

For the /api/db/collection, the method POST is used to create a new collection, while for the /api/db/resource, the PUT method is used to create a new resource or replace an existing one. That seems inconsistent.

Furthermore, the PUT method assumes that the specified identifier (path) exists or will be created and will not change. However, the description of the result states that it is the “Canonical decoded DB path of the stored resource (may differ from the request path if the name was normalized).”

My recommendation is using POST method consistently for creating (resources, queries, collections). Returned path can be used as an identifier for PUT method.

[daliboris]

Should we use entirely new QUERY method?

It's proposed in RFC 10008 in June 2026 and is

• Safe
• Idempotent
• Cacheable

[daliboris]

GET method of the /api/db endpoint:

• count parameter is of type integer, but the description states default value: all, which is a string

[daliboris]

POST method of the /api/db/move endpoint (similar /api/db/copy)

• from the description: parent [parameter], if supplied, must already exist as a collection
• status 409 is returned if Destination already exists (refuse-to-overwrite)

POST of the /api/db/collection

• status 409 = Parent collection does not exist (pass recursive=true to create intermediate collections)

Adding the recursive parameter to a POST request to /api/db/move would allow a resource to be moved to a collection even if it does not yet exist.

[daliboris]

/api/modules endpoint

• response schema, ref property defines as string with description: Origin: 'package', 'global', or 'mapped'

"ref": {
  "type": "string",
  "description": "Origin: 'package', 'global', or 'mapped'"
}

• can be defined as an enum

"ref": {
  "type": "string",
  "enum" : [
     "package",
     "global",
     "mapped"
   ]
  "description": "Origin: 'package', 'global', or 'mapped'"
}

[daliboris]

created property in the responses haw two meanings:

• datetime when the resource was created, in GET api/db, GET api/db/properties
• name of the created item (collection, user, group), in POST /api/db/collection, POST /api/users, POST /api/groups

Is it possible for the created property to have a different name in the second case, for example created-item, or path, user, and group?

[daliboris]

The POST method of /api/users can contain an array with Additional groups to assign.

What happens if a group does not exist: will it be created, or will the user creation be rejected?

If one or more groups are created, should the response include the names of the created groups (or group) in addition to the name of the created user?