Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Update rest API specs #54252

Merged
merged 5 commits into from
Apr 2, 2020
Merged

Update rest API specs #54252

Show file tree
Hide file tree
Changes from 2 commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
4d086f2
Update rest API specs
russcam Mar 26, 2020
fccaf58
Add JSON schema for rest api specs
russcam Mar 27, 2020
474b63a
Address PR comments
russcam Mar 29, 2020
ea86e14
Reinstate deprecated:bool API parts
russcam Apr 1, 2020
86916e2
Merge branch 'master' into rest-spec-validation
elasticmachine Apr 1, 2020
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
242 changes: 242 additions & 0 deletions rest-api-spec/schema.json
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,242 @@
{
russcam marked this conversation as resolved.
Show resolved Hide resolved
russcam marked this conversation as resolved.
Show resolved Hide resolved
"$schema": "http://json-schema.org/draft-07/schema#",
russcam marked this conversation as resolved.
Show resolved Hide resolved
"$id": "https://github.com/elastic/elasticsearch/tree/master/rest-api-spec",
"$ref": "#/definitions/Api",
"definitions": {
"Api": {
"type": "object",
"propertyNames": {
"pattern": "^[a-z]+?(_[a-z]+)*(\\.[a-z]+?(_[a-z]+)*)?$"
},
"minProperties": 1,
"maxProperties": 1,
"patternProperties": {
"^[a-z]+?(_[a-z]+)*(\\.[a-z]+?(_[a-z]+)*)?$": {
"$ref": "#/definitions/Components"
}
},
"additionalProperties": false,
"title": "API name",
"description": "An object with a single property name of the API and value of the API components"
},
"Components": {
"type": "object",
"additionalProperties": false,
"properties": {
"deprecated": {
"$ref": "#/definitions/Deprecated"
},
"documentation": {
"$ref": "#/definitions/Documentation"
},
"stability": {
"type": "string",
"enum": ["stable", "beta", "experimental", "private"]
},
"url": {
"$ref": "#/definitions/Url"
},
"params": {
"$ref": "#/definitions/Params"
},
"body": {
"$ref": "#/definitions/Body"
}
},
"required": [
"documentation",
"stability",
"url"
],
"title": "API components",
"description": "The components that make up the API"
},
"Url": {
"type": "object",
"additionalProperties": false,
"properties": {
"paths": {
"type": "array",
"items": {
"$ref": "#/definitions/Path"
},
"minLength": 1
}
},
"required": [
"paths"
],
"title": "API urls",
"description": "An array of the URL path variants for the API"
},
"Params": {
"type": "object",
"additionalProperties": true,
"propertyNames": {
"pattern": "^_?[a-z]+?(_[a-z]+)*$"
},
"patternProperties": {
"^_?[a-z]+?(_[a-z]+)*$": {
"$ref": "#/definitions/ParamPart"
}
},
"title": "API query string parameters",
"description": "A collection of the query string parameters for the API"
},
"Body": {
"type": "object",
"additionalProperties": false,
"properties": {
"description": {
"type": "string"
},
"required": {
"type": "boolean"
},
"serialize": {
russcam marked this conversation as resolved.
Show resolved Hide resolved
"type": "string",
"enum": ["bulk"]
}
},
"required": [
"description"
],
"title": "API request Body",
"description": "The request body for the API. Does not detail the structure, only whether the API accepts a body and its format"
},
"Deprecated": {
"type": "object",
"additionalProperties": false,
"properties": {
"version": {
russcam marked this conversation as resolved.
Show resolved Hide resolved
"type": "string",
"pattern": "^(\\d+)(\\.(\\d+))?(\\.(\\d+))?(\\-([0-9A-Za-z]+))?$",
russcam marked this conversation as resolved.
Show resolved Hide resolved
"title": "The version from which deprecation applies"
},
"description": {
"type": "string",
"title": "A description for the deprecation, which may include alternatives to use"
}
},
"required": [
"description",
"version"
],
"title": "Deprecation",
"description": "Indicates if part of the API is deprecated, in what version and why"
},
"Documentation": {
"type": "object",
"additionalProperties": false,
"properties": {
"url": {
"type": "string",
"format": "uri"
},
"description": {
"type": "string"
}
},
"required": [
"url",
"description"
],
"title": "Documentation",
"description": "API documentation including a link to the public reference and a short descritpion"
},
"Parts": {
"type": "object",
"additionalProperties": true,
"propertyNames": {
"pattern": "^_?[a-z]+?(_[a-z]+)*$"
},
"patternProperties": {
"^_?[a-z]+?(_[a-z]+)*$": {
"$ref": "#/definitions/ParamPart"
}
},
"title": "API url parts",
"description": "Variable parts that make up an API url path"
},
"ParamPart": {
"type": "object",
"additionalProperties": false,
"properties": {
"type": {
"type": "string",
"pattern": "^list|date|time|string|enum|int|double|long|boolean|number$",
"title": "The type of the parameter."
},
"options": {
"type": "array",
"items": {
"type": "string",
"pattern": "^[a-zA-Z_]+$"
},
"title": "Valid options when type is an enum"
},
"default": {
"type": ["string", "number", "boolean"],
"title": "Default value"
},
"deprecated": {
"$ref": "#/definitions/Deprecated"
},
"description": {
"type": "string",
"title": "A description for the parameter"
},
"required": {
"type": "boolean",
"title": "Whether the parameter is required"
}
},
"required": [
"description",
"type"
],
"allOf": [
{
"if": {
"properties": { "type": { "const": "enum" } }
},
"then": {
"required": ["options"]
}
}
],
"title": "API parameter or part",
"description": "The properties of an API parameter or part"
},
"Path": {
"type": "object",
"additionalProperties": false,
"properties": {
"path": {
"type": "string",
"pattern": "^\\/([a-z0-9\\/_{}])*$"
},
"methods": {
"type": "array",
"items": {
"type": "string",
"enum": ["DELETE", "GET", "HEAD", "POST", "PUT"],
"minLength": 1
}
},
"parts": {
"$ref": "#/definitions/Parts"
},
"deprecated": {
"$ref": "#/definitions/Deprecated"
}
},
"required": [
"methods",
"path"
],
"title": "API path",
"description": "A path variant for the API including the HTTP methods it supports and parts"
}
}
}
2 changes: 1 addition & 1 deletion rest-api-spec/src/main/resources/rest-api-spec/api/cat.aliases.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -63,7 +63,7 @@
"none",
"all"
],
"default": ["all"],
"default": "all",
"description":"Whether to expand wildcard expression to concrete indices that are open, closed or both."
}
}
Expand Down
14 changes: 7 additions & 7 deletions rest-api-spec/src/main/resources/rest-api-spec/api/cat.health.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -37,13 +37,13 @@
"type":"enum",
"description":"The unit in which to display time values",
"options":[
"d (Days)",
"h (Hours)",
"m (Minutes)",
"s (Seconds)",
"ms (Milliseconds)",
"micros (Microseconds)",
"nanos (Nanoseconds)"
"d",
"h",
"m",
"s",
"ms",
"micros",
"nanos"
]
},
"ts":{
Expand Down
1 change: 0 additions & 1 deletion rest-api-spec/src/main/resources/rest-api-spec/api/cat.indices.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -68,7 +68,6 @@
"yellow",
"red"
],
"default":null,
"description":"A health status (\"green\", \"yellow\", or \"red\" to filter only indices matching the specified health status"
},
"help":{
Expand Down
3 changes: 1 addition & 2 deletions rest-api-spec/src/main/resources/rest-api-spec/api/clear_scroll.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -21,8 +21,7 @@
"parts":{
"scroll_id":{
"type":"list",
"description":"A comma-separated list of scroll IDs to clear",
"deprecated":true
russcam marked this conversation as resolved.
Show resolved Hide resolved
"description":"A comma-separated list of scroll IDs to clear"
}
},
"deprecated":{
Expand Down
1 change: 0 additions & 1 deletion rest-api-spec/src/main/resources/rest-api-spec/api/cluster.health.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -97,7 +97,6 @@
"yellow",
"red"
],
"default":null,
"description":"Wait until cluster is in a specific state"
}
}
Expand Down
3 changes: 1 addition & 2 deletions rest-api-spec/src/main/resources/rest-api-spec/api/create.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -41,8 +41,7 @@
},
"type":{
"type":"string",
"description":"The type of the document",
"deprecated":true
"description":"The type of the document"
}
},
"deprecated":{
Expand Down
3 changes: 1 addition & 2 deletions rest-api-spec/src/main/resources/rest-api-spec/api/delete.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -39,8 +39,7 @@
},
"type":{
"type":"string",
"description":"The type of the document",
"deprecated":true
"description":"The type of the document"
}
},
"deprecated":{
Expand Down
3 changes: 1 addition & 2 deletions rest-api-spec/src/main/resources/rest-api-spec/api/delete_by_query.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -56,7 +56,6 @@
"description":"Whether to ignore if a wildcard indices expression resolves into no concrete indices. (This includes `_all` string or when no indices have been specified)"
},
"conflicts":{
"note":"This is not copied from search",
"type":"enum",
"options":[
"abort",
Expand Down Expand Up @@ -160,7 +159,7 @@
},
"scroll_size":{
"type":"number",
"defaut_value":100,
"default":100,
"description":"Size on the scroll request powering the delete by query"
},
"wait_for_completion":{
Expand Down
3 changes: 1 addition & 2 deletions rest-api-spec/src/main/resources/rest-api-spec/api/exists_source.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -39,8 +39,7 @@
},
"type":{
"type":"string",
"description":"The type of the document; deprecated and optional starting with 7.0",
"deprecated":true
"description":"The type of the document; deprecated and optional starting with 7.0"
}
},
"deprecated":{
Expand Down
1 change: 1 addition & 0 deletions rest-api-spec/src/main/resources/rest-api-spec/api/get_script_context.json
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,7 @@
{
"get_script_context":{
"documentation":{
"url": "https://www.elastic.co/guide/en/elasticsearch/painless/master/painless-contexts.html",
"description":"Returns all script contexts."
},
"stability":"experimental",
Expand Down
1 change: 1 addition & 0 deletions rest-api-spec/src/main/resources/rest-api-spec/api/get_script_languages.json
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,7 @@
{
"get_script_languages":{
"documentation":{
"url": "https://www.elastic.co/guide/en/elasticsearch/reference/master/modules-scripting.html",
"description":"Returns available script types, languages and contexts"
},
"stability":"experimental",
Expand Down
2 changes: 1 addition & 1 deletion rest-api-spec/src/main/resources/rest-api-spec/api/indices.get_alias.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -73,7 +73,7 @@
"none",
"all"
],
"default": ["all"],
"default": "all",
"description":"Whether to expand wildcard expression to concrete indices that are open, closed or both."
},
"local":{
Expand Down
5 changes: 1 addition & 4 deletions rest-api-spec/src/main/resources/rest-api-spec/api/indices.get_settings.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -77,10 +77,7 @@
"none",
"all"
],
"default":[
"open",
"closed"
],
"default": "all",
"description":"Whether to expand wildcard expression to concrete indices that are open, closed or both."
},
"flat_settings":{
Expand Down
3 changes: 1 addition & 2 deletions rest-api-spec/src/main/resources/rest-api-spec/api/indices.validate_query.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -40,8 +40,7 @@
},
"type":{
"type":"list",
"description":"A comma-separated list of document types to restrict the operation; leave empty to perform the operation on all types",
"deprecated":true
"description":"A comma-separated list of document types to restrict the operation; leave empty to perform the operation on all types"
}
},
"deprecated":{
Expand Down
Loading