iSharkFly-Docs
/
opensearch-docs-cn
mirror of https://github.com/iSharkFly-Docs/opensearch-docs-cn
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Adds the path and http methods section to API style guide (#1435) 

* Adds the path and http methods section to API style guide

Signed-off-by: Fanit Kolchina <kolchfa@amazon.com>

* Removed the link that is not accessible from the outside

Signed-off-by: Fanit Kolchina <kolchfa@amazon.com>

* Reworded based on feedback

Signed-off-by: Fanit Kolchina <kolchfa@amazon.com>

* Update STYLE_API_TEMPLATE.md

Co-authored-by: Nate Bower <nbower@amazon.com>

Signed-off-by: Fanit Kolchina <kolchfa@amazon.com>
Co-authored-by: Nate Bower <nbower@amazon.com>
This commit is contained in:
kolchfa-aws 2022-10-13 12:57:13 -04:00 committed by GitHub
parent 5f8d2fae09
commit d664344b04
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
1 changed files with 21 additions and 7 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

28
STYLE_API_TEMPLATE.md
View File

@ -20,7 +20,7 @@ When you provide an exact example with a value, you can use the code element in
*Example usage*:
The response provides a value for `time_field`, such as “timestamp.”
See also [Examples](https://alpha-docs-aws.amazon.com/awsstyleguide/latest/styleguide/examples.html) in the AWS Style Guide.
Provide a REST API call example in `json` format. Optionally, also include the `curl` command if the call can only be executed in a command line.
## Basic elements for documentation
@ -29,12 +29,13 @@ The following sections describe the basic API documentation structure. Each sect
Depending on where the documentation appears within a section or subsection, heading levels may be adjusted to fit with other content.
1. Name of API (heading level 2)
2. Path parameters (heading level 3)
3. Query parameters (heading level 3)
4. Request fields (heading level 3)
5. Sample request (heading level 4)
6. Sample response (heading level 4)
7. Response fields (heading level 3)
1. (Optional) Path and HTTP methods (heading level 3)
1. Path parameters (heading level 3)
1. Query parameters (heading level 3)
1. Request fields (heading level 3)
1. Sample request (heading level 4)
1. Sample response (heading level 4)
1. Response fields (heading level 3)
## API name
@ -52,6 +53,19 @@ If applicable, provide any caveats to its usage with a note or tip, as in the fo
"If you use the Security plugin, make sure you have the appropriate permissions."
(To set this point in note-style format, follow the text on the next line with {: .note})
### Path and HTTP methods
For relatively complex API calls that include path parameters, it's sometimes a good idea to provide an example so that users can visualize how the request is properly formed. This section is optional and includes examples that illustrate how the endpoint and path parameters fit together in the request. The following is an example of this section for the nodes stats API:
```json
GET /_nodes/stats
GET /_nodes/<node_id>/stats
GET /_nodes/stats/<metric>
GET /_nodes/<node_id>/stats/<metric>
GET /_nodes/stats/<metric>/<index_metric>
GET /_nodes/<node_id>/stats/<metric>/<index_metric>
```
### Path parameters
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.