-
Notifications
You must be signed in to change notification settings - Fork 8.2k
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.
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
Documentation for Saved Objects API #19513
Changes from all commits
8440413
17711c2
5acc822
5c7f157
430c24e
6ef490f
9c7a929
18aec08
3da99c1
03a5056
f2a78a8
ec322d5
450d64f
a52a32c
568350d
File filter
Filter by extension
Conversations
Jump to
Diff view
Diff view
There are no files selected for viewing
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,33 @@ | ||
[[api]] | ||
= REST API | ||
|
||
[partintro] | ||
-- | ||
Some of the features of Kibana are provided via a REST API, which is ideal for | ||
people that want to create an integration with Kibana or that want to automate | ||
certain aspects of configuring and deploying Kibana. | ||
|
||
Each API in this documentation should be clearly marked as either `stable`, | ||
`beta`, or `experimental`. If an API is not marked, it should be considered | ||
`experimental`. | ||
|
||
What do these labels mean? | ||
|
||
* *Stable* APIs should be safe to use extensively in production. Any breaking | ||
changes to these APIs should only occur in major versions and will be | ||
clearly documented in the breaking changes documentation for that release. | ||
* *Beta* APIs are on track to become stable, permanent features of Kibana. | ||
Caution should be exercised in their use since it is possible we'd have to make | ||
a breaking change to these APIs in a minor version, but we'll avoid this | ||
wherever possible. | ||
* *Experimental* APIs are just that - an experiment. An experimental API might | ||
have breaking changes in any version of Kibana, or it might even be removed | ||
entirely. | ||
|
||
[float] | ||
== APIs | ||
|
||
* <<saved-objects-api>> | ||
-- | ||
|
||
include::api/saved-objects.asciidoc[] |
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,24 @@ | ||
[[saved-objects-api]] | ||
== Saved Objects API | ||
|
||
The saved objects API allows people to manage Kibana saved objects, including | ||
but not limited to dashboards, visualizations, and index patterns. | ||
|
||
Traditionally, developers would perform this level of integration by writing | ||
documents directly to the `.kibana` index. *Do not do this!* Writing directly | ||
to the `.kibana` index is not safe and it _will_ result in corrupted data that | ||
permanently breaks Kibana in a future version. | ||
|
||
* <<saved-objects-api-get>> | ||
* <<saved-objects-api-bulk-get>> | ||
* <<saved-objects-api-find>> | ||
* <<saved-objects-api-create>> | ||
* <<saved-objects-api-update>> | ||
* <<saved-objects-api-delete>> | ||
|
||
include::saved-objects/get.asciidoc[] | ||
include::saved-objects/bulk_get.asciidoc[] | ||
include::saved-objects/find.asciidoc[] | ||
include::saved-objects/create.asciidoc[] | ||
include::saved-objects/update.asciidoc[] | ||
include::saved-objects/delete.asciidoc[] |
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,81 @@ | ||
[[saved-objects-api-bulk-get]] | ||
=== Bulk Get Objects | ||
|
||
experimental[This functionality is *experimental* and may be changed or removed completely in a future release.] | ||
|
||
The bulk-get saved object API enables you to retrieve multiple Kibana saved | ||
objects by id. | ||
|
||
==== Request | ||
|
||
`POST /api/saved_objects/_bulk_get` | ||
|
||
==== Request Body | ||
|
||
The request body must be a JSON array containing objects, each of which | ||
contains the following properties: | ||
|
||
`type` (required):: | ||
(string) Valid options, include: `visualization`, `dashboard`, `search`, `index-pattern`, `config`, and `timelion-sheet` | ||
|
||
`id` (required):: | ||
(string) ID of object to retrieve | ||
|
||
==== Response body | ||
|
||
The response body will have a top level `saved_objects` property that contains | ||
an array of objects, which represent the response for each of the requested | ||
objects. The order of the objects in the response is identical to the order of | ||
the objects in the request. | ||
|
||
For any saved object that could not be found, an error object will exist in its | ||
place. | ||
|
||
==== Examples | ||
|
||
The following example attempts to retrieve an index pattern with id | ||
`my-pattern` and a dashboard with id `my-dashboard`, but only the index pattern | ||
exists. | ||
|
||
[source,js] | ||
-------------------------------------------------- | ||
POST api/saved_objects/_bulk_get | ||
[ | ||
{ | ||
"type": "index-pattern", | ||
"id": "my-pattern" | ||
}, | ||
{ | ||
"type": "dashboard", | ||
"id": "my-dashboard" | ||
} | ||
] | ||
-------------------------------------------------- | ||
// KIBANA | ||
|
||
A successful call returns a response code of `200` and a response body | ||
containing a JSON structure similar to the following example: | ||
|
||
[source,js] | ||
-------------------------------------------------- | ||
{ | ||
"saved_objects": [ | ||
{ | ||
"id": "my-pattern", | ||
"type": "index-pattern", | ||
"version": 1, | ||
"attributes": { | ||
"title": "my-pattern-*" | ||
} | ||
}, | ||
{ | ||
"id": "my-dashboard", | ||
"type": "dashboard", | ||
"error": { | ||
"statusCode": 404, | ||
"message": "Not found" | ||
} | ||
} | ||
] | ||
} | ||
-------------------------------------------------- |
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,73 @@ | ||
[[saved-objects-api-create]] | ||
=== Create Object | ||
|
||
experimental[This functionality is *experimental* and may be changed or removed completely in a future release.] | ||
|
||
The create saved object API enables you to persist a Kibana saved object. | ||
|
||
==== Request | ||
|
||
`POST /api/saved_objects/<type>` + | ||
|
||
`POST /api/saved_objects/<type>/<id>` | ||
|
||
==== Path Parameters | ||
|
||
`type` (required):: | ||
(string) Valid options, include: `visualization`, `dashboard`, `search`, `index-pattern`, `config`, and `timelion-sheet` | ||
|
||
`id` (optional):: | ||
(string) Enables specifying an ID to use, as opposed to one being randomly generated | ||
|
||
|
||
==== Query Parameters | ||
|
||
`overwrite` (optional):: | ||
(boolean) If true, will overwrite the document with the same ID. | ||
|
||
|
||
==== Request Body | ||
|
||
`attributes` (required):: | ||
(object) The data to persist | ||
|
||
|
||
==== Examples | ||
|
||
The following example creates an index pattern object with a pattern of | ||
`my-pattern-*`. | ||
|
||
[source,js] | ||
-------------------------------------------------- | ||
POST api/saved_objects/index-pattern/my-pattern | ||
{ | ||
"attributes": { | ||
"title": "my-pattern-*" | ||
} | ||
} | ||
-------------------------------------------------- | ||
// KIBANA | ||
|
||
A successful call returns a response code of `200` and a response body | ||
containing a JSON structure similar to the following example: | ||
|
||
[source,js] | ||
-------------------------------------------------- | ||
{ | ||
"id": "my-pattern", <1> | ||
"type": "index-pattern", | ||
"version": 1, | ||
"attributes": { | ||
"title": "my-pattern-*" | ||
} | ||
} | ||
-------------------------------------------------- | ||
|
||
<1> If `my-pattern` was not specified in the path, a unique ID would have been | ||
generated. | ||
|
||
==== Known issues | ||
|
||
1. *Attributes are not validated at creation time*. This means you can pass | ||
arbitrary and ill-formed data into this API that can break Kibana. Make sure | ||
any data you send to this API is properly formed. |
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,32 @@ | ||
[[saved-objects-api-delete]] | ||
=== Delete Object | ||
|
||
experimental[This functionality is *experimental* and may be changed or removed completely in a future release.] | ||
|
||
The delete saved object API permanently removes a Kibana saved object. Once a | ||
saved object has been deleted, _it cannot be recovered_. | ||
|
||
==== Request | ||
|
||
`DELETE /api/saved_objects/<type>/<id>` | ||
|
||
==== Path Parameters | ||
|
||
`type` (required):: | ||
(string) Valid options, include: `visualization`, `dashboard`, `search`, `index-pattern`, `config`, and `timelion-sheet` | ||
|
||
`id` (required):: | ||
(string) Object ID being removed | ||
|
||
|
||
==== Examples | ||
|
||
The following example deletes an index pattern object with an ID of `my-pattern` | ||
|
||
This comment was marked as resolved.
Sorry, something went wrong. |
||
[source,js] | ||
-------------------------------------------------- | ||
DELETE api/saved_objects/index-pattern/my-pattern | ||
-------------------------------------------------- | ||
// KIBANA | ||
|
||
A successful call returns a response code of `200`. |
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,84 @@ | ||
[[saved-objects-api-find]] | ||
=== Find Objects | ||
|
||
experimental[This functionality is *experimental* and may be changed or removed completely in a future release.] | ||
|
||
The find saved object API enables you to retrieve a paginated set of Kibana | ||
saved objects by various conditions. | ||
|
||
==== Request | ||
|
||
`GET /api/saved_objects/_find` | ||
|
||
==== Query Parameters | ||
|
||
`per_page` (optional):: | ||
(number) The number of objects to return per page | ||
`page` (optional):: | ||
(number) The page of objects to return | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Is there a way to set If I find with Am I guaranteed that when I get page 2 the list won't have changed? I'm trying to recall how the scroll api worked. There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more.
No, there is no way to do this. You'd need to use a scan/scroll like streaming interface for that, which we don't have at the moment.
It starts with page 1. I've never encountered an API that zero indexes pages, have you?
No, this is not a scan/scroll-like interface. It's just classic pagination, which can change as you navigate. I can add a note about that. There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. I've pushed a note that clarifies this. There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Looks like there's a default per_page of 20? I just did a find with no parameters and got this; {"page":1,"per_page":20,"total":418,"saved_objects": |
||
`type` (optional):: | ||
(array|string) The saved object type(s) that the response should be limited to | ||
`search` (optional):: | ||
(string) A {ref}/query-dsl-simple-query-string-query.html[simple_query_string] Elasticsearch query to filter the objects in the response | ||
`search_fields` (optional):: | ||
(array|string) The fields to perform the `simple_query_string` parsed query against | ||
`fields` (optional):: | ||
(array|string) The fields to return in the response | ||
`sort_field` (optional):: | ||
(string) The field on which the response will be sorted | ||
|
||
[NOTE] | ||
============================================== | ||
|
||
As objects change in Kibana, the results on each page of this response can | ||
change. This makes the `find` API suitable for traditional paginated results | ||
but not a reliable way to safely export large amounts of data. | ||
|
||
============================================== | ||
|
||
|
||
==== Examples | ||
|
||
The following example attempts to find index patterns with titles that start | ||
with `my`: | ||
|
||
[source,js] | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. What do you think about adding an example showing how to specify multiple There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. I've pushed a change that clarifies this behavior, but I think it really belongs in some top level "API conventions" documentation since its not unique to the saved objects API. But we can address that separately. |
||
-------------------------------------------------- | ||
GET api/saved_objects/_find?type=index-pattern&search_fields=title&search=my* | ||
-------------------------------------------------- | ||
// KIBANA | ||
|
||
A successful call returns a response code of `200` and a response body | ||
containing a JSON structure similar to the following example: | ||
|
||
[source,js] | ||
-------------------------------------------------- | ||
{ | ||
"total": 1, | ||
"data": [ | ||
{ | ||
"id": "my-pattern", | ||
"type": "index-pattern", | ||
"version": 1, | ||
"attributes": { | ||
"title": "my-pattern-*" | ||
} | ||
} | ||
] | ||
} | ||
-------------------------------------------------- | ||
|
||
[NOTE] | ||
.Multiple values for a parameter | ||
============================================== | ||
|
||
For parameters that can accept multiple values (e.g. `fields`), repeat the | ||
query parameter for each value: | ||
|
||
[source,js] | ||
-------------------------------------------------- | ||
GET api/saved_objects/_find?fields=id&fields=title | ||
-------------------------------------------------- | ||
// KIBANA | ||
|
||
============================================== |
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,46 @@ | ||
[[saved-objects-api-get]] | ||
=== Get Object | ||
|
||
experimental[This functionality is *experimental* and may be changed or removed completely in a future release.] | ||
|
||
The get saved object API enables you to retrieve a single Kibana saved object | ||
by id. | ||
|
||
==== Request | ||
|
||
`GET /api/saved_objects/<type>/<id>` | ||
|
||
==== Path Parameters | ||
|
||
`type` (required):: | ||
(string) Valid options, include: `visualization`, `dashboard`, `search`, `index-pattern`, `config`, and `timelion-sheet` | ||
|
||
`id` (required):: | ||
(string) ID of object to retrieve | ||
|
||
|
||
==== Examples | ||
|
||
The following example retrieves the index pattern object with an id of | ||
`my-pattern`. | ||
|
||
[source,js] | ||
-------------------------------------------------- | ||
GET api/saved_objects/index-pattern/my-pattern | ||
-------------------------------------------------- | ||
// KIBANA | ||
|
||
A successful call returns a response code of `200` and a response body | ||
containing a JSON structure similar to the following example: | ||
|
||
[source,js] | ||
-------------------------------------------------- | ||
{ | ||
"id": "my-pattern", | ||
"type": "index-pattern", | ||
"version": 1, | ||
"attributes": { | ||
"title": "my-pattern-*" | ||
} | ||
} | ||
-------------------------------------------------- |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
how do we reconcile this with the experimental flag?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I don't think we do. We don't have a stable way to programmatically manage saved objects.