Documentation for Saved Objects API #19513

epixa · 2018-05-29T18:19:31Z

This is an initial pass on the saved object API, which will be the first API formally documented under the Kibana REST API. There is plenty of additional stuff we could add, like more examples, more structured ways to indicate error messages and status codes, etc.

My intention here is simply to get things started, since not documented these APIs at all is becoming a burden.

To test this PR, simply run node scripts/docs.js --open, which should open a new tab in your browser.

Supersedes #16726
Closes #14871

Signed-off-by: Tyler Smalley <tyler.smalley@elastic.co>

elasticmachine · 2018-05-30T02:59:29Z

💚 Build Succeeded

continuous-integration/kibana-ci/pull-request

jbudz · 2018-05-30T14:00:42Z

docs/api/saved-objects.asciidoc

+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


how do we reconcile this with the experimental flag?

I don't think we do. We don't have a stable way to programmatically manage saved objects.

LeeDr · 2018-05-30T14:04:41Z

docs/api/saved-objects/bulk_get.asciidoc

+
+`type` (required)::
+  (string) Valid options, include: `visualization`, `dashboard`, `search`, `config`, and `timelion-sheet`
+


Should index-pattern be in that list of valid options? I'm hoping it would.

Yeah, index-pattern is valid. I'll add it everywhere we have a list like this.

LeeDr · 2018-05-30T14:06:22Z

docs/api/saved-objects/create.asciidoc

+
+`type` (required)::
+  (string) Valid options, include: `visualization`, `dashboard`, `search`, `config`, and `timelion-sheet`
+


No index-pattern ?

docs/api/saved-objects/delete.asciidoc

+==== Examples
+
+The following example deletes an index pattern object with an ID of `my-pattern`
+


legrego

I know the Platform team is researching API specs, such as OpenAPI/Swagger. If we plan on exploring that route, I found https://github.com/Swagger2Markup/swagger2markup, which converts a Swagger spec to AsciiDoc. If nothing else, it might be a decent starting point for us. I'm not suggesting we tackle it for this PR, but it's something to think about in the future before we hand-write too many of these.

legrego · 2018-05-30T13:51:57Z

docs/api/saved-objects/bulk_get.asciidoc

+`type` (required)::
+  (string) Valid options, include: `visualization`, `dashboard`, `search`, `config`, and `timelion-sheet`
+
+`id` (required)::


Do you think it's worthwhile to point out that this isn't the ES _id? This tripped me up at first because I kept forgetting that the document id is derived from this id

legrego · 2018-05-30T13:59:25Z

docs/api/saved-objects/find.asciidoc

+The following example attempts to find index patterns with titles that start
+with `my`:
+
+[source,js]


What do you think about adding an example showing how to specify multiple search_fields/fields? I know there are a few different patterns for doing this, so having it documented could be helpful

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.

legrego · 2018-05-30T14:02:39Z

docs/api/saved-objects/update.asciidoc

+==== Path Parameters
+
+`type` (required)::
+  (string) Valid options, include: `visualization`, `dashboard`, `search`, `config`, and `timelion-sheet`


The type and id path parameters are used and described in a few of these API endpoints. What do you think about extracting these descriptions into reusable AsciiDoc attributes? It could prevent these from getting out of sync in the future.

LeeDr · 2018-05-30T14:11:46Z

docs/api/saved-objects/find.asciidoc

+`per_page` (optional)::
+  (number) The number of objects to return per page
+`page` (optional)::
+  (number) The page of objects to return


Is there a way to set per_page to get all objects? Do I just set it to some huge number, or zero means all?

If I find with per_page = 10, do I start with page = 0? Or page = 1?

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.

Is there a way to set per_page to get all objects? Do I just set it to some huge number, or zero means all?

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.

If I find with per_page = 10, do I start with page = 0? Or page = 1?

It starts with page 1. I've never encountered an API that zero indexes pages, have you?

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.

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.

I've pushed a note that clarifies this.

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":

LeeDr · 2018-05-30T14:12:07Z

docs/api/saved-objects/get.asciidoc

+
+`type` (required)::
+  (string) Valid options, include: `visualization`, `dashboard`, `search`, `config`, and `timelion-sheet`
+


index-pattern

jbudz · 2018-05-30T14:16:05Z

LGTM for getting a first pass in. I think in the future we could add info on how to auth/why there's a kbn-xsrf header. And then in the copy as curl section Note: Unnecessary use of -X or --request, GET is already inferred., but that belongs in the docs repo.

LeeDr · 2018-05-30T14:23:20Z

It looks like if I needed to export everything and re-create it in a new Kibana instance I could do the find with no parameters (to find everything), and then use that with create? Is it as simple as that?
What would I be missing?

jbudz · 2018-05-30T14:24:56Z

Another future thought is to publish our clients, or move them somewhere plugins can use. And document those APIs too.

epixa · 2018-05-30T14:55:04Z

I've pushed updates to address all the feedback, along with the notes below. Can I get another pass?

I know the Platform team is researching API specs, such as OpenAPI/Swagger. If we plan on exploring that route, I found https://github.com/Swagger2Markup/swagger2markup, which converts a Swagger spec to AsciiDoc.

This is awesome! We'll definitely take a look at that in the near future.

I think in the future we could add info on how to auth/why there's a kbn-xsrf header.

Yes, I think we need an API conventions doc. I've created an issue for that: #19553

And then in the copy as curl section Note: Unnecessary use of -X or --request, GET is already inferred., but that belongs in the docs repo.

What OS/version of curl do you see this on? I don't get any such warnings on macos. In any case, that isn't from this PR itself, so we won't block on it.

It looks like if I needed to export everything and re-create it in a new Kibana instance I could do the find with no parameters (to find everything), and then use that with create? Is it as simple as that?
What would I be missing?

Since find uses traditional pagination rather than a scan/scroll interface, it's not a reliable way to export data to use in this way. The note I added about pagination says exactly that. The consequence for using find in this way is the potential for duplicate or missing objects at page boundaries if any changes occur while the export is happening.

We have an issue for a generic import/export API, and we'll want to document it as well: #16831

Another future thought is to publish our clients, or move them somewhere plugins can use. And document those APIs too.

For sure!

elasticmachine · 2018-05-30T15:59:34Z

💚 Build Succeeded

continuous-integration/kibana-ci/pull-request

legrego · 2018-05-30T16:08:53Z

LGTM!

* Adds documentation for Saved Objects API Signed-off-by: Tyler Smalley <tyler.smalley@elastic.co> * [DOCS] Moved Rest APIs in navigation * docs: revise rest api intro * docs: revise create object api details * docs: revise saved object api intro * docs: revise delete saved object api details * docs: remove newline character from api response * docs: get saved object api details * docs: update saved object api details * docs: fix title attribute in saved object api examples * docs: bulk-get saved object api details * docs: find saved object api details * docs: add index-pattern to valid types in api * docs: clarify sending multiple values in api * docs: note that savedObjects.find is not safe for export

epixa · 2018-05-30T16:29:14Z

6.x/6.4 f8521c0
6.3 e9ed3a5

JasonLarson44 · 2018-07-24T22:46:51Z

Can I use the create object endpoint to create a dashboard and populate it with visuals that already exist? I am able to create an empty dashboard by posting a json payload with an attributes object that contains a title and description. However, I can't seem to figure out how to pass in the panelsJSON array to fill in the dashboard. Is this possible?

Tyler Smalley and others added 2 commits May 29, 2018 14:07

Adds documentation for Saved Objects API

8440413

Signed-off-by: Tyler Smalley <tyler.smalley@elastic.co>

[DOCS] Moved Rest APIs in navigation

17711c2

epixa added Team:Docs Team:Core Core services & architecture: plugins, logging, config, saved objects, http, ES client, i18n, etc labels May 29, 2018

epixa self-assigned this May 29, 2018

epixa mentioned this pull request May 29, 2018

[WIP] Adds documentation for Saved Objects API #16726

Closed

epixa added 10 commits May 29, 2018 14:52

docs: revise rest api intro

5acc822

docs: revise create object api details

5c7f157

docs: revise saved object api intro

430c24e

docs: revise delete saved object api details

6ef490f

docs: remove newline character from api response

9c7a929

docs: get saved object api details

18aec08

docs: update saved object api details

3da99c1

docs: fix title attribute in saved object api examples

03a5056

docs: bulk-get saved object api details

f2a78a8

docs: find saved object api details

ec322d5

elastic deleted a comment from elasticmachine May 30, 2018

epixa added review v7.0.0 v6.3.0 v6.4.0 labels May 30, 2018

legrego self-requested a review May 30, 2018 13:53

jbudz reviewed May 30, 2018

View reviewed changes

LeeDr reviewed May 30, 2018

View reviewed changes

docs/api/saved-objects/delete.asciidoc

==== Examples

The following example deletes an index pattern object with an ID of `my-pattern`

This comment was marked as resolved.

Sign in to view

legrego reviewed May 30, 2018

View reviewed changes

docs: add index-pattern to valid types in api

450d64f

LeeDr reviewed May 30, 2018

View reviewed changes

epixa added 2 commits May 30, 2018 10:35

docs: clarify sending multiple values in api

a52a32c

docs: note that savedObjects.find is not safe for export

568350d

jbudz approved these changes May 30, 2018

View reviewed changes

epixa merged commit 5abc2dc into elastic:master May 30, 2018

epixa deleted the kibana-api branch May 30, 2018 16:27

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Documentation for Saved Objects API #19513

Documentation for Saved Objects API #19513

epixa commented May 29, 2018 •

edited

Loading

elasticmachine commented May 30, 2018

jbudz May 30, 2018

epixa May 30, 2018

LeeDr May 30, 2018 •

edited

Loading

epixa May 30, 2018

LeeDr May 30, 2018

This comment was marked as resolved.

legrego left a comment

legrego May 30, 2018

legrego May 30, 2018

epixa May 30, 2018

legrego May 30, 2018

LeeDr May 30, 2018

epixa May 30, 2018

epixa May 30, 2018

LeeDr May 30, 2018

LeeDr May 30, 2018

jbudz commented May 30, 2018

LeeDr commented May 30, 2018

jbudz commented May 30, 2018

epixa commented May 30, 2018

elasticmachine commented May 30, 2018

legrego commented May 30, 2018

epixa commented May 30, 2018

JasonLarson44 commented Jul 24, 2018


		`type` (required)::
		(string) Valid options, include: `visualization`, `dashboard`, `search`, `config`, and `timelion-sheet`

		==== Examples

		The following example deletes an index pattern object with an ID of `my-pattern`

Documentation for Saved Objects API #19513

Documentation for Saved Objects API #19513

Conversation

epixa commented May 29, 2018 • edited Loading

elasticmachine commented May 30, 2018

💚 Build Succeeded

Choose a reason for hiding this comment

Choose a reason for hiding this comment

LeeDr May 30, 2018 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

This comment was marked as resolved.

legrego left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

jbudz commented May 30, 2018

LeeDr commented May 30, 2018

jbudz commented May 30, 2018

epixa commented May 30, 2018

elasticmachine commented May 30, 2018

💚 Build Succeeded

legrego commented May 30, 2018

epixa commented May 30, 2018

JasonLarson44 commented Jul 24, 2018

epixa commented May 29, 2018 •

edited

Loading

LeeDr May 30, 2018 •

edited

Loading