Some more OpenAPI suggestions for the Query API.

As others have reported, there is some confusion around the endpoints' purpose (when viewed in the developer portal). This confusion could be helped by choosing more appropriate operation summaryvalues (and not conflating with the HTTP method). For example "Query" is not a good operation summary - "Get a query" or "Get query definition" would be better choices.

Here are some (opinionated) OpenAPI summary suggestions (in bold) you might consider for the current set of endpoints in the Query API (also listing a suggested operation description to illustrate the difference):

• List query types Lists the query types.

• List query categories Lists the query categories.

• List queries Returns a list of queries.

• Get a query Returns information about the specified query.

• Start a query job Creates a background job to execute the specified query.

• Start ad-hoc query job Creates a background job to execute the specified ad-hoc query.

• Get query job status Returns information about the specified background query execution job.

• List available fields tree root Lists the available fields tree for the specified query type root.

• List available fields tree node Lists the available fields tree for the specified query node.