1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
|
# OpenSearch REST API JSON specification
This repository contains a collection of JSON files which describe the [OpenSearch](https://github.com/opensearch-project/OpenSearch) HTTP API.
Their purpose is to formalize and standardize the API, to facilitate development of libraries and integrations.
Example for the ["Create Index"](https://www.elastic.co/guide/en/elasticsearch/reference/master/indices-create-index.html) API:
```json
{
"indices.create": {
"documentation":{
"url":"https://www.elastic.co/guide/en/elasticsearch/reference/master/indices-create-index.html"
},
"stability": "stable",
"url":{
"paths":[
{
"path":"/{index}",
"method":"PUT",
"parts":{
"index":{
"type":"string",
"description":"The name of the index"
}
}
}
]
},
"params": {
"timeout": {
"type" : "time",
"description" : "Explicit operation timeout"
}
},
"body": {
"description" : "The configuration for the index (`settings` and `mappings`)"
}
}
}
```
The specification contains:
* The _name_ of the API (`indices.create`), which usually corresponds to the client calls
* Link to the documentation at the <http://elastic.co> website.
**IMPORANT:** This should be a _live_ link. Several downstream ES clients use
this link to generate their documentation. Using a broken link or linking to
yet-to-be-created doc pages can break the [Elastic docs
build](https://github.com/elastic/docs#building-documentation).
* `stability` indicating the state of the API, has to be declared explicitly or YAML tests will fail
* `experimental` highly likely to break in the near future (minor/path), no bwc guarantees.
Possibly removed in the future.
* `beta` less likely to break or be removed but still reserve the right to do so
* `stable` No backwards breaking changes in a minor
* Request URL: HTTP method, path and parts
* Request parameters
* Request body specification
**NOTE**
If an API is stable but it response should be treated as an arbitrary map of key values please notate this as followed
```json
{
"api.name": {
"stability" : "stable",
"response": {
"treat_json_as_key_value" : true
}
}
}
```
## Backwards compatibility
The specification follows the same backward compatibility guarantees as OpenSearch.
- Within a Major, additions only.
- If an item has been documented wrong it should be deprecated instead as removing these might break downstream clients.
- Major version change, may deprecate pieces or simply remove them given enough deprecation time.
## Deprecations
The specification schema allows to codify API deprecations, either for an entire API, or for specific parts of the API, such as paths or parameters.
#### Entire API:
```json
{
"api" : {
"deprecated" : {
"version" : "7.0.0",
"description" : "Reason API is being deprecated"
},
}
}
```
#### Specific paths and their parts:
```json
{
"api": {
"url": {
"paths": [
{
"path":"/{index}/{type}/{id}/_create",
"method":"PUT",
"parts":{
"id":{
"type":"string",
"description":"Document ID"
},
"index":{
"type":"string",
"description":"The name of the index"
},
"type":{
"type":"string",
"description":"The type of the document",
"deprecated":true
}
},
"deprecated":{
"version":"7.0.0",
"description":"Specifying types in urls has been deprecated"
}
}
]
}
}
}
```
#### Parameters
```json
{
"api": {
"url": {
"params": {
"stored_fields": {
"type": "list",
"description" : "",
"deprecated" : {
"version" : "7.0.0",
"description" : "Reason parameter is being deprecated"
}
}
}
}
}
}
```
## License
This software is licensed under the Apache License, version 2 ("ALv2").
|
