Add API and experimetal templates (#4258)
* Add API and experimetal templates Signed-off-by: Fanit Kolchina <kolchfa@amazon.com> * Add forum option Signed-off-by: Fanit Kolchina <kolchfa@amazon.com> * Doc review comments Signed-off-by: Fanit Kolchina <kolchfa@amazon.com> * Update API_STYLE_GUIDE.md Co-authored-by: Chris Moore <107723039+cwillum@users.noreply.github.com> Signed-off-by: kolchfa-aws <105444904+kolchfa-aws@users.noreply.github.com> --------- Signed-off-by: Fanit Kolchina <kolchfa@amazon.com> Signed-off-by: kolchfa-aws <105444904+kolchfa-aws@users.noreply.github.com> Co-authored-by: Chris Moore <107723039+cwillum@users.noreply.github.com>
This commit is contained in:
kolchfa-aws
GitHub
parent
d0242fd6fa
commit
4f8e612465
|
|
@ -1,12 +1,14 @@
|
|||
# API reference page template
|
||||
# API Style Guide
|
||||
|
||||
This template provides the basic structure for creating OpenSearch API documentation. It includes the most important elements that should appear in the documentation and helpful suggestions to help support them.
|
||||
This guide provides the basic structure for creating OpenSearch API documentation. It includes the various elements that we feel are most important to creating complete and useful API documentation, as well as description and examples where appropriate.
|
||||
|
||||
Depending on the intended purpose of the API, *some sections will be required while others may not be applicable*.
|
||||
|
||||
Use the [API_TEMPLATE](templates/API_TEMPLATE.md) to create an API documentation page.
|
||||
|
||||
### A note on terminology ###
|
||||
|
||||
Terminology for API parameters varies in the software industry, where two or even three names may be used to label the same type of parameter. For the sake of consistency, we use the following nomenclature for parameters in our API documentation:
|
||||
Terminology for API parameters varies in the software industry, where two or even three names may be used to label the same type of parameter. For consistency, we use the following nomenclature for parameters in our API documentation:
|
||||
* *Path parameter* – "path parameter" and "URL parameter" are sometimes used synonymously. To avoid confusion, we use "path parameter" in this documentation.
|
||||
* *Query parameter* – This parameter name is often used synonymously with "request parameter." We use "query parameter" to be consistent.
|
||||
|
||||
|
|
@ -24,7 +26,7 @@ Provide a REST API call example in `json` format. Optionally, also include the `
|
|||
|
||||
## Basic elements for documentation
|
||||
|
||||
The following sections describe the basic API documentation structure. Each section is discussed under its respective heading below. You can include only those elements appropriate to the API.
|
||||
The following sections describe the basic API documentation structure. Each section is discussed under its respective heading. Include only those elements appropriate to the API.
|
||||
|
||||
Depending on where the documentation appears within a section or subsection, heading levels may be adjusted to fit with other content.
|
||||
|
||||
|
|
@ -70,10 +72,11 @@ GET /_nodes/<node_id>/stats/<metric>/<index_metric>
|
|||
|
||||
While the API endpoint states a point of entry to a resource, the path parameter acts on the resource that precedes it. Path parameters come after the resource name in the URL.
|
||||
|
||||
In the following example, the resource is `scroll` and its path parameter is `<scroll_id>`:
|
||||
|
||||
```json
|
||||
GET _search/scroll/<scroll_id>
|
||||
```
|
||||
In the example above, the resource is `scroll` and its path parameter is `<scroll_id>`.
|
||||
|
||||
Introduce what the path parameters can do at a high level. Provide a table with parameter names and descriptions. Include a table with the following columns:
|
||||
*Parameter* – Parameter name in plain font.
|
||||
|
|
@ -87,12 +90,12 @@ Parameter | Data type | Description
|
|||
|
||||
In terms of placement, query parameters are always appended to the end of the URL and located to the right of the operator "?". Query parameters serve the purpose of modifying information to be retrieved from the resource.
|
||||
|
||||
In the following example, the endpoint is `aliases` and its query parameter is `v` (provides verbose output):
|
||||
|
||||
```json
|
||||
GET _cat/aliases?v
|
||||
```
|
||||
|
||||
In the example above, the endpoint is `aliases` and its query parameter is `v` (provides verbose output).
|
||||
|
||||
Include a paragraph that describes how to use the query parameters with an example in code font. Include the query parameter operator "?" to delineate query parameters from path parameters.
|
||||
|
||||
For GET and DELETE APIs: Introduce what you can do with the optional parameters. Include a table with the same columns as the path parameter table.
|
||||
|
|
@ -114,7 +117,7 @@ Field | Data type | Description
|
|||
|
||||
#### Example request
|
||||
|
||||
Provide a sentence that describes what is shown in the example, followed by a cut-and-paste-ready API request in JSON format. Make sure that you test the request yourself in the Dashboards Dev Tools console to make sure it works. See the examples below.
|
||||
Provide a sentence that describes what is shown in the example, followed by a cut-and-paste-ready API request in JSON format. Make sure that you test the request yourself in the Dashboards Dev Tools console to make sure it works. See the following examples.
|
||||
|
||||
The following request gets all the settings in your index:
|
||||
|
||||
|
|
@ -138,7 +141,7 @@ POST _reindex
|
|||
|
||||
#### Example response
|
||||
|
||||
Include a JSON example response to show what the API returns. See the examples below.
|
||||
Include a JSON example response to show what the API returns. See the following examples.
|
||||
|
||||
The `GET /sample-index1/_settings` request returns the following response fields:
|
||||
|
||||
|
|
@ -9,6 +9,7 @@ This guide provides an overview of the formatted elements commonly used in the O
|
|||
* [Adding pages or sections](#adding-pages-or-sections)
|
||||
* [Buttons](#buttons)
|
||||
* [Callouts](#callouts)
|
||||
* [Collapsible blocks](#collapsible-blocks)
|
||||
* [Dashes](#dashes)
|
||||
* [Horizontal rule](#horizontal-rule)
|
||||
* [Images](#images)
|
||||
|
|
@ -91,6 +92,31 @@ For a callout with multiple paragraphs or lists, use `>`:
|
|||
|
||||
```
|
||||
|
||||
## Collapsible blocks
|
||||
|
||||
To insert a collapsible block, use the `<details>` element as follows:
|
||||
|
||||
````html
|
||||
<details open markdown="block">
|
||||
<summary>
|
||||
Response
|
||||
</summary>
|
||||
{: .text-delta}
|
||||
|
||||
```json
|
||||
{
|
||||
"_nodes" : {
|
||||
"total" : 1,
|
||||
"successful" : 1,
|
||||
"failed" : 0
|
||||
}
|
||||
}
|
||||
```
|
||||
</details>
|
||||
````
|
||||
|
||||
Collapsible blocks are useful for long responses and for the Table of Contents at the beginning of a page.
|
||||
|
||||
## Dashes
|
||||
|
||||
Use one dash for hyphens, two for en dashes, and three for em dashes:
|
||||
|
|
|
|||
|
|
@ -0,0 +1,89 @@
|
|||
---
|
||||
layout: default
|
||||
title: Example API
|
||||
parent:
|
||||
nav_order:
|
||||
---
|
||||
|
||||
# Example API
|
||||
Introduced 1.0
|
||||
{: .label .label-purple }
|
||||
|
||||
The Example API ... (descriptive sentence about what this API does).
|
||||
|
||||
## Path and HTTP methods
|
||||
|
||||
```json
|
||||
POST /_example/endpoint/
|
||||
POST /_example/endpoint/<path_parameter>
|
||||
```
|
||||
|
||||
## Path parameters
|
||||
|
||||
The following table lists the available path parameters. All path parameters are optional.
|
||||
|
||||
| Parameter | Data type | Description |
|
||||
| :--- | :--- | :--- |
|
||||
| `path_parameter` | Type | Example path parameter description. Default is ... |
|
||||
|
||||
## Query parameters
|
||||
|
||||
The following table lists the available query parameters. All query parameters are optional.
|
||||
|
||||
| Parameter | Data type | Description |
|
||||
| :--- | :--- | :--- |
|
||||
| `query_parameter` | String | Example query parameter description. Default is ... |
|
||||
|
||||
## Request fields
|
||||
|
||||
The following table lists the available request fields.
|
||||
|
||||
| Field | Data type | Description |
|
||||
| :--- | :--- | :--- |
|
||||
| `example_object` | Object | Example object description. |
|
||||
| `example_object.required_request_field` | Type | Required request field description. Required. |
|
||||
| `example_object.optional_request_field` | Type | Optional request field description. Optional. Default is ... |
|
||||
|
||||
#### Example request
|
||||
|
||||
```json
|
||||
POST /_example/endpoint/
|
||||
{
|
||||
"example_object": {
|
||||
"required_request_field": "example value",
|
||||
"optional_request_field": "example value"
|
||||
}
|
||||
}
|
||||
```
|
||||
{% include copy-curl.html %}
|
||||
|
||||
#### Example response
|
||||
|
||||
<details open markdown="block">
|
||||
<summary>
|
||||
Response
|
||||
</summary>
|
||||
{: .text-delta}
|
||||
|
||||
```json
|
||||
{
|
||||
"_nodes" : {
|
||||
"total" : 1,
|
||||
"successful" : 1,
|
||||
"failed" : 0
|
||||
}
|
||||
}
|
||||
```
|
||||
</details>
|
||||
|
||||
## Response fields
|
||||
|
||||
The following table lists all response fields.
|
||||
|
||||
| Field | Data type | Description |
|
||||
| :--- | :--- | :--- |
|
||||
| `response_field` | Type | Required field description. |
|
||||
|
||||
## Required permissions
|
||||
|
||||
If you use the Security plugin, make sure you have the appropriate permissions: `cluster:example/permission/name`.
|
||||
|
|
@ -0,0 +1,14 @@
|
|||
---
|
||||
layout: default
|
||||
title: Experimental feature name
|
||||
nav_order:
|
||||
parent:
|
||||
---
|
||||
|
||||
# Experimental feature name
|
||||
|
||||
This is an experimental feature and is not recommended for use in a production environment. For updates on the progress of the feature or if you want to leave feedback, see the associated [GitHub issue](https://example.issue.link).
|
||||
{: .warning}
|
||||
|
||||
This is an experimental feature and is not recommended for use in a production environment. For updates on the progress the feature or if you want to leave feedback, join the discussion in the [OpenSearch forum](https://forum.opensearch.org/).
|
||||
{: .warning}
|
||||
Loading…
Reference in New Issue