HTTP API: Schema endpoint #736
Conversation
|
Deploy Preview Available Via |
| paths: | ||
| /_db/{database-name}/_api/schema: | ||
| get: | ||
| operationId: getAllSchemas |
There was a problem hiding this comment.
as per our naming convention:
| operationId: getAllSchemas | |
| operationId: listSchemas |
| @@ -0,0 +1,1116 @@ | |||
| --- | |||
|
|
|||
| @@ -0,0 +1,1116 @@ | |||
| --- | |||
|
|
|||
| title: HTTP interface for database structures (schema, graph, view) | |||
There was a problem hiding this comment.
This is ambiguous IMO. I generally wonder how to call it, because just Schemas can be confused with document schemas. Should we refer to it as "sampled schemas", "inferred schemas", or something similar?
| HTTP interface for database structures gives you information about | ||
| graphs, views, collections and schemas in the database. |
There was a problem hiding this comment.
This is too generic and makes it sound like it would give you all kinds of metadata for graphs etc. which isn't the case. It's about the common document structure, isn't it?
| # GET /_api/schema | ||
| # GET /_api/schema/graph/{graph-name} | ||
| # GET /_api/schema/view/{view-name} | ||
| # GET /_api/schema/collection/{collection-name} |
There was a problem hiding this comment.
What are these comments for?
| --- | ||
|
|
||
| ## Supported API Paths | ||
| 1. [**GET /_api/schema**](#get-apischema) – Returns all graphs, views, and collections in the database. | ||
| 2. [**GET /_api/schema/graph/<graph-name>**](#get-apischemagraphgraph-name) – Returns the specified graph and its connected collections. | ||
| 3. [**GET /_api/schema/view/<view-name>**](#get-apischemaviewview-name) – Returns the specified view and its linked collections. | ||
| 4. [**GET /_api/schema/collection/<collection-name>**](#get-apischemacollectioncollection-name) – Returns the specified collection and its schema. | ||
|
|
||
| --- |
There was a problem hiding this comment.
This seems unnecessary and we don't provide such overviews anywhere in the existing content. Descriptions of endpoints should go into the OpenAPI code block.
|
|
||
| --- | ||
|
|
||
| <h2 id="get-apischema">GET /_api/schema</h2> |
There was a problem hiding this comment.
Please take a look at other existing pages. We use descriptive headlines instead of the endpoint, and raw HTML should be avoided.
| description: | | ||
| The number of example documents/edges to return per collection. | ||
| Must be a non-negative integer and not be larger than `sampleNum`. | ||
| If `0`, no examples will be returned. Defaults to `1`. |
There was a problem hiding this comment.
Present tense. Using default: 1 is sufficient
| If `0`, no examples will be returned. Defaults to `1`. | |
| If set to `0`, no examples are returned. |
| '200 OK': | ||
| description: | | ||
| The schema overview was successfully returned. | ||
| '400 Bad Request': | ||
| description: | | ||
| Invalid query parameters (e.g., negative or non-numeric values). | ||
| '404 Not Found': | ||
| description: | | ||
| Collection, view or graph not found on the database. | ||
| '405 Method Not Allowed': | ||
| description: | | ||
| When request method is not GET. This endpoint only supports GET. | ||
| '500 Internal Server Error': | ||
| description: | | ||
| Internal server error. |
There was a problem hiding this comment.
It must only be the status code, e.g. '200':. We don't tend to describe all of the possible status codes, especially because there can be many different ones if it's not handled by the specific rest handler but somewhere else (e.g. there is always a possibility that a request returns 503 during startup, but describing this for each endpoint would be extremely cumbersome). Which of the listed ones are specific to the schema feature?
| - Schema | ||
| ``` | ||
|
|
||
| **Examples** |
There was a problem hiding this comment.
Please see existing content how to use ```curl blocks for generated examples. You basically need to write an arangosh script that generates some minimal data and then use special functions for outputting request to be displayed in the docs.
Description
Add a docs-hugo for new schema endpoints:
/schema,/schema/graph/{graph-name},/schema/view/{view-name},/schema/collection/{collection-name}.Includes query parameters (
sampleNum,exampleNum) and examples of http requests and responses.Upstream PRs