Skip to content

Commit 4f8e612

Browse files
kolchfa-awscwillum
kolchfa-aws
and
cwillum
authored
Add API and experimetal templates (opensearch-project#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>
1 parent d0242fd commit 4f8e612

File tree

4 files changed

+141
-9
lines changed

4 files changed

+141
-9
lines changed

‎STYLE_API_TEMPLATE.md ‎API_STYLE_GUIDE.md

+12-9
Original file line numberDiff line numberDiff line change
@@ -1,12 +1,14 @@
1-
# API reference page template
1+
# API Style Guide
22

3-
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.
3+
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.
44

55
Depending on the intended purpose of the API, *some sections will be required while others may not be applicable*.
66

7+
Use the [API_TEMPLATE](templates/API_TEMPLATE.md) to create an API documentation page.
8+
79
### A note on terminology ###
810

9-
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:
11+
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:
1012
* *Path parameter* – "path parameter" and "URL parameter" are sometimes used synonymously. To avoid confusion, we use "path parameter" in this documentation.
1113
* *Query parameter* – This parameter name is often used synonymously with "request parameter." We use "query parameter" to be consistent.
1214

@@ -24,7 +26,7 @@ Provide a REST API call example in `json` format. Optionally, also include the `
2426

2527
## Basic elements for documentation
2628

27-
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.
29+
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.
2830

2931
Depending on where the documentation appears within a section or subsection, heading levels may be adjusted to fit with other content.
3032

@@ -70,10 +72,11 @@ GET /_nodes/<node_id>/stats/<metric>/<index_metric>
7072

7173
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.
7274

75+
In the following example, the resource is `scroll` and its path parameter is `<scroll_id>`:
76+
7377
```json
7478
GET _search/scroll/<scroll_id>
7579
```
76-
In the example above, the resource is `scroll` and its path parameter is `<scroll_id>`.
7780

7881
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:
7982
*Parameter* – Parameter name in plain font.
@@ -87,12 +90,12 @@ Parameter | Data type | Description
8790

8891
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.
8992

93+
In the following example, the endpoint is `aliases` and its query parameter is `v` (provides verbose output):
94+
9095
```json
9196
GET _cat/aliases?v
9297
```
9398

94-
In the example above, the endpoint is `aliases` and its query parameter is `v` (provides verbose output).
95-
9699
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.
97100

98101
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
114117

115118
#### Example request
116119

117-
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.
120+
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.
118121

119122
The following request gets all the settings in your index:
120123

@@ -138,7 +141,7 @@ POST _reindex
138141

139142
#### Example response
140143

141-
Include a JSON example response to show what the API returns. See the examples below.
144+
Include a JSON example response to show what the API returns. See the following examples.
142145

143146
The `GET /sample-index1/_settings` request returns the following response fields:
144147

‎FORMATTING_GUIDE.md

+26
Original file line numberDiff line numberDiff line change
@@ -9,6 +9,7 @@ This guide provides an overview of the formatted elements commonly used in the O
99
* [Adding pages or sections](#adding-pages-or-sections)
1010
* [Buttons](#buttons)
1111
* [Callouts](#callouts)
12+
* [Collapsible blocks](#collapsible-blocks)
1213
* [Dashes](#dashes)
1314
* [Horizontal rule](#horizontal-rule)
1415
* [Images](#images)
@@ -91,6 +92,31 @@ For a callout with multiple paragraphs or lists, use `>`:
9192
9293
```
9394

95+
## Collapsible blocks
96+
97+
To insert a collapsible block, use the `<details>` element as follows:
98+
99+
````html
100+
<details open markdown="block">
101+
<summary>
102+
Response
103+
</summary>
104+
{: .text-delta}
105+
106+
```json
107+
{
108+
"_nodes" : {
109+
"total" : 1,
110+
"successful" : 1,
111+
"failed" : 0
112+
}
113+
}
114+
```
115+
</details>
116+
````
117+
118+
Collapsible blocks are useful for long responses and for the Table of Contents at the beginning of a page.
119+
94120
## Dashes
95121

96122
Use one dash for hyphens, two for en dashes, and three for em dashes:

‎templates/API_TEMPLATE.md

+89
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,89 @@
1+
---
2+
layout: default
3+
title: Example API
4+
parent:
5+
nav_order:
6+
---
7+
8+
# Example API
9+
Introduced 1.0
10+
{: .label .label-purple }
11+
12+
The Example API ... (descriptive sentence about what this API does).
13+
14+
## Path and HTTP methods
15+
16+
```json
17+
POST /_example/endpoint/
18+
POST /_example/endpoint/<path_parameter>
19+
```
20+
21+
## Path parameters
22+
23+
The following table lists the available path parameters. All path parameters are optional.
24+
25+
| Parameter | Data type | Description |
26+
| :--- | :--- | :--- |
27+
| `path_parameter` | Type | Example path parameter description. Default is ... |
28+
29+
## Query parameters
30+
31+
The following table lists the available query parameters. All query parameters are optional.
32+
33+
| Parameter | Data type | Description |
34+
| :--- | :--- | :--- |
35+
| `query_parameter` | String | Example query parameter description. Default is ... |
36+
37+
## Request fields
38+
39+
The following table lists the available request fields.
40+
41+
| Field | Data type | Description |
42+
| :--- | :--- | :--- |
43+
| `example_object` | Object | Example object description. |
44+
| `example_object.required_request_field` | Type | Required request field description. Required. |
45+
| `example_object.optional_request_field` | Type | Optional request field description. Optional. Default is ... |
46+
47+
#### Example request
48+
49+
```json
50+
POST /_example/endpoint/
51+
{
52+
"example_object": {
53+
"required_request_field": "example value",
54+
"optional_request_field": "example value"
55+
}
56+
}
57+
```
58+
{% include copy-curl.html %}
59+
60+
#### Example response
61+
62+
<details open markdown="block">
63+
<summary>
64+
Response
65+
</summary>
66+
{: .text-delta}
67+
68+
```json
69+
{
70+
"_nodes" : {
71+
"total" : 1,
72+
"successful" : 1,
73+
"failed" : 0
74+
}
75+
}
76+
```
77+
</details>
78+
79+
## Response fields
80+
81+
The following table lists all response fields.
82+
83+
| Field | Data type | Description |
84+
| :--- | :--- | :--- |
85+
| `response_field` | Type | Required field description. |
86+
87+
## Required permissions
88+
89+
If you use the Security plugin, make sure you have the appropriate permissions: `cluster:example/permission/name`.

‎templates/EXPERIMENTAL_TEMPLATE.md

+14
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
---
2+
layout: default
3+
title: Experimental feature name
4+
nav_order:
5+
parent:
6+
---
7+
8+
# Experimental feature name
9+
10+
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).
11+
{: .warning}
12+
13+
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/).
14+
{: .warning}

0 commit comments

Comments
 (0)