diff --git a/docs/api/spaces-management.asciidoc b/docs/api/spaces-management.asciidoc index 91b7ae349b9a80..7390a3815cd653 100644 --- a/docs/api/spaces-management.asciidoc +++ b/docs/api/spaces-management.asciidoc @@ -1,38 +1,4 @@ -[role="xpack"] [[spaces-api]] == {kib} spaces APIs -Manage your {kib} spaces. - -The following {kib} spaces APIs are available: - -* <> to create a {kib} space - -* <> to update an existing {kib} space - -* <> to retrieve a specified {kib} space - -* <> to retrieve all {kib} spaces - -* <> to delete a {kib} space - -* <> to copy saved objects between spaces - -* <> to overwrite saved objects returned as errors from the copy saved objects to space API - -* <> to disable legacy URL aliases if an error is encountered - -* <> to update one or more saved objects to add and/or remove them from specified spaces - -* <> to collect references and spaces context for saved objects - -include::spaces-management/post.asciidoc[] -include::spaces-management/put.asciidoc[] -include::spaces-management/get.asciidoc[] -include::spaces-management/get_all.asciidoc[] -include::spaces-management/delete.asciidoc[] -include::spaces-management/copy_saved_objects.asciidoc[] -include::spaces-management/resolve_copy_saved_objects_conflicts.asciidoc[] -include::spaces-management/disable_legacy_url_aliases.asciidoc[] -include::spaces-management/update_objects_spaces.asciidoc[] -include::spaces-management/get_shareable_references.asciidoc[] +For the latest details, refer to {api-kibana}/group/endpoint-spaces[spaces APIs]. diff --git a/docs/api/spaces-management/copy_saved_objects.asciidoc b/docs/api/spaces-management/copy_saved_objects.asciidoc deleted file mode 100644 index 32f7480a39b871..00000000000000 --- a/docs/api/spaces-management/copy_saved_objects.asciidoc +++ /dev/null @@ -1,491 +0,0 @@ -[role="xpack"] -[[spaces-api-copy-saved-objects]] -=== Copy saved objects to space API -++++ -Copy saved objects to space -++++ - -experimental[] Copy saved objects between spaces. - -It also allows you to automatically copy related objects, so when you copy a `dashboard`, this can automatically copy over the -associated visualizations, {data-sources}, and saved searches, as required. - -You can request to overwrite any objects that already exist in the target space if they share an ID, or you can use the -<> to do this on a per-object basis. - -[[spaces-api-copy-saved-objects-request]] -==== {api-request-title} - -`POST :/api/spaces/_copy_saved_objects` - -`POST :/s//api/spaces/_copy_saved_objects` - -[[spaces-api-copy-saved-objects-path-params]] -==== {api-path-parms-title} - -`space_id`:: - (Optional, string) The ID of the space that contains the saved objects you want to copy. When `space_id` is unspecified in the URL, the - default space is used. - -[role="child_attributes"] -[[spaces-api-copy-saved-objects-request-body]] -==== {api-request-body-title} - -`spaces`:: - (Required, string array) The IDs of the spaces where you want to copy the specified objects. - -`objects`:: - (Required, object array) The saved objects to copy. -+ -.Properties of `objects` -[%collapsible%open] -===== - `type`::: - (Required, string) The saved object type. - - `id`::: - (Required, string) The saved object ID. -===== - -`includeReferences`:: - (Optional, boolean) When set to `true`, all saved objects related to the specified saved objects will also be copied into the target - spaces. The default value is `false`. - -`createNewCopies`:: - (Optional, boolean) Creates new copies of saved objects, regenerates each object ID, and resets the origin. When used, potential conflict - errors are avoided. The default value is `true`. -+ -NOTE: This option cannot be used with the `overwrite` and `compatibilityMode` options. - -`overwrite`:: - (Optional, boolean) When set to `true`, all conflicts are automatically overridden. When a saved object with a matching `type` and `id` - exists in the target space, that version is replaced with the version from the source space. The default value is `false`. -+ -NOTE: This option cannot be used with the `createNewCopies` option. - -`compatibilityMode`:: - (Optional, boolean) Applies various adjustments to the saved objects that are being copied to maintain compatibility between different {kib} - versions. Use this option only if you encounter issues with copied saved objects. -+ -NOTE: This option cannot be used with the `createNewCopies` option. - -[[spaces-api-copy-saved-objects-response-codes]] -==== Response codes - -`200`:: - Indicates a successful call. - -`404`:: - Indicates that the request failed because one or more of the objects specified could not be found. A list of the unresolved objects are included in the 404 response attributes. - -[role="child_attributes"] -[[spaces-api-copy-saved-objects-response-body]] -==== {api-response-body-title} - -``:: - (object) An object that describes the result of the copy operation for the space. Includes the dynamic keys in the response. -+ -.Properties of `` -[%collapsible%open] -===== - `success`::: - (boolean) The copy operation was successful. When set to `false`, some objects may have been copied. For additional information, refer - to the `errors` and `successResults` properties. - - `successCount`::: - (number) The number of objects that successfully copied. - - `errors`::: - (Optional, array) The errors that occurred during the copy operation. When errors are reported, the `success` flag is set to `false`. -+ -NOTE: One object may result in multiple errors, which requires separate steps to resolve. For instance, a `missing_references` error and a -`conflict` error. -+ -.Properties of `errors` -[%collapsible%open] -====== - `id`:::: - (string) The saved object ID that failed to copy. - `type`:::: - (string) The type of saved object that failed to copy. - `error`:::: - (object) The error that caused the copy operation to fail. -+ -.Properties of `error` -[%collapsible%open] -======= - `type`:::: - (string) The type of error. For example, `conflict`, `ambiguous_conflict`, `missing_references`, `unsupported_type`, or `unknown`. - Errors marked as `conflict` or `ambiguous_conflict` may be resolved by using the <>. - `destinationId`:::: - (Optional, string) The destination ID that was used during the copy attempt. This is only present on `conflict` error types. - `destinations`:::: - (Optional, array) A list of possible object destinations with `id`, `title`, and `updatedAt` fields to describe each one. This is - only present on `ambiguous_conflict` error types. -======= -====== - - `successResults`::: - (Optional, array) Indicates successfully copied objects, with any applicable metadata. -+ -NOTE: Objects are created when all resolvable errors are addressed, including conflict and missing references errors. For more information, -refer to the <>. - -===== -[[spaces-api-copy-saved-objects-example]] -==== {api-examples-title} - -[[spaces-api-copy-saved-objects-example-1]] -===== Successful copy (with `createNewCopies` enabled) - -Copy a dashboard with the `my-dashboard` ID, including all references from the `default` space to the `marketing` space. In this example, -the dashboard has a reference to a visualization, and that has a reference to a {data-source}: - -[source,sh] ----- -$ curl -X POST api/spaces/_copy_saved_objects -{ - "objects": [{ - "type": "dashboard", - "id": "my-dashboard" - }], - "spaces": ["marketing"], - "includeReferences": true -} ----- -// KIBANA - -The API returns the following: - -[source,sh] ----- -{ - "marketing": { - "success": true, - "successCount": 3, - "successResults": [ - { - "id": "my-dashboard", - "type": "dashboard", - "destinationId": "1e127098-5b80-417f-b0f1-c60c8395358f", - "meta": { - "icon": "dashboardApp", - "title": "Look at my dashboard" - } - }, - { - "id": "my-vis", - "type": "visualization", - "destinationId": "a610ed80-1c73-4507-9e13-d3af736c8e04", - "meta": { - "icon": "visualizeApp", - "title": "Look at my visualization" - } - }, - { - "id": "my-index-pattern", - "type": "index-pattern", - "destinationId": "bc3c9c70-bf6f-4bec-b4ce-f4189aa9e26b", - "meta": { - "icon": "indexPatternApp", - "title": "my-pattern-*" - } - } - ] - } -} ----- - -The result indicates a successful copy, and all three objects are created. Since these objects were created as new copies, each entry in the -`successResults` array includes a `destinationId` attribute. - -[[spaces-api-copy-saved-objects-example-2]] -===== Successful copy (with `createNewCopies` disabled) - -Copy a dashboard with the `my-dashboard` ID, including all references from the `default` space to the `marketing` space. In this example, -the dashboard has a reference to a visualization, and that has a reference to a {data-source}: - -[source,sh] ----- -$ curl -X POST api/spaces/_copy_saved_objects -{ - "objects": [{ - "type": "dashboard", - "id": "my-dashboard" - }], - "spaces": ["marketing"], - "includeReferences": true, - "createNewCopies": false -} ----- -// KIBANA - -The API returns the following: - -[source,sh] ----- -{ - "marketing": { - "success": true, - "successCount": 3, - "successResults": [ - { - "id": "my-dashboard", - "type": "dashboard", - "meta": { - "icon": "dashboardApp", - "title": "Look at my dashboard" - } - }, - { - "id": "my-vis", - "type": "visualization", - "meta": { - "icon": "visualizeApp", - "title": "Look at my visualization" - } - }, - { - "id": "my-index-pattern", - "type": "index-pattern", - "meta": { - "icon": "indexPatternApp", - "title": "my-pattern-*" - } - } - ] - } -} ----- - -The result indicates a successful copy, and all three objects are created. - -[[spaces-api-copy-saved-objects-example-3]] -===== Failed copy (with conflict errors) - -Copy a dashboard with the `my-dashboard` ID, including all references from the `default` space to the `marketing` and `sales` spaces. In -this example, the dashboard has a reference to a visualization and a *Canvas* workpad, and the visualization has a reference to an index -pattern: - -[source,sh] ----- -$ curl -X POST api/spaces/_copy_saved_objects -{ - "objects": [{ - "type": "dashboard", - "id": "my-dashboard" - }], - "spaces": ["marketing", "sales"], - "includeReferences": true, - "createNewCopies": false -} ----- -// KIBANA - -The API returns the following: - -[source,sh] ----- -{ - "marketing": { - "success": true, - "successCount": 4, - "successResults": [ - { - "id": "my-dashboard", - "type": "dashboard", - "meta": { - "icon": "dashboardApp", - "title": "Look at my dashboard" - } - }, - { - "id": "my-vis", - "type": "visualization", - "meta": { - "icon": "visualizeApp", - "title": "Look at my visualization" - } - }, - { - "id": "my-canvas", - "type": "canvas-workpad", - "meta": { - "icon": "canvasApp", - "title": "Look at my canvas" - } - }, - { - "id": "my-index-pattern", - "type": "index-pattern", - "meta": { - "icon": "indexPatternApp", - "title": "my-pattern-*" - } - } - ] - }, - "sales": { - "success": false, - "successCount": 1, - "errors": [ - { - "id": "my-pattern", - "type": "index-pattern", - "title": "my-pattern-*", - "error": { - "type": "conflict" - }, - "meta": { - "icon": "indexPatternApp", - "title": "my-pattern-*" - } - }, - { - "id": "my-visualization", - "type": "my-vis", - "title": "Look at my visualization", - "error": { - "type": "conflict", - "destinationId": "another-vis" - }, - "meta": { - "icon": "visualizeApp", - "title": "Look at my visualization" - } - }, - { - "id": "my-canvas", - "type": "canvas-workpad", - "title": "Look at my canvas", - "error": { - "type": "ambiguous_conflict", - "destinations": [ - { - "id": "another-canvas", - "title": "Look at another canvas", - "updatedAt": "2020-07-08T16:36:32.377Z" - }, - { - "id": "yet-another-canvas", - "title": "Look at yet another canvas", - "updatedAt": "2020-07-05T12:29:54.849Z" - } - ] - }, - "meta": { - "icon": "canvasApp", - "title": "Look at my canvas" - } - } - ], - "successResults": [ - { - "id": "my-dashboard", - "type": "dashboard", - "meta": { - "icon": "dashboardApp", - "title": "Look at my dashboard" - } - } - ] - } -} ----- - -The result indicates a successful copy for the `marketing` space, and an unsuccessful copy for the `sales` space because the {data-source}, -visualization, and *Canvas* workpad each resulted in a conflict error: - -* A {data-source} with the same ID already exists, which resulted in a conflict error. To resolve the error, overwrite the existing object, -or skip the object. - -* A visualization with a different ID, but the same origin already exists, which resulted in a conflict error. The `destinationId` field -contains the `id` of the other visualization, which caused the conflict. The behavior is added to make sure that new objects that can be -shared between spaces behave in a similar way as legacy non-shareable objects. When a shareable object is copied into a new space, it -retains its origin so that the conflicts are encountered as expected. To resolve, overwrite the specified destination object, or skip the -object. - -* Two *Canvas* workpads with different IDs, but the same origin, already exist, which resulted in a conflict error. The `destinations` array -describes the other workpads which caused the conflict. When a shareable object is copied into a new space, then shared to another space -where an object of the same origin exists, the conflict error occurs. To resolve, pick a destination object to overwrite, or skip the -object. - -Objects are created when the error is resolved using the <>. - -[[spaces-api-copy-saved-objects-example-4]] -===== Failed copy (with missing reference errors) - -Copy a dashboard with the `my-dashboard` ID, including all references from the `default` space to the `marketing` space. In this example, -the dashboard has a reference to a visualization and a *Canvas* workpad, and the visualization has a reference to a {data-source}: - -[source,sh] ----- -$ curl -X POST api/spaces/_copy_saved_objects -{ - "objects": [{ - "type": "dashboard", - "id": "my-dashboard" - }], - "spaces": ["marketing"], - "includeReferences": true, - "createNewCopies": false -} ----- -// KIBANA - -The API returns the following: - -[source,sh] ----- -{ - "marketing": { - "success": false, - "successCount": 2, - "errors": [ - { - "id": "my-vis", - "type": "visualization", - "title": "Look at my visualization", - "error": { - "type": "missing_references", - "references": [ - { - "type": "index-pattern", - "id": "my-pattern-*" - } - ] - }, - "meta": { - "icon": "visualizeApp", - "title": "Look at my visualization" - } - }, - ] - "successResults": [ - { - "id": "my-dashboard", - "type": "dashboard", - "meta": { - "icon": "dashboardApp", - "title": "Look at my dashboard" - } - }, - { - "id": "my-canvas", - "type": "canvas-workpad", - "meta": { - "icon": "canvasApp", - "title": "Look at my canvas" - } - } - ], - } -} ----- - -The result indicates an unsuccessful copy because the visualization resulted in a missing references error. - -Objects are created when the errors are resolved using the <>. diff --git a/docs/api/spaces-management/delete.asciidoc b/docs/api/spaces-management/delete.asciidoc deleted file mode 100644 index b1b453a0e2d3e5..00000000000000 --- a/docs/api/spaces-management/delete.asciidoc +++ /dev/null @@ -1,23 +0,0 @@ -[[spaces-api-delete]] -=== Delete space API -++++ -Delete space -++++ - -experimental[] Delete a {kib} space. - -WARNING: When you delete a space, all saved objects that belong to the space are automatically deleted, which is permanent and cannot be undone. - -[[spaces-api-delete-request]] -==== Request - -`DELETE :/api/spaces/space/` - -[[spaces-api-delete-errors-codes]] -==== Response codes - -`204`:: - Indicates a successful call. - -`404`:: - Indicates that the request failed. diff --git a/docs/api/spaces-management/disable_legacy_url_aliases.asciidoc b/docs/api/spaces-management/disable_legacy_url_aliases.asciidoc deleted file mode 100644 index 3f713d9d0c25e2..00000000000000 --- a/docs/api/spaces-management/disable_legacy_url_aliases.asciidoc +++ /dev/null @@ -1,59 +0,0 @@ -[[spaces-api-disable-legacy-url-aliases]] -=== Disable legacy URL aliases API -++++ -Disable legacy URL aliases -++++ - -experimental[] Disable a <> in {kib}. - -[[spaces-api-disable-legacy-url-aliases-request]] -==== {api-request-title} - -`POST :/api/spaces/_disable_legacy_url_aliases` - -[role="child_attributes"] -[[spaces-api-disable-legacy-url-aliases-request-body]] -==== {api-request-body-title} - -`aliases`:: - (Required, object array) The aliases to disable. -+ -.Properties of `aliases` -[%collapsible%open] -===== - `targetSpace`::: - (Required, string) The space where the alias target object exists. - - `targetType`::: - (Required, string) The type of the alias target object. - - `sourceId`::: - (Required, string) The ID of the alias source object. This is the "legacy" object ID. -===== - -[[spaces-api-disable-legacy-url-aliases-response-codes]] -==== {api-response-codes-title} - -`204`:: - Indicates a successful call. - -[[spaces-api-disable-legacy-url-aliases-example]] -==== {api-examples-title} - -[source,sh] --------------------------------------------------- -$ curl -X POST api/spaces/_disable_legacy_url_aliases -{ - "aliases": [ - { - "targetSpace": "bills-space", - "targetType": "dashboard", - "sourceId": "123" - } - ] -} --------------------------------------------------- -// KIBANA - -This example leaves the alias intact, but the legacy URL for this alias, http://localhost:5601/s/bills-space/app/dashboards#/view/123, will -no longer function. The dashboard still exists, and you can access it with the new URL. \ No newline at end of file diff --git a/docs/api/spaces-management/get.asciidoc b/docs/api/spaces-management/get.asciidoc deleted file mode 100644 index f3e3462b2e0dae..00000000000000 --- a/docs/api/spaces-management/get.asciidoc +++ /dev/null @@ -1,37 +0,0 @@ -[[spaces-api-get]] -=== Get a space API -++++ -Get space -++++ - -experimental[] Retrieve a specified {kib} space. - -[[spaces-api-get-request]] -==== Request - -`GET :/api/spaces/space/marketing` - -[[spaces-api-get-response-codes]] -==== Response code - -`200`:: - Indicates a successful call. - -[[spaces-api-get-example]] -==== Example - -The API returns the following: - -[source,sh] --------------------------------------------------- -{ - "id": "marketing", - "name": "Marketing", - "description" : "This is the Marketing Space", - "color": "#aabbcc", - "initials": "MK", - "disabledFeatures": [], - "imageUrl": "", - "solution": "es" -} --------------------------------------------------- diff --git a/docs/api/spaces-management/get_all.asciidoc b/docs/api/spaces-management/get_all.asciidoc deleted file mode 100644 index 92a65d670ad87d..00000000000000 --- a/docs/api/spaces-management/get_all.asciidoc +++ /dev/null @@ -1,138 +0,0 @@ -[[spaces-api-get-all]] -=== Get all {kib} spaces API -++++ -Get all spaces -++++ - -experimental[] Retrieve all {kib} spaces. - -[[spaces-api-get-all-request]] -==== Request - -`GET :/api/spaces/space` - -[[spaces-api-get-all-query-params]] -==== Query parameters - -`purpose`:: - (Optional, string) Valid options include `any`, `copySavedObjectsIntoSpace`, and `shareSavedObjectsIntoSpace`. This determines what - authorization checks are applied to the API call. If `purpose` is not provided in the URL, the `any` purpose is used. - -`include_authorized_purposes`:: - (Optional, boolean) When enabled, the API will return any spaces that the user is authorized to access in any capacity, and each space - will contain the purpose(s) for which the user is authorized. This can be useful to determine which spaces a user can read but not take a - specific action in. If the Security plugin is not enabled, this will have no effect, as no authorization checks would take place. -+ -NOTE: This option cannot be used in conjunction with `purpose`. - -[[spaces-api-get-all-response-codes]] -==== Response code - -`200`:: - Indicates a successful call. - -[[spaces-api-get-all-example]] -==== Examples - -[[spaces-api-get-all-example-1]] -===== Default options - -Retrieve all spaces without specifying any options: - -[source,sh] --------------------------------------------------- -$ curl -X GET api/spaces/space --------------------------------------------------- - -The API returns the following: - -[source,sh] --------------------------------------------------- -[ - { - "id": "default", - "name": "Default", - "description" : "This is the Default Space", - "disabledFeatures": [], - "imageUrl": "", - "_reserved": true - }, - { - "id": "marketing", - "name": "Marketing", - "description" : "This is the Marketing Space", - "color": "#aabbcc", - "disabledFeatures": ["apm"], - "initials": "MK", - "imageUrl": "data:image/png;base64,iVBORw0KGgoAAAANSU" - }, - { - "id": "sales", - "name": "Sales", - "initials": "MK", - "disabledFeatures": ["discover"], - "imageUrl": "", - "solution": "oblt" - } -] --------------------------------------------------- - -[[spaces-api-get-all-example-2]] -===== Custom options - -The user has read-only access to the Sales space. Retrieve all spaces and specify options: - -[source,sh] --------------------------------------------------- -$ curl -X GET api/spaces/space?purpose=shareSavedObjectsIntoSpace&include_authorized_purposes=true --------------------------------------------------- - -The API returns the following: - -[source,sh] --------------------------------------------------- -[ - { - "id": "default", - "name": "Default", - "description" : "This is the Default Space", - "disabledFeatures": [], - "imageUrl": "", - "_reserved": true, - "authorizedPurposes": { - "any": true, - "copySavedObjectsIntoSpace": true, - "findSavedObjects": true, - "shareSavedObjectsIntoSpace": true, - } - }, - { - "id": "marketing", - "name": "Marketing", - "description" : "This is the Marketing Space", - "color": "#aabbcc", - "disabledFeatures": ["apm"], - "initials": "MK", - "imageUrl": "data:image/png;base64,iVBORw0KGgoAAAANSU", - "authorizedPurposes": { - "any": true, - "copySavedObjectsIntoSpace": true, - "findSavedObjects": true, - "shareSavedObjectsIntoSpace": true, - } - }, - { - "id": "sales", - "name": "Sales", - "initials": "MK", - "disabledFeatures": ["discover"], - "imageUrl": "", - "authorizedPurposes": { - "any": true, - "copySavedObjectsIntoSpace": false, - "findSavedObjects": true, - "shareSavedObjectsIntoSpace": false, - } - } -] --------------------------------------------------- diff --git a/docs/api/spaces-management/get_shareable_references.asciidoc b/docs/api/spaces-management/get_shareable_references.asciidoc deleted file mode 100644 index 8066736c0c15d6..00000000000000 --- a/docs/api/spaces-management/get_shareable_references.asciidoc +++ /dev/null @@ -1,81 +0,0 @@ -[role="xpack"] -[[spaces-api-get-shareable-references]] -=== Get shareable references API -++++ -Get shareable references -++++ - -experimental[] Get shareable references. - -Collects references and spaces context for saved objects. - -[[spaces-api-get-shareable-references-request]] -==== {api-request-title} - -`POST :/api/spaces/_get_shareable_references` - -[[spaces-api-get-shareable-references-request-body]] -==== {api-request-body-title} - -`objects`:: - (Required, object array) The saved objects to collect outbound references for. -+ -.Properties of `objects` -[%collapsible%open] -===== - `type`::: - (Required, string) The saved object type. - - `id`::: - (Required, string) The saved object ID. -===== - -[role="child_attributes"] -[[spaces-api-get-shareable-references-response-body]] -==== {api-response-body-title} - -`objects`:: - (object array) The returned input object or one of its references, with additional context. -+ -.Properties of `objects` -[%collapsible%open] -===== - `type`::: - (string) The saved object type. - - `id`::: - (string) The saved object ID. - - `originId`::: - (string) The origin ID of the referenced object (if it has one). - - `inboundReferences`::: - (object array) References to this object. -+ -NOTE: This does not contain _all inbound references everywhere_, it only contains inbound references to this object within the scope of this operation. -+ -.Properties of `inboundReferences` -[%collapsible%open] -====== - `type`:::: - (string) The type of the object that has the inbound reference. - - `id`:::: - (string) The ID of the object that has the inbound reference. - - `name`:::: - (string) The name of the inbound reference. -====== - - `spaces`::: - (string array) The space(s) that the referenced saved object exists in. - - `spacesWithMatchingAliases`::: - (string array) The space(s) that legacy URL aliases matching this type/id exist in. (if there are any) - - `spacesWithMatchingOrigins`::: - (string array) The space(s) that objects matching this origin exist in (including this one). (if there are any) - - `isMissing`::: - (boolean) Whether or not this object or reference is missing. -===== diff --git a/docs/api/spaces-management/post.asciidoc b/docs/api/spaces-management/post.asciidoc deleted file mode 100644 index 4c5976249f80e8..00000000000000 --- a/docs/api/spaces-management/post.asciidoc +++ /dev/null @@ -1,64 +0,0 @@ -[[spaces-api-post]] -=== Create space API -++++ -Create space -++++ - -experimental[] Create a {kib} space. - -[[spaces-api-post-request]] -==== Request - -`POST :/api/spaces/space` - -[[spaces-api-post-request-body]] -==== Request body - -`id`:: - (Required, string) The space ID that is part of the Kibana URL when inside the space. Space IDs are limited to lowercase alphanumeric, underscore, and hyphen characters (a-z, 0-9, '_', and '-'). You are unable to change the ID with the update operation. - -`name`:: - (Required, string) The display name for the space. - -`description`:: - (Optional, string) The description for the space. - -`disabledFeatures`:: - (Optional, string array) The list of disabled features for the space. To get a list of available feature IDs, use the <>. - -`initials`:: - (Optional, string) The initials shown in the space avatar. By default, the initials are automatically generated from the space name. Initials must be 1 or 2 characters. - -`color`:: - (Optional, string) The hexadecimal color code used in the space avatar. By default, the color is automatically generated from the space name. - -`imageUrl`:: - (Optional, string) The data-URL encoded image to display in the space avatar. If specified, `initials` will not be displayed, and the `color` will be visible as the background color for transparent images. - For best results, your image should be 64x64. Images will not be optimized by this API call, so care should be taken when using custom images. - -`solution`:: - (Optional, string) The solution defined for the space. Can be one of `security`, `oblt`, `es`, `classic` - -[[spaces-api-post-response-codes]] -==== Response codes - -`200`:: - Indicates a successful call. - -[[spaces-api-post-example]] -==== Example - -[source,sh] --------------------------------------------------- -$ curl -X POST api/spaces/space -{ - "id": "marketing", - "name": "Marketing", - "description" : "This is the Marketing Space", - "color": "#aabbcc", - "initials": "MK", - "disabledFeatures": [], - "imageUrl": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAD4AAABACAYAAABC6cT1AAAGf0lEQVRoQ+3abYydRRUH8N882xYo0IqagEVjokQJKAiKBjXExC9G/aCkGowCIghCkRcrVSSKIu/FEiqgGL6gBIlAYrAqUTH6hZgQFVEMKlQFfItWoQWhZe8z5uzMLdvbfbkLxb13d+fbvfe588x/zpn/+Z9zJpmnI81T3BaAzzfLL1h8weLzZAcWXH2eGHo7zAWLL1h8nuzAjFw9G1N6Kzq8HnuM36MR8iibF3Fv4q+7cv8yDV6K13bYq2furSP8Ag8ncr/vnSnwRViJT2GfCV7yL1yHGxLb+l3EdM9lluNEnIC9xz+f2ZL4Er6Z2DrdXN3fZwp8CU7OfDHxggle8lTLbQ1nJ/7Z7yKmey5zYGZt4h2IzR8/trRc2PDlxJPTzfVcgJ+CC0wMPOa9F6cm7up3EVM9V9386MxliVdM8GwAv6hh/awCz/w7lY25OtF5ruBz4ZLP42NYNrDAFbC3YPWuILnMAfgq3oaRQQYea/stViV+sgssvjKzLvGySeaaNVfP4d7Btokgvxj/bblgpueuF1hmWcyTCmfE3J3M1lTcv0vMswM88zR+jpw4osu6me8kzkpsfLZWzxyRuabO22buxxOJ12FxnXfWgEe83pB5sOE47BsLymzscOoi7nw2JJfZreUjiUsTyzKPZm5NvBDvSuw268AzNzV8H5/Am+qCnsAXgpgSW2Zq9cyKlksbPlTd+te4quWNieMHBfiNDdciYnwsdI/MaOaWhnMTf54J8CqNj8x8JXFIZltYu+HqlmNT8YSBsHgAPw/vxvlVV4du/s0oaxbxg0TbL/jMni0nNcVjQq7+HZfgtpbzBg342TgQ63AkmsymxBW4IjE6A+D7Vzd/fyWxIM/VuCe+HzTgZ2Jpy/kNJ2FJLmLm24mPJ/42A+Bvrxt4SISwlhsaPodH26LZB8rVA3inwwebsrixJCZzX+KMxI/7AV61eVh3DV6Mx3EOvh4kN6jAg8nfUCXm4d1wE66OyxNPTQc+s3/o/MoXizL3JE5O3F3P/uBZPPF4Zr+Wi5uSO48ZPRdyCwn7YB/A35m5KhWNHox4fcNnIs0ddOCRSBxf8+cQG+Huf0l8NJVYP+nI7NXy2ar4QqIGm69JfKPOE2w/mBavCzwM11R2D+ChsUO7hyUfmwx55qDM1xJvqZ7y08TpifuGBfjeURVJnNIVGpkNiXNS0ds7jcySDitDCCWW56LJ10fRo8sNA+3qXUSZD2CtQlZh9T+1rB7h9oliembflnMbzqgSNZKbKGHdPm7OwXb1CvQ1metSETMpszmzvikCJNh/h5E5PHNl4qga/+/cxqrdeWDYgIe7X5L4cGJPJX2940lOX8pD41FnFnc4riluvQKbK0dcHJFi2IBHNTQSlguru4d2/wPOTNzRA3x5y+U1E1uqWDkETOT026XuUJzx6u7ReLhSYenQ7uHua0fKZmwfmcPqsQjxE5WVONcRxn7X89zgn/EKPMRMxOVQXmP18Mx3q3b/Y/0cQE/IhFtHESMsHFlZ1Ml3CH3DZPHImY+pxcKumNmYirtvqMBfhMuU6s3iqOQkTsMPe1tCQwO8Ajs0lxr7W+vnp1MJc9EgCNd/cy6x+9D4veXmprj5wxMw/3C4egW6zzgZOlYZzfwo3F2J7ael0pJamvlPKgWNKFft1AAcKotXoFEbD7kaoSoQPVKB35+5KHF0lai/rJo+up87jWEE/qqqwY+qrL21LWLm95lPJ16ppKw31XC3PXYPJauPEx7B6BHCgrSizRs18qiaRp8tlN3ueCTYPHH9RNaunjI8Z7wLYpT3jZSCYXQ8e9vTsRE/q+no3XMKeObgGtaintbb/AvXj4JDkNw/5hrwYPfIvlZFUbLn7G5q+eQIN09Vnho6cqvnM/Lt99RixH49wO8K0ZL41WTWHoQzvsNVkOheZqKhEGpsp3SzB+BBtZAYve7uOR9tuTaaB6l0XScdYfEQPpkTUyHEGP+XqyDBzu+NBCITUjNWHynkrbWKOuWFn1xKzqsyx0bdvS78odp0+N503Zao0uCsWuSIDku8/7EO60b41vN5+Ses9BKlTdvd8bhp9EBvJjWJAIn/vxwHe6b3tSk6JFPV4nq85oAOrx555v/x/rh3E6Lo+bnuNS4uB4Cuq0ZfvO8X1rM6q/+vnjLVqZq7v83onttc2oYF4HPJmv1gWbB4P7s0l55ZsPhcsmY/WBYs3s8uzaVn5q3F/wf70mRuBCtbjQAAAABJRU5ErkJggg==" -} --------------------------------------------------- -// KIBANA diff --git a/docs/api/spaces-management/put.asciidoc b/docs/api/spaces-management/put.asciidoc deleted file mode 100644 index 88d0d41114eb5b..00000000000000 --- a/docs/api/spaces-management/put.asciidoc +++ /dev/null @@ -1,64 +0,0 @@ -[[spaces-api-put]] -=== Update space API -++++ -Update space -++++ - -experimental[] Update an existing {kib} space. - -[[spaces-api-put-api-request]] -==== Request - -`PUT :/api/spaces/space/` - -[[spaces-api-put-request-body]] -==== Request body - -`id`:: - (Required, string) The space ID that is part of the {kib} URL when inside the space. You are unable to change the ID with the update operation. - -`name`:: - (Required, string) The display name for the space. - -`description`:: - (Optional, string) The description for the space. - -`disabledFeatures`:: - (Optional, string array) The list of disabled features for the space. To get a list of available feature IDs, use the <>. - -`initials`:: - (Optional, string) Specifies the initials shown in the space avatar. By default, the initials are automatically generated from the space name. Initials must be 1 or 2 characters. - -`color`:: - (Optional, string) Specifies the hexadecimal color code used in the space avatar. By default, the color is automatically generated from the space name. - -`imageUrl`:: - (Optional, string) Specifies the data-url encoded image to display in the space avatar. If specified, `initials` will not be displayed, and the `color` will be visible as the background color for transparent images. - For best results, your image should be 64x64. Images will not be optimized by this API call, so care should be taken when using custom images. - -`solution`:: - (Optional, string) The solution defined for the space. Can be one of `security`, `oblt`, `es`, `classic`. - -[[spaces-api-put-response-codes]] -==== Response codes - -`200`:: - Indicates a successful call. - -[[sample-api-example]] -==== Example - -[source,sh] --------------------------------------------------- -$ curl -X PUT api/spaces/space/marketing -{ - "id": "marketing", - "name": "Marketing", - "description" : "This is the Marketing Space", - "color": "#aabbcc", - "initials": "MK", - "disabledFeatures": [], - "imageUrl": "" -} --------------------------------------------------- -// KIBANA diff --git a/docs/api/spaces-management/resolve_copy_saved_objects_conflicts.asciidoc b/docs/api/spaces-management/resolve_copy_saved_objects_conflicts.asciidoc deleted file mode 100644 index 0ca5c72070a860..00000000000000 --- a/docs/api/spaces-management/resolve_copy_saved_objects_conflicts.asciidoc +++ /dev/null @@ -1,317 +0,0 @@ -[role="xpack"] -[[spaces-api-resolve-copy-saved-objects-conflicts]] -=== Resolve copy saved objects to space conflicts API -++++ -Resolve copy to space conflicts -++++ - -experimental[] Overwrite saved objects that are returned as errors from the <>. - -[[spaces-api-resolve-copy-saved-objects-conflicts-request]] -==== {api-request-title} - -`POST :/api/spaces/_resolve_copy_saved_objects_errors` - -`POST :/s//api/spaces/_resolve_copy_saved_objects_errors` - -[[spaces-api-resolve-copy-saved-objects-conflicts-prereqs]] -==== {api-prereq-title} - -Execute the <>, which returns the errors for you to resolve. - -[[spaces-api-resolve-copy-saved-objects-conflicts-path-params]] -==== {api-path-parms-title} - -`space_id`:: -(Optional, string) The ID of the space that contains the saved objects you want to copy. When `space_id` is unspecified in the URL, the default space is used. The `space_id` must be the same value used during the failed <> operation. - -[role="child_attributes"] -[[spaces-api-resolve-copy-saved-objects-conflicts-request-body]] -==== {api-request-body-title} - -`objects`:: - (Required, object array) The saved objects to copy. The `objects` must be the same values used during the failed <> operation. -+ -.Properties of `objects` -[%collapsible%open] -===== - `type`::: - (Required, string) The saved object type. - - `id`::: - (Required, string) The saved object ID. -===== - -`includeReferences`:: - (Optional, boolean) When set to `true`, all saved objects related to the specified saved objects are copied into the target spaces. The `includeReferences` must be the same values used during the failed <> operation. The default value is `false`. - -`createNewCopies`:: - (Optional, boolean) Creates new copies of the saved objects, regenerates each object ID, and resets the origin. When enabled during the - initial copy, also enable when resolving copy errors. The default value is `true`. - -`retries`:: - (Required, object) The retry operations to attempt, which can specify how to resolve different types of errors. Object keys represent the - target space IDs. -+ -.Properties of `retries` -[%collapsible%open] -===== - ``::: - (Required, array) The errors to resolve for the specified ``. -+ - -.Properties of `` -[%collapsible%open] -====== - `type`:::: - (Required, string) The saved object type. - `id`:::: - (Required, string) The saved object ID. - `overwrite`:::: - (Required, boolean) When set to `true`, the saved object from the source space (designated by the <>) overwrites the conflicting object in the destination space. When set to `false`, this does nothing. - `destinationId`:::: - (Optional, string) Specifies the destination ID that the copied object should have, if different from the current ID. - `ignoreMissingReferences`::: - (Optional, boolean) When set to `true`, any missing references errors are ignored. When set to `false`, does nothing. -====== -===== - -[role="child_attributes"] -[[spaces-api-resolve-copy-saved-objects-conflicts-response-body]] -==== {api-response-body-title} - -``:: - (object) An object that describes the result of the copy operation for the space. Includes the dynamic keys in the response. -+ -.Properties of `` -[%collapsible%open] -===== - `success`::: - (boolean) The copy operation was successful. When set to `false`, some objects may have been copied. For additional information, refer to the `successCount` and `errors` properties. - - `successCount`::: - (number) The number of objects that successfully copied. - - `errors`::: - (Optional, array) The errors that occurred during the copy operation. When errors are reported, the `success` flag is set to `false`. -+ -NOTE: One object may result in multiple errors, which requires separate steps to resolve. For instance, a `missing_references` error and a -`conflict` error. -+ - -.Properties of `errors` -[%collapsible%open] -====== - `id`:::: - (string) The saved object ID that failed to copy. - - `type`:::: - (string) The type of saved object that failed to copy. - - `error`:::: - (object) The error that caused the copy operation to fail. -+ - -.Properties of `error` -[%collapsible%open] -======= - `type`:::: - (string) The type of error. For example, `conflict`, `ambiguous_conflict`, `missing_references`, `unsupported_type`, or `unknown`. - `destinationId`:::: - (Optional, string) The destination ID that was used during the copy attempt. This is only present on `conflict` errors types. - `destinations`:::: - (Optional, array) A list of possible object destinations with `id`, `title`, and `updatedAt` fields to describe each one. This is - only present on `ambiguous_conflict` error types. -======= -====== - -`successResults`::: - (Optional, array) Indicates successfully copied objects, with any applicable metadata. -+ -NOTE: Objects are created when all resolvable errors are addressed, including conflict and missing references errors. For more information, -refer to the <>. - -===== - -[[spaces-api-resolve-copy-saved-objects-conflicts-example]] -==== {api-examples-title} - -[[spaces-api-resolve-copy-saved-objects-conflicts-example-1]] -===== Resolve conflict errors - -This example builds upon the <>. - -Resolve conflict errors for a {data-source}, visualization, and *Canvas* workpad by overwriting the existing saved objects: - -[source,sh] ----- -$ curl -X POST api/spaces/_resolve_copy_saved_objects_errors -{ - "objects": [{ - "type": "dashboard", - "id": "my-dashboard" - }], - "includeReferences": true, - "createNewCopies": false, - "retries": { - "sales": [ - { - "type": "index-pattern", - "id": "my-pattern", - "overwrite": true - }, - { - "type": "visualization", - "id": "my-vis", - "overwrite": true, - "destinationId": "another-vis" - }, - { - "type": "canvas", - "id": "my-canvas", - "overwrite": true, - "destinationId": "yet-another-canvas" - }, - { - "type": "dashboard", - "id": "my-dashboard" - } - ] - } -} ----- -// KIBANA - -The API returns the following: - -[source,sh] ----- -{ - "sales": { - "success": true, - "successCount": 4, - "successResults": [ - { - "id": "my-pattern", - "type": "index-pattern", - "meta": { - "icon": "indexPatternApp", - "title": "my-pattern-*" - } - }, - { - "id": "my-vis", - "type": "visualization", - "destinationId": "another-vis", - "meta": { - "icon": "visualizeApp", - "title": "Look at my visualization" - } - }, - { - "id": "my-canvas", - "type": "canvas-workpad", - "destinationId": "yet-another-canvas", - "meta": { - "icon": "canvasApp", - "title": "Look at my canvas" - } - }, - { - "id": "my-dashboard", - "type": "dashboard", - "meta": { - "icon": "dashboardApp", - "title": "Look at my dashboard" - } - } - ] - } -} ----- - -The result indicates a successful copy, and all four objects are created. - -TIP: If a prior copy attempt resulted in resolvable errors, you must include a retry for each object you want to copy, including any that -were returned in the `successResults` array. In this example, we retried copying the dashboard accordingly. - -[[spaces-api-resolve-copy-saved-objects-conflicts-example-2]] -===== Resolve missing reference errors - -This example builds upon the <>. - -Resolve missing reference errors for a visualization by ignoring the error: - -[source,sh] ----- -$ curl -X POST api/spaces/_resolve_copy_saved_objects_errors -{ - "objects": [{ - "type": "dashboard", - "id": "my-dashboard" - }], - "includeReferences": true, - "createNewCopies": false, - "retries": { - "marketing": [ - { - "type": "visualization", - "id": "my-vis", - "ignoreMissingReferences": true - }, - { - "type": "canvas", - "id": "my-canvas" - }, - { - "type": "dashboard", - "id": "my-dashboard" - } - ] - } -} ----- -// KIBANA - -The API returns the following: - -[source,sh] ----- -{ - "marketing": { - "success": true, - "successCount": 3, - "successResults": [ - { - "id": "my-vis", - "type": "visualization", - "meta": { - "icon": "visualizeApp", - "title": "Look at my visualization" - } - }, - { - "id": "my-canvas", - "type": "canvas-workpad", - "meta": { - "icon": "canvasApp", - "title": "Look at my canvas" - } - }, - { - "id": "my-dashboard", - "type": "dashboard", - "meta": { - "icon": "dashboardApp", - "title": "Look at my dashboard" - } - } - ] - } -} ----- - -The result indicates a successful copy and all three objects are created. - -TIP: If a prior copy attempt resulted in resolvable errors, you must include a retry for each object you want to copy, including any that -were returned in the `successResults` array. In this example, we retried copying the dashboard and canvas accordingly. diff --git a/docs/api/spaces-management/update_objects_spaces.asciidoc b/docs/api/spaces-management/update_objects_spaces.asciidoc deleted file mode 100644 index dec846fd6fee0d..00000000000000 --- a/docs/api/spaces-management/update_objects_spaces.asciidoc +++ /dev/null @@ -1,142 +0,0 @@ -[role="xpack"] -[[spaces-api-update-objects-spaces]] -=== Update saved objects spaces API -++++ -Update saved objects spaces -++++ - -experimental[] Update saved objects spaces. - -Updates one or more saved objects to add and/or remove them from specified spaces. - -[[spaces-api-update-objects-spaces-request]] -==== {api-request-title} - -`POST :/api/spaces/_update_objects_spaces` - -[[spaces-api-update-objects-spaces-request-body]] -==== {api-request-body-title} - -`objects`:: - (Required, object array) The saved objects to update. -+ -.Properties of `objects` -[%collapsible%open] -===== - `type`::: - (Required, string) The saved object type. - - `id`::: - (Required, string) The saved object ID. -===== - -`spacesToAdd`:: - (Required, string array) The IDs of the spaces the specified objects should be added to. - -`spacesToRemove`:: - (Required, string array) The IDs of the spaces the specified objects should be removed from. - -[role="child_attributes"] -[[spaces-api-update-objects-spaces-response-body]] -==== {api-response-body-title} - -`objects`:: - (object array) The saved objects that have been updated. -+ -.Properties of `objects` -[%collapsible%open] -===== - `type`::: - (string) The saved object type. - - `id`::: - (string) The saved object ID. - - `spaces`::: - (string array) The space(s) that the referenced saved object exists in. - - `errors`::: - (string) Included if there was an error updating this object's spaces. -===== - -[[spaces-api-update-objects-spaces-example]] -==== {api-examples-title} - -[[spaces-api-update-objects-spaces-example-1]] -===== Sharing saved objects - -To share a saved object to a space programmatically follow these steps: - -1. Collect reference graph and spaces context for each saved object that you want to share using <>: -+ -[source,sh] ----- -$ curl -X POST /api/spaces/_get_shareable_references -{ - "objects": [ - { - "type": "index-pattern", - "id": "90943e30-9a47-11e8-b64d-95841ca0b247" - } - ] -} ----- -+ -The API returns the following: -+ -[source,json] ----- -{ - "objects": [ - { - "type": "index-pattern", - "id": "90943e30-9a47-11e8-b64d-95841ca0b247", - "spaces": ["default"], - "inboundReferences": [], - "spacesWithMatchingOrigins": ["default"] - } - ] -} ----- - -2. Check each saved object for `spacesWithMatchingOrigins` conflicts. -+ -Objects should not be shared to spaces with matching origins or you will create URL conflicts (causing the same URL to point to different saved objects). - -3. Check each saved object for `spacesWithMatchingAliases` conflicts. -+ -If these match the space(s) that these saved objects will be shared to you should disable legacy URL aliases for them using <>. -+ -When sharing to all spaces (`*`) all entries in `spacesWithMatchingAliases` should be checked. - -4. Update spaces of each saved object and all its references: -+ -[source,sh] ----- -$ curl -X POST /api/spaces/_update_objects_spaces -{ - "objects": [ - { - "type": "index-pattern", - "id": "90943e30-9a47-11e8-b64d-95841ca0b247" - } - ], - "spacesToAdd": ["test"], - "spacesToRemove": [] -} ----- -+ -The API returns the following: -+ -[source,json] ----- -{ - "objects": [ - { - "type": "index-pattern", - "id": "90943e30-9a47-11e8-b64d-95841ca0b247", - "spaces": ["default", "test"] - } - ] -} ----- diff --git a/docs/management/managing-saved-objects.asciidoc b/docs/management/managing-saved-objects.asciidoc index df96721205d598..231843081e7e1f 100644 --- a/docs/management/managing-saved-objects.asciidoc +++ b/docs/management/managing-saved-objects.asciidoc @@ -100,7 +100,6 @@ into an older version of {kib}. For example: [float] -[role="xpack"] [[managing-saved-objects-copy-to-space]] === Copy to other {kib} spaces @@ -117,7 +116,6 @@ the saved object. If you don't want this behavior, use the <> instead. [float] -[role="xpack"] [[managing-saved-objects-share-to-space]] === Share to other {kib} spaces @@ -135,4 +133,79 @@ those space icons to open the Share UI. + The share operation automatically includes child objects that are related to the saved objects. -include::saved-objects/saved-object-ids.asciidoc[] +[[spaces-api-update-objects-spaces-example-1]] +To share a saved object to a space programmatically with the {api-kibana}/group/endpoint-spaces[spaces APIs], follow these steps: + +1. Collect reference graph and spaces context for each saved object that you want to share using get shareable references API: ++ +[source,sh] +---- +$ curl -X POST /api/spaces/_get_shareable_references +{ + "objects": [ + { + "type": "index-pattern", + "id": "90943e30-9a47-11e8-b64d-95841ca0b247" + } + ] +} +---- ++ +The API returns the following: ++ +[source,json] +---- +{ + "objects": [ + { + "type": "index-pattern", + "id": "90943e30-9a47-11e8-b64d-95841ca0b247", + "spaces": ["default"], + "inboundReferences": [], + "spacesWithMatchingOrigins": ["default"] + } + ] +} +---- + +2. Check each saved object for `spacesWithMatchingOrigins` conflicts. ++ +Objects should not be shared to spaces with matching origins or you will create URL conflicts (causing the same URL to point to different saved objects). + +3. Check each saved object for `spacesWithMatchingAliases` conflicts. ++ +If these match the spaces that these saved objects will be shared to you should disable legacy URL aliases for them using the disable legacy URL aliases API. ++ +When sharing to all spaces (`*`) all entries in `spacesWithMatchingAliases` should be checked. + +4. Update spaces of each saved object and all its references: ++ +[source,sh] +---- +$ curl -X POST /api/spaces/_update_objects_spaces +{ + "objects": [ + { + "type": "index-pattern", + "id": "90943e30-9a47-11e8-b64d-95841ca0b247" + } + ], + "spacesToAdd": ["test"], + "spacesToRemove": [] +} +---- ++ +The API returns the following: ++ +[source,json] +---- +{ + "objects": [ + { + "type": "index-pattern", + "id": "90943e30-9a47-11e8-b64d-95841ca0b247", + "spaces": ["default", "test"] + } + ] +} +---- diff --git a/docs/redirects.asciidoc b/docs/redirects.asciidoc index 4088342a6832b5..1fa61881eca927 100644 --- a/docs/redirects.asciidoc +++ b/docs/redirects.asciidoc @@ -1147,3 +1147,53 @@ Refer to {api-kibana}/group/endpoint-cases[cases API]. == Sync {ml} saved objects API Refer to {api-kibana}/group/endpoint-ml[machine learning APIs]. + +[role="exclude",id="spaces-api-post"] +== Create space API + +Refer to {api-kibana}/group/endpoint-spaces[spaces APIs]. + +[role="exclude",id="spaces-api-put"] +== Update space API + +Refer to {api-kibana}/group/endpoint-spaces[spaces APIs]. + +[role="exclude",id="spaces-api-get"] +== Get a space API + +Refer to {api-kibana}/group/endpoint-spaces[spaces APIs]. + +[role="exclude",id="spaces-api-get-all"] +== Get all {kib} spaces API + +Refer to {api-kibana}/group/endpoint-spaces[spaces APIs]. + +[role="exclude",id="spaces-api-delete"] +== Delete space API + +Refer to {api-kibana}/group/endpoint-spaces[spaces APIs]. + +[role="exclude",id="spaces-api-copy-saved-objects"] +== Copy saved objects to space API + +Refer to {api-kibana}/group/endpoint-spaces[spaces APIs]. + +[role="exclude",id="spaces-api-disable-legacy-url-aliases"] +== Disable legacy URL aliases API + +Refer to {api-kibana}/group/endpoint-spaces[spaces APIs]. + +[role="exclude",id="spaces-api-get-shareable-references"] +== Get shareable references API + +Refer to {api-kibana}/group/endpoint-spaces[spaces APIs]. + +[role="exclude",id="spaces-api-resolve-copy-saved-objects-conflicts"] +== Resolve copy saved objects to space conflicts API + +Refer to {api-kibana}/group/endpoint-spaces[spaces APIs]. + +[role="exclude",id="spaces-api-update-objects-spaces"] +== Update saved objects spaces API + +Refer to {api-kibana}/group/endpoint-spaces[spaces APIs]. \ No newline at end of file diff --git a/docs/user/management.asciidoc b/docs/user/management.asciidoc index 0365d39c43d3f4..c46786b98829db 100644 --- a/docs/user/management.asciidoc +++ b/docs/user/management.asciidoc @@ -197,6 +197,8 @@ include::{kibana-root}/docs/management/rollups/create_and_manage_rollups.asciido include::{kibana-root}/docs/management/managing-saved-objects.asciidoc[] +include::{kibana-root}/docs/management/saved-objects/saved-object-ids.asciidoc[] + include::security/index.asciidoc[] include::{kibana-root}/docs/spaces/index.asciidoc[] diff --git a/oas_docs/bundle.json b/oas_docs/bundle.json index 1757e0f4160d71..b1665860e42aa7 100644 --- a/oas_docs/bundle.json +++ b/oas_docs/bundle.json @@ -7100,7 +7100,7 @@ }, "/api/spaces/_copy_saved_objects": { "post": { - "description": "Copy saved objects to spaces", + "description": "It also allows you to automatically copy related objects, so when you copy a dashboard, this can automatically copy over the associated visualizations, data views, and saved searches, as required. You can request to overwrite any objects that already exist in the target space if they share an identifier or you can use the resolve copy saved objects conflicts API to do this on a per-object basis.", "operationId": "%2Fapi%2Fspaces%2F_copy_saved_objects#0", "parameters": [ { @@ -7134,14 +7134,17 @@ "properties": { "compatibilityMode": { "default": false, + "description": "Apply various adjustments to the saved objects that are being copied to maintain compatibility between different Kibana versions. Use this option only if you encounter issues with copied saved objects. This option cannot be used with the `createNewCopies` option.", "type": "boolean" }, "createNewCopies": { "default": true, + "description": "Create new copies of saved objects, regenerate each object identifier, and reset the origin. When used, potential conflict errors are avoided. This option cannot be used with the `overwrite` and `compatibilityMode` options.", "type": "boolean" }, "includeReferences": { "default": false, + "description": "When set to true, all saved objects related to the specified saved objects will also be copied into the target spaces.", "type": "boolean" }, "objects": { @@ -7149,9 +7152,11 @@ "additionalProperties": false, "properties": { "id": { + "description": "The identifier of the saved object to copy.", "type": "string" }, "type": { + "description": "The type of the saved object to copy.", "type": "string" } }, @@ -7165,10 +7170,12 @@ }, "overwrite": { "default": false, + "description": "When set to true, all conflicts are automatically overridden. When a saved object with a matching type and identifier exists in the target space, that version is replaced with the version from the source space. This option cannot be used with the `createNewCopies` option.", "type": "boolean" }, "spaces": { "items": { + "description": "The identifiers of the spaces where you want to copy the specified objects.", "type": "string" }, "type": "array" @@ -7184,13 +7191,14 @@ } }, "responses": {}, - "summary": "", - "tags": [] + "summary": "Copy saved objects between spaces", + "tags": [ + "spaces" + ] } }, "/api/spaces/_disable_legacy_url_aliases": { "post": { - "description": "Disable legacy URL aliases", "operationId": "%2Fapi%2Fspaces%2F_disable_legacy_url_aliases#0", "parameters": [ { @@ -7227,12 +7235,15 @@ "additionalProperties": false, "properties": { "sourceId": { + "description": "The alias source object identifier. This is the legacy object identifier.", "type": "string" }, "targetSpace": { + "description": "The space where the alias target object exists.", "type": "string" }, "targetType": { + "description": "The type of alias target object. ", "type": "string" } }, @@ -7255,13 +7266,15 @@ } }, "responses": {}, - "summary": "", - "tags": [] + "summary": "Disable legacy URL aliases", + "tags": [ + "spaces" + ] } }, "/api/spaces/_get_shareable_references": { "post": { - "description": "Get shareable references", + "description": "Collect references and space contexts for saved objects.", "operationId": "%2Fapi%2Fspaces%2F_get_shareable_references#0", "parameters": [ { @@ -7322,13 +7335,15 @@ } }, "responses": {}, - "summary": "", - "tags": [] + "summary": "Get shareable references", + "tags": [ + "spaces" + ] } }, "/api/spaces/_resolve_copy_saved_objects_errors": { "post": { - "description": "Resolve conflicts copying saved objects", + "description": "Overwrite saved objects that are returned as errors from the copy saved objects to space API.", "operationId": "%2Fapi%2Fspaces%2F_resolve_copy_saved_objects_errors#0", "parameters": [ { @@ -7397,22 +7412,28 @@ "additionalProperties": false, "properties": { "createNewCopy": { + "description": "Creates new copies of the saved objects, regenerates each object ID, and resets the origin.", "type": "boolean" }, "destinationId": { + "description": "Specifies the destination identifier that the copied object should have, if different from the current identifier.", "type": "string" }, "id": { + "description": "The saved object identifier.", "type": "string" }, "ignoreMissingReferences": { + "description": "When set to true, any missing references errors are ignored.", "type": "boolean" }, "overwrite": { "default": false, + "description": "When set to true, the saved object from the source space overwrites the conflicting object in the destination space.", "type": "boolean" }, "type": { + "description": "The saved object type.", "type": "string" } }, @@ -7437,13 +7458,13 @@ } }, "responses": {}, - "summary": "", + "summary": "Resolve conflicts copying saved objects", "tags": [] } }, "/api/spaces/_update_objects_spaces": { "post": { - "description": "Update saved objects in spaces", + "description": "Update one or more saved objects to add or remove them from some spaces.", "operationId": "%2Fapi%2Fspaces%2F_update_objects_spaces#0", "parameters": [ { @@ -7480,9 +7501,11 @@ "additionalProperties": false, "properties": { "id": { + "description": "The identifier of the saved object to update.", "type": "string" }, "type": { + "description": "The type of the saved object to update.", "type": "string" } }, @@ -7496,12 +7519,14 @@ }, "spacesToAdd": { "items": { + "description": "The identifiers of the spaces the saved objects should be added to or removed from.", "type": "string" }, "type": "array" }, "spacesToRemove": { "items": { + "description": "The identifiers of the spaces the saved objects should be added to or removed from.", "type": "string" }, "type": "array" @@ -7518,13 +7543,14 @@ } }, "responses": {}, - "summary": "", - "tags": [] + "summary": "Update saved objects in spaces", + "tags": [ + "spaces" + ] } }, "/api/spaces/space": { "get": { - "description": "Get all spaces", "operationId": "%2Fapi%2Fspaces%2Fspace#0", "parameters": [ { @@ -7540,6 +7566,7 @@ } }, { + "description": "Specifies which authorization checks are applied to the API call. The default value is `any`.", "in": "query", "name": "purpose", "required": false, @@ -7553,6 +7580,7 @@ } }, { + "description": "When enabled, the API returns any spaces that the user is authorized to access in any capacity and each space will contain the purposes for which the user is authorized. This can be useful to determine which spaces a user can read but not take a specific action in. If the security plugin is not enabled, this parameter has no effect, since no authorization checks take place. This parameter cannot be used in with the `purpose` parameter.", "in": "query", "name": "include_authorized_purposes", "required": true, @@ -7592,14 +7620,17 @@ } } ], - "responses": {}, - "summary": "", + "responses": { + "200": { + "description": "Indicates a successful call." + } + }, + "summary": "Get all spaces", "tags": [ "spaces" ] }, "post": { - "description": "Create a space", "operationId": "%2Fapi%2Fspaces%2Fspace#1", "parameters": [ { @@ -7635,29 +7666,36 @@ "type": "boolean" }, "color": { + "description": "The hexadecimal color code used in the space avatar. By default, the color is automatically generated from the space name.", "type": "string" }, "description": { + "description": "A description for the space.", "type": "string" }, "disabledFeatures": { "default": [], "items": { + "description": "The list of features that are turned off in the space.", "type": "string" }, "type": "array" }, "id": { + "description": "The space ID that is part of the Kibana URL when inside the space. Space IDs are limited to lowercase alphanumeric, underscore, and hyphen characters (a-z, 0-9, _, and -). You are cannot change the ID with the update operation.", "type": "string" }, "imageUrl": { + "description": "The data-URL encoded image to display in the space avatar. If specified, initials will not be displayed and the color will be visible as the background color for transparent images. For best results, your image should be 64x64. Images will not be optimized by this API call, so care should be taken when using custom images.", "type": "string" }, "initials": { + "description": "One or two characters that are shown in the space avatar. By default, the initials are automatically generated from the space name.", "maxLength": 2, "type": "string" }, "name": { + "description": "The display name for the space. ", "minLength": 1, "type": "string" }, @@ -7680,8 +7718,12 @@ } } }, - "responses": {}, - "summary": "", + "responses": { + "200": { + "description": "Indicates a successful call." + } + }, + "summary": "Create a space", "tags": [ "spaces" ] @@ -7689,7 +7731,7 @@ }, "/api/spaces/space/{id}": { "delete": { - "description": "Delete a space", + "description": "When you delete a space, all saved objects that belong to the space are automatically deleted, which is permanent and cannot be undone.", "operationId": "%2Fapi%2Fspaces%2Fspace%2F%7Bid%7D#2", "parameters": [ { @@ -7715,6 +7757,7 @@ } }, { + "description": "The space identifier.", "in": "path", "name": "id", "required": true, @@ -7723,14 +7766,20 @@ } } ], - "responses": {}, - "summary": "", + "responses": { + "204": { + "description": "Indicates a successful call." + }, + "404": { + "description": "Indicates that the request failed." + } + }, + "summary": "Delete a space", "tags": [ "spaces" ] }, "get": { - "description": "Get a space", "operationId": "%2Fapi%2Fspaces%2Fspace%2F%7Bid%7D#0", "parameters": [ { @@ -7746,6 +7795,7 @@ } }, { + "description": "The space identifier.", "in": "path", "name": "id", "required": true, @@ -7754,14 +7804,17 @@ } } ], - "responses": {}, - "summary": "", + "responses": { + "200": { + "description": "Indicates a successful call." + } + }, + "summary": "Get a space", "tags": [ "spaces" ] }, "put": { - "description": "Update a space", "operationId": "%2Fapi%2Fspaces%2Fspace%2F%7Bid%7D#1", "parameters": [ { @@ -7787,6 +7840,7 @@ } }, { + "description": "The space identifier. You are unable to change the ID with the update operation.", "in": "path", "name": "id", "required": true, @@ -7805,29 +7859,36 @@ "type": "boolean" }, "color": { + "description": "The hexadecimal color code used in the space avatar. By default, the color is automatically generated from the space name.", "type": "string" }, "description": { + "description": "A description for the space.", "type": "string" }, "disabledFeatures": { "default": [], "items": { + "description": "The list of features that are turned off in the space.", "type": "string" }, "type": "array" }, "id": { + "description": "The space ID that is part of the Kibana URL when inside the space. Space IDs are limited to lowercase alphanumeric, underscore, and hyphen characters (a-z, 0-9, _, and -). You are cannot change the ID with the update operation.", "type": "string" }, "imageUrl": { + "description": "The data-URL encoded image to display in the space avatar. If specified, initials will not be displayed and the color will be visible as the background color for transparent images. For best results, your image should be 64x64. Images will not be optimized by this API call, so care should be taken when using custom images.", "type": "string" }, "initials": { + "description": "One or two characters that are shown in the space avatar. By default, the initials are automatically generated from the space name.", "maxLength": 2, "type": "string" }, "name": { + "description": "The display name for the space. ", "minLength": 1, "type": "string" }, @@ -7850,8 +7911,12 @@ } } }, - "responses": {}, - "summary": "", + "responses": { + "200": { + "description": "Indicates a successful call." + } + }, + "summary": "Update a space", "tags": [ "spaces" ] diff --git a/oas_docs/bundle.serverless.json b/oas_docs/bundle.serverless.json index a3d09fdd76a025..3631a9fffb889e 100644 --- a/oas_docs/bundle.serverless.json +++ b/oas_docs/bundle.serverless.json @@ -6409,7 +6409,6 @@ }, "/api/spaces/space": { "get": { - "description": "Get all spaces", "operationId": "%2Fapi%2Fspaces%2Fspace#0", "parameters": [ { @@ -6425,6 +6424,7 @@ } }, { + "description": "Specifies which authorization checks are applied to the API call. The default value is `any`.", "in": "query", "name": "purpose", "required": false, @@ -6438,6 +6438,7 @@ } }, { + "description": "When enabled, the API returns any spaces that the user is authorized to access in any capacity and each space will contain the purposes for which the user is authorized. This can be useful to determine which spaces a user can read but not take a specific action in. If the security plugin is not enabled, this parameter has no effect, since no authorization checks take place. This parameter cannot be used in with the `purpose` parameter.", "in": "query", "name": "include_authorized_purposes", "required": true, @@ -6477,14 +6478,17 @@ } } ], - "responses": {}, - "summary": "", + "responses": { + "200": { + "description": "Indicates a successful call." + } + }, + "summary": "Get all spaces", "tags": [ "spaces" ] }, "post": { - "description": "Create a space", "operationId": "%2Fapi%2Fspaces%2Fspace#1", "parameters": [ { @@ -6520,29 +6524,36 @@ "type": "boolean" }, "color": { + "description": "The hexadecimal color code used in the space avatar. By default, the color is automatically generated from the space name.", "type": "string" }, "description": { + "description": "A description for the space.", "type": "string" }, "disabledFeatures": { "default": [], "items": { + "description": "The list of features that are turned off in the space.", "type": "string" }, "type": "array" }, "id": { + "description": "The space ID that is part of the Kibana URL when inside the space. Space IDs are limited to lowercase alphanumeric, underscore, and hyphen characters (a-z, 0-9, _, and -). You are cannot change the ID with the update operation.", "type": "string" }, "imageUrl": { + "description": "The data-URL encoded image to display in the space avatar. If specified, initials will not be displayed and the color will be visible as the background color for transparent images. For best results, your image should be 64x64. Images will not be optimized by this API call, so care should be taken when using custom images.", "type": "string" }, "initials": { + "description": "One or two characters that are shown in the space avatar. By default, the initials are automatically generated from the space name.", "maxLength": 2, "type": "string" }, "name": { + "description": "The display name for the space. ", "minLength": 1, "type": "string" } @@ -6556,8 +6567,12 @@ } } }, - "responses": {}, - "summary": "", + "responses": { + "200": { + "description": "Indicates a successful call." + } + }, + "summary": "Create a space", "tags": [ "spaces" ] @@ -6565,7 +6580,7 @@ }, "/api/spaces/space/{id}": { "delete": { - "description": "Delete a space", + "description": "When you delete a space, all saved objects that belong to the space are automatically deleted, which is permanent and cannot be undone.", "operationId": "%2Fapi%2Fspaces%2Fspace%2F%7Bid%7D#2", "parameters": [ { @@ -6591,6 +6606,7 @@ } }, { + "description": "The space identifier.", "in": "path", "name": "id", "required": true, @@ -6599,14 +6615,20 @@ } } ], - "responses": {}, - "summary": "", + "responses": { + "204": { + "description": "Indicates a successful call." + }, + "404": { + "description": "Indicates that the request failed." + } + }, + "summary": "Delete a space", "tags": [ "spaces" ] }, "get": { - "description": "Get a space", "operationId": "%2Fapi%2Fspaces%2Fspace%2F%7Bid%7D#0", "parameters": [ { @@ -6622,6 +6644,7 @@ } }, { + "description": "The space identifier.", "in": "path", "name": "id", "required": true, @@ -6630,14 +6653,17 @@ } } ], - "responses": {}, - "summary": "", + "responses": { + "200": { + "description": "Indicates a successful call." + } + }, + "summary": "Get a space", "tags": [ "spaces" ] }, "put": { - "description": "Update a space", "operationId": "%2Fapi%2Fspaces%2Fspace%2F%7Bid%7D#1", "parameters": [ { @@ -6663,6 +6689,7 @@ } }, { + "description": "The space identifier. You are unable to change the ID with the update operation.", "in": "path", "name": "id", "required": true, @@ -6681,29 +6708,36 @@ "type": "boolean" }, "color": { + "description": "The hexadecimal color code used in the space avatar. By default, the color is automatically generated from the space name.", "type": "string" }, "description": { + "description": "A description for the space.", "type": "string" }, "disabledFeatures": { "default": [], "items": { + "description": "The list of features that are turned off in the space.", "type": "string" }, "type": "array" }, "id": { + "description": "The space ID that is part of the Kibana URL when inside the space. Space IDs are limited to lowercase alphanumeric, underscore, and hyphen characters (a-z, 0-9, _, and -). You are cannot change the ID with the update operation.", "type": "string" }, "imageUrl": { + "description": "The data-URL encoded image to display in the space avatar. If specified, initials will not be displayed and the color will be visible as the background color for transparent images. For best results, your image should be 64x64. Images will not be optimized by this API call, so care should be taken when using custom images.", "type": "string" }, "initials": { + "description": "One or two characters that are shown in the space avatar. By default, the initials are automatically generated from the space name.", "maxLength": 2, "type": "string" }, "name": { + "description": "The display name for the space. ", "minLength": 1, "type": "string" } @@ -6717,8 +6751,12 @@ } } }, - "responses": {}, - "summary": "", + "responses": { + "200": { + "description": "Indicates a successful call." + } + }, + "summary": "Update a space", "tags": [ "spaces" ] diff --git a/oas_docs/examples/copy_saved_objects_request1.yaml b/oas_docs/examples/copy_saved_objects_request1.yaml new file mode 100644 index 00000000000000..4ddb9cc39da227 --- /dev/null +++ b/oas_docs/examples/copy_saved_objects_request1.yaml @@ -0,0 +1,11 @@ +summary: Copy with createNewCopies +description: > + Copy a dashboard with the my-dashboard ID, including all references from the default space to the marketing space. + In this example, the dashboard has a reference to a visualization and that has a reference to a data view. +value: + objects: + - type: dashboard + id: my-dashboard + spaces: + - marketing + includeReferences: true \ No newline at end of file diff --git a/oas_docs/examples/copy_saved_objects_request2.yaml b/oas_docs/examples/copy_saved_objects_request2.yaml new file mode 100644 index 00000000000000..52ae83b66b95db --- /dev/null +++ b/oas_docs/examples/copy_saved_objects_request2.yaml @@ -0,0 +1,12 @@ +summary: Copy without createNewCopies +description: > + Copy a dashboard with the my-dashboard ID, including all references from the default space to the marketing space. + In this example, the dashboard has a reference to a visualization and that has a reference to a data view. +value: + objects: + - type: dashboard + id: my-dashboard + spaces: + - marketing + includeReferences: true + createNewCopies: false \ No newline at end of file diff --git a/oas_docs/examples/copy_saved_objects_response1.yaml b/oas_docs/examples/copy_saved_objects_response1.yaml new file mode 100644 index 00000000000000..d65fc50c5a317b --- /dev/null +++ b/oas_docs/examples/copy_saved_objects_response1.yaml @@ -0,0 +1,28 @@ +summary: Copy with createNewCopies +description: > + The response for successfully copying a dashboard with the my-dashboard ID, including all references from the default space to the marketing space. + The result indicates a successful copy and all three objects are created. + Since these objects were created as new copies, each entry in the successResults array includes a destinationId attribute. +value: + marketing: + success: true + successCount: 3 + successResults: + - id: my-dashboard + type: dashboard + destinationId: "1e127098-5b80-417f-b0f1-c60c8395358f" + meta: + icon: dashboardApp + title: Look at my dashboard + - id: my-vis + type: visualization + destinationId: "a610ed80-1c73-4507-9e13-d3af736c8e04" + meta: + icon: visualizeApp + title: Look at my visualization + - id: my-index-pattern + type: index-pattern + destinationId: "bc3c9c70-bf6f-4bec-b4ce-f4189aa9e26b" + meta: + icon: indexPatternApp + title: my-pattern-* diff --git a/oas_docs/examples/copy_saved_objects_response2.yaml b/oas_docs/examples/copy_saved_objects_response2.yaml new file mode 100644 index 00000000000000..1e49191eaeaa1c --- /dev/null +++ b/oas_docs/examples/copy_saved_objects_response2.yaml @@ -0,0 +1,24 @@ +summary: Copy without createNewCopies +description: > + The response for successfully copying a dashboard with the my-dashboard ID with createNewCopies turned off. + The result indicates a successful copy and all three objects are created. +value: + marketing: + success: true + successCount: 3 + successResults: + - id: my-dashboard + type: dashboard + meta: + icon: dashboardApp + title: Look at my dashboard + - id: my-vis + type: visualization + meta: + icon: visualizeApp + title: Look at my visualization + - id: my-index-pattern + type: index-pattern + meta: + icon: indexPatternApp + title: my-pattern-* diff --git a/oas_docs/examples/copy_saved_objects_response3.yaml b/oas_docs/examples/copy_saved_objects_response3.yaml new file mode 100644 index 00000000000000..aa497ca6bc5202 --- /dev/null +++ b/oas_docs/examples/copy_saved_objects_response3.yaml @@ -0,0 +1,72 @@ +summary: Failed copy response with conflict errors +description: > + A response for a failed copy of a dashboard with the my-dashboard ID including all references from the default space to the marketing and sales spaces. In this example, the dashboard has a reference to a visualization and a Canvas workpad and the visualization has a reference to an index pattern. + The result indicates a successful copy for the marketing space and an unsuccessful copy for the sales space because the data view, visualization, and Canvas workpad each resulted in a conflict error. + Objects are created when the error is resolved using the resolve copy conflicts API. +value: + marketing: + success: true + successCount: 4 + successResults: + - id: my-dashboard + type: dashboard + meta: + icon: dashboardApp + title: Look at my dashboard + - id: my-vis + type: visualization + meta: + icon: visualizeApp + title: Look at my visualization + - id: my-canvas + type: canvas-workpad + meta: + icon: canvasApp + title: Look at my canvas + - id: my-index-pattern + type: index-pattern + meta: + icon: indexPatternApp + title: my-pattern-* + sales: + success: false + successCount: 1, + errors: + - id: my-pattern + type: index-pattern + title: my-pattern-* + error: + type: conflict + meta: + icon: indexPatternApp + title: my-pattern-* + - id: my-visualization + type: my-vis + title: Look at my visualization + error: + type: conflict + destinationId: another-vis + meta: + icon: visualizeApp + title: Look at my visualization + - id: my-canvas + type: canvas-workpad + title: Look at my canvas + error: + type: ambiguous_conflict + destinations: + - id: another-canvas + title: Look at another canvas + updatedAt: "2020-07-08T16:36:32.377Z" + - id: yet-another-canvas + title: Look at yet another canvas + updatedAt: "2020-07-05T12:29:54.849Z" + meta: + icon: canvasApp + title: Look at my canvas + successResults": + - id: my-dashboard + type: dashboard + meta: + icon: dashboardApp + title: Look at my dashboard \ No newline at end of file diff --git a/oas_docs/examples/copy_saved_objects_response4.yaml b/oas_docs/examples/copy_saved_objects_response4.yaml new file mode 100644 index 00000000000000..c9acefafb1d6ef --- /dev/null +++ b/oas_docs/examples/copy_saved_objects_response4.yaml @@ -0,0 +1,33 @@ +summary: Failed copy with missing reference errors +description: > + The response for successfully copying a dashboard with the my-dashboard ID, including all references from the default space to the marketing space. + In this example, the dashboard has a reference to a visualization and a Canvas workpad and the visualization has a reference to a data view. + The result indicates an unsuccessful copy because the visualization resulted in a missing references error. + Objects are created when the errors are resolved using the resolve copy conflicts API. +value: + marketing: + success: false + successCount: 2 + errors: + - id: my-vis + type: visualization + title: Look at my visualization + error: + type: missing_references + references: + - type: index-pattern + id: my-pattern-* + meta: + icon: visualizeApp + title: Look at my visualization + successResults: + - id: my-dashboard + type: dashboard + meta: + icon: dashboardApp + title: Look at my dashboard + - id: my-canvas + type: canvas-workpad + meta: + icon: canvasApp + title: Look at my canvas diff --git a/oas_docs/examples/create_space_request.yaml b/oas_docs/examples/create_space_request.yaml new file mode 100644 index 00000000000000..0e037504f7e7ce --- /dev/null +++ b/oas_docs/examples/create_space_request.yaml @@ -0,0 +1,9 @@ +summary: Create a marketing space +value: + id: marketing + name: Marketing + description : This is the Marketing Space + color: #aabbcc + initials: MK + disabledFeatures: [] + imageUrl: "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAD4AAABACAYAAABC6cT1AAAGf0lEQVRoQ+3abYydRRUH8N882xYo0IqagEVjokQJKAiKBjXExC9G/aCkGowCIghCkRcrVSSKIu/FEiqgGL6gBIlAYrAqUTH6hZgQFVEMKlQFfItWoQWhZe8z5uzMLdvbfbkLxb13d+fbvfe588x/zpn/+Z9zJpmnI81T3BaAzzfLL1h8weLzZAcWXH2eGHo7zAWLL1h8nuzAjFw9G1N6Kzq8HnuM36MR8iibF3Fv4q+7cv8yDV6K13bYq2furSP8Ag8ncr/vnSnwRViJT2GfCV7yL1yHGxLb+l3EdM9lluNEnIC9xz+f2ZL4Er6Z2DrdXN3fZwp8CU7OfDHxggle8lTLbQ1nJ/7Z7yKmey5zYGZt4h2IzR8/trRc2PDlxJPTzfVcgJ+CC0wMPOa9F6cm7up3EVM9V9386MxliVdM8GwAv6hh/awCz/w7lY25OtF5ruBz4ZLP42NYNrDAFbC3YPWuILnMAfgq3oaRQQYea/stViV+sgssvjKzLvGySeaaNVfP4d7Btokgvxj/bblgpueuF1hmWcyTCmfE3J3M1lTcv0vMswM88zR+jpw4osu6me8kzkpsfLZWzxyRuabO22buxxOJ12FxnXfWgEe83pB5sOE47BsLymzscOoi7nw2JJfZreUjiUsTyzKPZm5NvBDvSuw268AzNzV8H5/Am+qCnsAXgpgSW2Zq9cyKlksbPlTd+te4quWNieMHBfiNDdciYnwsdI/MaOaWhnMTf54J8CqNj8x8JXFIZltYu+HqlmNT8YSBsHgAPw/vxvlVV4du/s0oaxbxg0TbL/jMni0nNcVjQq7+HZfgtpbzBg342TgQ63AkmsymxBW4IjE6A+D7Vzd/fyWxIM/VuCe+HzTgZ2Jpy/kNJ2FJLmLm24mPJ/42A+Bvrxt4SISwlhsaPodH26LZB8rVA3inwwebsrixJCZzX+KMxI/7AV61eVh3DV6Mx3EOvh4kN6jAg8nfUCXm4d1wE66OyxNPTQc+s3/o/MoXizL3JE5O3F3P/uBZPPF4Zr+Wi5uSO48ZPRdyCwn7YB/A35m5KhWNHox4fcNnIs0ddOCRSBxf8+cQG+Huf0l8NJVYP+nI7NXy2ar4QqIGm69JfKPOE2w/mBavCzwM11R2D+ChsUO7hyUfmwx55qDM1xJvqZ7y08TpifuGBfjeURVJnNIVGpkNiXNS0ds7jcySDitDCCWW56LJ10fRo8sNA+3qXUSZD2CtQlZh9T+1rB7h9oliembflnMbzqgSNZKbKGHdPm7OwXb1CvQ1metSETMpszmzvikCJNh/h5E5PHNl4qga/+/cxqrdeWDYgIe7X5L4cGJPJX2940lOX8pD41FnFnc4riluvQKbK0dcHJFi2IBHNTQSlguru4d2/wPOTNzRA3x5y+U1E1uqWDkETOT026XuUJzx6u7ReLhSYenQ7uHua0fKZmwfmcPqsQjxE5WVONcRxn7X89zgn/EKPMRMxOVQXmP18Mx3q3b/Y/0cQE/IhFtHESMsHFlZ1Ml3CH3DZPHImY+pxcKumNmYirtvqMBfhMuU6s3iqOQkTsMPe1tCQwO8Ajs0lxr7W+vnp1MJc9EgCNd/cy6x+9D4veXmprj5wxMw/3C4egW6zzgZOlYZzfwo3F2J7ael0pJamvlPKgWNKFft1AAcKotXoFEbD7kaoSoQPVKB35+5KHF0lai/rJo+up87jWEE/qqqwY+qrL21LWLm95lPJ16ppKw31XC3PXYPJauPEx7B6BHCgrSizRs18qiaRp8tlN3ueCTYPHH9RNaunjI8Z7wLYpT3jZSCYXQ8e9vTsRE/q+no3XMKeObgGtaintbb/AvXj4JDkNw/5hrwYPfIvlZFUbLn7G5q+eQIN09Vnho6cqvnM/Lt99RixH49wO8K0ZL41WTWHoQzvsNVkOheZqKhEGpsp3SzB+BBtZAYve7uOR9tuTaaB6l0XScdYfEQPpkTUyHEGP+XqyDBzu+NBCITUjNWHynkrbWKOuWFn1xKzqsyx0bdvS78odp0+N503Zao0uCsWuSIDku8/7EO60b41vN5+Ses9BKlTdvd8bhp9EBvJjWJAIn/vxwHe6b3tSk6JFPV4nq85oAOrx555v/x/rh3E6Lo+bnuNS4uB4Cuq0ZfvO8X1rM6q/+vnjLVqZq7v83onttc2oYF4HPJmv1gWbB4P7s0l55ZsPhcsmY/WBYs3s8uzaVn5q3F/wf70mRuBCtbjQAAAABJRU5ErkJggg==" \ No newline at end of file diff --git a/oas_docs/examples/disable_legacy_url_request1.yaml b/oas_docs/examples/disable_legacy_url_request1.yaml new file mode 100644 index 00000000000000..a85a14d4e1c168 --- /dev/null +++ b/oas_docs/examples/disable_legacy_url_request1.yaml @@ -0,0 +1,9 @@ +summary: Disable legacy URL aliases +description: > + This request leaves the alias intact but the legacy URL for this alias (http://localhost:5601/s/bills-space/app/dashboards#/view/123) will no longer function. + The dashboard still exists and you can access it with the new URL. +value: + aliases: + - targetSpace: bills-space + targetType: dashboard + sourceId: 123 \ No newline at end of file diff --git a/oas_docs/examples/get_space_response.yaml b/oas_docs/examples/get_space_response.yaml new file mode 100644 index 00000000000000..6cf8a250d90aa2 --- /dev/null +++ b/oas_docs/examples/get_space_response.yaml @@ -0,0 +1,10 @@ +summary: Get details about a marketing space +value: + id: marketing + name: Marketing + description : This is the Marketing Space + color: #aabbcc + initials: MK + disabledFeatures: [] + imageUrl: "" + solution: es \ No newline at end of file diff --git a/oas_docs/examples/get_spaces_response1.yaml b/oas_docs/examples/get_spaces_response1.yaml new file mode 100644 index 00000000000000..88e938821a378a --- /dev/null +++ b/oas_docs/examples/get_spaces_response1.yaml @@ -0,0 +1,24 @@ +summary: Get all spaces +description: Get all spaces without specifying any options. +value: + - id: default + name: Default + description: This is the Default Space + disabledFeatures: [] + imageUrl: "" + _reserved: true + - id: marketing + name: Marketing + description: This is the Marketing Space + color: #aabbcc + disabledFeatures: + - apm + initials: MK + imageUrl: "data:image/png;base64,iVBORw0KGgoAAAANSU" + - id: sales + name: Sales + initials: MK + disabledFeatures: + - discover + imageUr": "" + solution: oblt \ No newline at end of file diff --git a/oas_docs/examples/get_spaces_response2.yaml b/oas_docs/examples/get_spaces_response2.yaml new file mode 100644 index 00000000000000..a95c92676b236a --- /dev/null +++ b/oas_docs/examples/get_spaces_response2.yaml @@ -0,0 +1,41 @@ +summary: Get all spaces with custom options +description: > + The user has read-only access to the Sales space. + Get all spaces with the following query parameters: + "purpose=shareSavedObjectsIntoSpace&include_authorized_purposes=true" +value: + - id: default + name: Default + description: This is the Default Space + disabledFeatures: [] + imageUrl: "" + _reserved: true + authorizedPurposes: + any: true + copySavedObjectsIntoSpace: true + findSavedObjects: true + shareSavedObjectsIntoSpace: true + - id: marketing + name: Marketing + description: This is the Marketing Space + color: #aabbcc + disabledFeatures: + - apm + initials: MK + imageUrl: "data:image/png;base64,iVBORw0KGgoAAAANSU" + authorizedPurposes: + any: true + copySavedObjectsIntoSpace: true + findSavedObjects: true + shareSavedObjectsIntoSpace: true + - id: sales + name: Sales + initials: MK + disabledFeatures: + - discover + imageUrl: "" + authorizedPurposes: + any: true + copySavedObjectsIntoSpace: false + findSavedObjects: true + shareSavedObjectsIntoSpace: false \ No newline at end of file diff --git a/oas_docs/examples/resolve_copy_saved_objects_request1.yaml b/oas_docs/examples/resolve_copy_saved_objects_request1.yaml new file mode 100644 index 00000000000000..11cee7931e38cf --- /dev/null +++ b/oas_docs/examples/resolve_copy_saved_objects_request1.yaml @@ -0,0 +1,26 @@ +summary: Resolve conflict errors +description: > + Resolve conflict errors for a data view, visualization, and Canvas workpad by overwriting the existing saved objects. + NOTE: If a prior copy attempt resulted in resolvable errors, you must include a retry for each object you want to copy, including any that were returned in the successResults array. + In this example, we retried copying the dashboard accordingly. +value: + objects: + - type: dashboard + id: my-dashboard + includeReferences: true + createNewCopies: false + retries: + sales: + - type: index-pattern + id: my-pattern + overwrite: true + - type: visualization + id: my-vis + overwrite: true, + destinationId: another-vis + - type: canvas + id: my-canvas + overwrite: true + destinationId: yet-another-canvas + - type: dashboard + id: my-dashboard \ No newline at end of file diff --git a/oas_docs/examples/resolve_copy_saved_objects_request2.yaml b/oas_docs/examples/resolve_copy_saved_objects_request2.yaml new file mode 100644 index 00000000000000..e8438b77fc1a57 --- /dev/null +++ b/oas_docs/examples/resolve_copy_saved_objects_request2.yaml @@ -0,0 +1,20 @@ +summary: Resolve missing reference errors +description: > + Resolve missing reference errors for a visualization by ignoring the error. + NOTE: If a prior copy attempt resulted in resolvable errors, you must include a retry for each object you want to copy, including any that were returned in the successResults array. + In this example, we retried copying the dashboard and canvas accordingly. +value: + objects: + - type: dashboard + id: my-dashboard + includeReferences: true + createNewCopies: false + retries: + marketing: + - type: visualization + id: my-vis + ignoreMissingReferences: true + - type: canvas + id: my-canvas + - type: dashboard + id: my-dashboard diff --git a/oas_docs/examples/resolve_copy_saved_objects_response1.yaml b/oas_docs/examples/resolve_copy_saved_objects_response1.yaml new file mode 100644 index 00000000000000..fee42792f05a06 --- /dev/null +++ b/oas_docs/examples/resolve_copy_saved_objects_response1.yaml @@ -0,0 +1,31 @@ +summary: Resolve conflict errors +description: > + The response for resolving conflict errors for a data view, visualization, and Canvas workpad by overwriting the existing saved objects. + The result indicates a successful copy and all four objects are created. +value: + sales: + success: true + successCount: 4 + successResults: + - id: my-pattern + type: index-pattern + meta: + icon: indexPatternApp + title: my-pattern-* + - id: my-vis + type: visualization + destinationId: another-vis + meta: + icon: visualizeApp + title: Look at my visualization + - id: my-canvas + type: canvas-workpad + destinationId: yet-another-canvas + meta: + icon: canvasApp + title: Look at my canvas + - id: my-dashboard + type: dashboard + meta: + icon: dashboardApp + title: Look at my dashboard diff --git a/oas_docs/examples/resolve_copy_saved_objects_response2.yaml b/oas_docs/examples/resolve_copy_saved_objects_response2.yaml new file mode 100644 index 00000000000000..0ea8f58ce405db --- /dev/null +++ b/oas_docs/examples/resolve_copy_saved_objects_response2.yaml @@ -0,0 +1,24 @@ +summary: Resolve conflict errors +description: > + The response for resolving missing reference errors for a visualization. + The result indicates a successful copy and all three objects are created. +value: + marketing: + success: true + successCount: 3 + successResults: + - id: my-vis + type: visualization + meta: + icon: visualizeApp + title: Look at my visualization + - id: my-canvas + type: canvas-workpad + meta: + icon: canvasApp + title: Look at my canvas + - id: my-dashboard + type: dashboard + meta: + icon: dashboardApp + title: Look at my dashboard diff --git a/oas_docs/examples/update_saved_objects_spaces_request1.yaml b/oas_docs/examples/update_saved_objects_spaces_request1.yaml new file mode 100644 index 00000000000000..0f341e6c3ace46 --- /dev/null +++ b/oas_docs/examples/update_saved_objects_spaces_request1.yaml @@ -0,0 +1,9 @@ +summary: Update saved object spaces +description: Update the spaces of each saved object and all its references. +value: + objects: + - type: index-pattern + id: 90943e30-9a47-11e8-b64d-95841ca0b247 + spacesToAdd: + - test + spacesToRemove: [] \ No newline at end of file diff --git a/oas_docs/examples/update_saved_objects_spaces_response1.yaml b/oas_docs/examples/update_saved_objects_spaces_response1.yaml new file mode 100644 index 00000000000000..1f1c1d47c8b065 --- /dev/null +++ b/oas_docs/examples/update_saved_objects_spaces_response1.yaml @@ -0,0 +1,10 @@ +summary: Update saved object spaces +description: > + The response from updating the spaces of saved objects. +value: + objects: + - type: index-pattern + id: 90943e30-9a47-11e8-b64d-95841ca0b247 + spaces: + - default + - test \ No newline at end of file diff --git a/oas_docs/examples/update_space_request.yaml b/oas_docs/examples/update_space_request.yaml new file mode 100644 index 00000000000000..42d1972390759b --- /dev/null +++ b/oas_docs/examples/update_space_request.yaml @@ -0,0 +1,10 @@ +summary: Update a marketing space +description: Update the marketing space to remove the imageUrl. +value: + id: marketing + name: Marketing + description : This is the Marketing Space + color: #aabbcc + initials: MK + disabledFeatures: [] + imageUrl: "" \ No newline at end of file diff --git a/oas_docs/makefile b/oas_docs/makefile index 717895f9b6c1c6..ce24aa5b7b8b7e 100644 --- a/oas_docs/makefile +++ b/oas_docs/makefile @@ -52,11 +52,13 @@ api-docs-overlay: ## Run spectral API docs linter on kibana.serverless.yaml @npx bump overlay "output/kibana.serverless.yaml" "overlays/kibana.overlays.serverless.yaml" > "output/kibana.serverless.tmp1.yaml" @npx bump overlay "output/kibana.serverless.tmp1.yaml" "overlays/alerting.overlays.yaml" > "output/kibana.serverless.tmp2.yaml" @npx bump overlay "output/kibana.serverless.tmp2.yaml" "overlays/connectors.overlays.yaml" > "output/kibana.serverless.tmp3.yaml" + @npx bump overlay "output/kibana.serverless.tmp3.yaml" "overlays/kibana.overlays.shared.yaml" > "output/kibana.serverless.tmp4.yaml" @npx bump overlay "output/kibana.yaml" "overlays/kibana.overlays.yaml" > "output/kibana.tmp1.yaml" @npx bump overlay "output/kibana.tmp1.yaml" "overlays/alerting.overlays.yaml" > "output/kibana.tmp2.yaml" @npx bump overlay "output/kibana.tmp2.yaml" "overlays/connectors.overlays.yaml" > "output/kibana.tmp3.yaml" - @npx @redocly/cli bundle output/kibana.serverless.tmp3.yaml --ext yaml -o output/kibana.serverless.new.yaml - @npx @redocly/cli bundle output/kibana.tmp3.yaml --ext yaml -o output/kibana.new.yaml + @npx bump overlay "output/kibana.tmp3.yaml" "overlays/kibana.overlays.shared.yaml" > "output/kibana.tmp4.yaml" + @npx @redocly/cli bundle output/kibana.serverless.tmp4.yaml --ext yaml -o output/kibana.serverless.new.yaml + @npx @redocly/cli bundle output/kibana.tmp4.yaml --ext yaml -o output/kibana.new.yaml rm output/kibana.tmp*.yaml rm output/kibana.serverless.tmp*.yaml diff --git a/oas_docs/output/kibana.serverless.staging.yaml b/oas_docs/output/kibana.serverless.staging.yaml index 2634ca5ad5959f..fa7139a863f063 100644 --- a/oas_docs/output/kibana.serverless.staging.yaml +++ b/oas_docs/output/kibana.serverless.staging.yaml @@ -16302,7 +16302,6 @@ paths: - Prompts API /api/spaces/space: get: - description: Get all spaces operationId: '%2Fapi%2Fspaces%2Fspace#0' parameters: - description: The version of the API to use @@ -16313,7 +16312,10 @@ paths: enum: - '2023-10-31' type: string - - in: query + - description: >- + Specifies which authorization checks are applied to the API call. + The default value is `any`. + in: query name: purpose required: false schema: @@ -16322,7 +16324,15 @@ paths: - copySavedObjectsIntoSpace - shareSavedObjectsIntoSpace type: string - - in: query + - description: >- + When enabled, the API returns any spaces that the user is authorized + to access in any capacity and each space will contain the purposes + for which the user is authorized. This can be useful to determine + which spaces a user can read but not take a specific action in. If + the security plugin is not enabled, this parameter has no effect, + since no authorization checks take place. This parameter cannot be + used in with the `purpose` parameter. + in: query name: include_authorized_purposes required: true schema: @@ -16341,12 +16351,13 @@ paths: x-oas-optional: true - type: boolean x-oas-optional: true - responses: {} - summary: '' + responses: + '200': + description: Indicates a successful call. + summary: Get all spaces tags: - spaces post: - description: Create a space operationId: '%2Fapi%2Fspaces%2Fspace#1' parameters: - description: The version of the API to use @@ -16374,34 +16385,61 @@ paths: _reserved: type: boolean color: + description: >- + The hexadecimal color code used in the space avatar. By + default, the color is automatically generated from the space + name. type: string description: + description: A description for the space. type: string disabledFeatures: default: [] items: + description: The list of features that are turned off in the space. type: string type: array id: + description: >- + The space ID that is part of the Kibana URL when inside the + space. Space IDs are limited to lowercase alphanumeric, + underscore, and hyphen characters (a-z, 0-9, _, and -). You + are cannot change the ID with the update operation. type: string imageUrl: + description: >- + The data-URL encoded image to display in the space avatar. + If specified, initials will not be displayed and the color + will be visible as the background color for transparent + images. For best results, your image should be 64x64. Images + will not be optimized by this API call, so care should be + taken when using custom images. type: string initials: + description: >- + One or two characters that are shown in the space avatar. By + default, the initials are automatically generated from the + space name. maxLength: 2 type: string name: + description: 'The display name for the space. ' minLength: 1 type: string required: - id - name - responses: {} - summary: '' + responses: + '200': + description: Indicates a successful call. + summary: Create a space tags: - spaces '/api/spaces/space/{id}': delete: - description: Delete a space + description: >- + When you delete a space, all saved objects that belong to the space are + automatically deleted, which is permanent and cannot be undone. operationId: '%2Fapi%2Fspaces%2Fspace%2F%7Bid%7D#2' parameters: - description: The version of the API to use @@ -16419,17 +16457,21 @@ paths: schema: example: 'true' type: string - - in: path + - description: The space identifier. + in: path name: id required: true schema: type: string - responses: {} - summary: '' + responses: + '204': + description: Indicates a successful call. + '404': + description: Indicates that the request failed. + summary: Delete a space tags: - spaces get: - description: Get a space operationId: '%2Fapi%2Fspaces%2Fspace%2F%7Bid%7D#0' parameters: - description: The version of the API to use @@ -16440,17 +16482,19 @@ paths: enum: - '2023-10-31' type: string - - in: path + - description: The space identifier. + in: path name: id required: true schema: type: string - responses: {} - summary: '' + responses: + '200': + description: Indicates a successful call. + summary: Get a space tags: - spaces put: - description: Update a space operationId: '%2Fapi%2Fspaces%2Fspace%2F%7Bid%7D#1' parameters: - description: The version of the API to use @@ -16468,7 +16512,10 @@ paths: schema: example: 'true' type: string - - in: path + - description: >- + The space identifier. You are unable to change the ID with the + update operation. + in: path name: id required: true schema: @@ -16483,29 +16530,54 @@ paths: _reserved: type: boolean color: + description: >- + The hexadecimal color code used in the space avatar. By + default, the color is automatically generated from the space + name. type: string description: + description: A description for the space. type: string disabledFeatures: default: [] items: + description: The list of features that are turned off in the space. type: string type: array id: + description: >- + The space ID that is part of the Kibana URL when inside the + space. Space IDs are limited to lowercase alphanumeric, + underscore, and hyphen characters (a-z, 0-9, _, and -). You + are cannot change the ID with the update operation. type: string imageUrl: + description: >- + The data-URL encoded image to display in the space avatar. + If specified, initials will not be displayed and the color + will be visible as the background color for transparent + images. For best results, your image should be 64x64. Images + will not be optimized by this API call, so care should be + taken when using custom images. type: string initials: + description: >- + One or two characters that are shown in the space avatar. By + default, the initials are automatically generated from the + space name. maxLength: 2 type: string name: + description: 'The display name for the space. ' minLength: 1 type: string required: - id - name - responses: {} - summary: '' + responses: + '200': + description: Indicates a successful call. + summary: Update a space tags: - spaces /api/status: diff --git a/oas_docs/output/kibana.serverless.yaml b/oas_docs/output/kibana.serverless.yaml index 2634ca5ad5959f..fa7139a863f063 100644 --- a/oas_docs/output/kibana.serverless.yaml +++ b/oas_docs/output/kibana.serverless.yaml @@ -16302,7 +16302,6 @@ paths: - Prompts API /api/spaces/space: get: - description: Get all spaces operationId: '%2Fapi%2Fspaces%2Fspace#0' parameters: - description: The version of the API to use @@ -16313,7 +16312,10 @@ paths: enum: - '2023-10-31' type: string - - in: query + - description: >- + Specifies which authorization checks are applied to the API call. + The default value is `any`. + in: query name: purpose required: false schema: @@ -16322,7 +16324,15 @@ paths: - copySavedObjectsIntoSpace - shareSavedObjectsIntoSpace type: string - - in: query + - description: >- + When enabled, the API returns any spaces that the user is authorized + to access in any capacity and each space will contain the purposes + for which the user is authorized. This can be useful to determine + which spaces a user can read but not take a specific action in. If + the security plugin is not enabled, this parameter has no effect, + since no authorization checks take place. This parameter cannot be + used in with the `purpose` parameter. + in: query name: include_authorized_purposes required: true schema: @@ -16341,12 +16351,13 @@ paths: x-oas-optional: true - type: boolean x-oas-optional: true - responses: {} - summary: '' + responses: + '200': + description: Indicates a successful call. + summary: Get all spaces tags: - spaces post: - description: Create a space operationId: '%2Fapi%2Fspaces%2Fspace#1' parameters: - description: The version of the API to use @@ -16374,34 +16385,61 @@ paths: _reserved: type: boolean color: + description: >- + The hexadecimal color code used in the space avatar. By + default, the color is automatically generated from the space + name. type: string description: + description: A description for the space. type: string disabledFeatures: default: [] items: + description: The list of features that are turned off in the space. type: string type: array id: + description: >- + The space ID that is part of the Kibana URL when inside the + space. Space IDs are limited to lowercase alphanumeric, + underscore, and hyphen characters (a-z, 0-9, _, and -). You + are cannot change the ID with the update operation. type: string imageUrl: + description: >- + The data-URL encoded image to display in the space avatar. + If specified, initials will not be displayed and the color + will be visible as the background color for transparent + images. For best results, your image should be 64x64. Images + will not be optimized by this API call, so care should be + taken when using custom images. type: string initials: + description: >- + One or two characters that are shown in the space avatar. By + default, the initials are automatically generated from the + space name. maxLength: 2 type: string name: + description: 'The display name for the space. ' minLength: 1 type: string required: - id - name - responses: {} - summary: '' + responses: + '200': + description: Indicates a successful call. + summary: Create a space tags: - spaces '/api/spaces/space/{id}': delete: - description: Delete a space + description: >- + When you delete a space, all saved objects that belong to the space are + automatically deleted, which is permanent and cannot be undone. operationId: '%2Fapi%2Fspaces%2Fspace%2F%7Bid%7D#2' parameters: - description: The version of the API to use @@ -16419,17 +16457,21 @@ paths: schema: example: 'true' type: string - - in: path + - description: The space identifier. + in: path name: id required: true schema: type: string - responses: {} - summary: '' + responses: + '204': + description: Indicates a successful call. + '404': + description: Indicates that the request failed. + summary: Delete a space tags: - spaces get: - description: Get a space operationId: '%2Fapi%2Fspaces%2Fspace%2F%7Bid%7D#0' parameters: - description: The version of the API to use @@ -16440,17 +16482,19 @@ paths: enum: - '2023-10-31' type: string - - in: path + - description: The space identifier. + in: path name: id required: true schema: type: string - responses: {} - summary: '' + responses: + '200': + description: Indicates a successful call. + summary: Get a space tags: - spaces put: - description: Update a space operationId: '%2Fapi%2Fspaces%2Fspace%2F%7Bid%7D#1' parameters: - description: The version of the API to use @@ -16468,7 +16512,10 @@ paths: schema: example: 'true' type: string - - in: path + - description: >- + The space identifier. You are unable to change the ID with the + update operation. + in: path name: id required: true schema: @@ -16483,29 +16530,54 @@ paths: _reserved: type: boolean color: + description: >- + The hexadecimal color code used in the space avatar. By + default, the color is automatically generated from the space + name. type: string description: + description: A description for the space. type: string disabledFeatures: default: [] items: + description: The list of features that are turned off in the space. type: string type: array id: + description: >- + The space ID that is part of the Kibana URL when inside the + space. Space IDs are limited to lowercase alphanumeric, + underscore, and hyphen characters (a-z, 0-9, _, and -). You + are cannot change the ID with the update operation. type: string imageUrl: + description: >- + The data-URL encoded image to display in the space avatar. + If specified, initials will not be displayed and the color + will be visible as the background color for transparent + images. For best results, your image should be 64x64. Images + will not be optimized by this API call, so care should be + taken when using custom images. type: string initials: + description: >- + One or two characters that are shown in the space avatar. By + default, the initials are automatically generated from the + space name. maxLength: 2 type: string name: + description: 'The display name for the space. ' minLength: 1 type: string required: - id - name - responses: {} - summary: '' + responses: + '200': + description: Indicates a successful call. + summary: Update a space tags: - spaces /api/status: diff --git a/oas_docs/output/kibana.staging.yaml b/oas_docs/output/kibana.staging.yaml index 647ad65e617e02..6c1ad62cf7a2b5 100644 --- a/oas_docs/output/kibana.staging.yaml +++ b/oas_docs/output/kibana.staging.yaml @@ -20841,7 +20841,13 @@ paths: - roles /api/spaces/_copy_saved_objects: post: - description: Copy saved objects to spaces + description: >- + It also allows you to automatically copy related objects, so when you + copy a dashboard, this can automatically copy over the associated + visualizations, data views, and saved searches, as required. You can + request to overwrite any objects that already exist in the target space + if they share an identifier or you can use the resolve copy saved + objects conflicts API to do this on a per-object basis. operationId: '%2Fapi%2Fspaces%2F_copy_saved_objects#0' parameters: - description: The version of the API to use @@ -20868,12 +20874,26 @@ paths: properties: compatibilityMode: default: false + description: >- + Apply various adjustments to the saved objects that are + being copied to maintain compatibility between different + Kibana versions. Use this option only if you encounter + issues with copied saved objects. This option cannot be used + with the `createNewCopies` option. type: boolean createNewCopies: default: true + description: >- + Create new copies of saved objects, regenerate each object + identifier, and reset the origin. When used, potential + conflict errors are avoided. This option cannot be used + with the `overwrite` and `compatibilityMode` options. type: boolean includeReferences: default: false + description: >- + When set to true, all saved objects related to the specified + saved objects will also be copied into the target spaces. type: boolean objects: items: @@ -20881,8 +20901,10 @@ paths: type: object properties: id: + description: The identifier of the saved object to copy. type: string type: + description: The type of the saved object to copy. type: string required: - type @@ -20890,20 +20912,29 @@ paths: type: array overwrite: default: false + description: >- + When set to true, all conflicts are automatically + overridden. When a saved object with a matching type and + identifier exists in the target space, that version is + replaced with the version from the source space. This option + cannot be used with the `createNewCopies` option. type: boolean spaces: items: + description: >- + The identifiers of the spaces where you want to copy the + specified objects. type: string type: array required: - spaces - objects responses: {} - summary: '' - tags: [] + summary: Copy saved objects between spaces + tags: + - spaces /api/spaces/_disable_legacy_url_aliases: post: - description: Disable legacy URL aliases operationId: '%2Fapi%2Fspaces%2F_disable_legacy_url_aliases#0' parameters: - description: The version of the API to use @@ -20934,10 +20965,15 @@ paths: type: object properties: sourceId: + description: >- + The alias source object identifier. This is the legacy + object identifier. type: string targetSpace: + description: The space where the alias target object exists. type: string targetType: + description: 'The type of alias target object. ' type: string required: - targetSpace @@ -20947,11 +20983,12 @@ paths: required: - aliases responses: {} - summary: '' - tags: [] + summary: Disable legacy URL aliases + tags: + - spaces /api/spaces/_get_shareable_references: post: - description: Get shareable references + description: Collect references and space contexts for saved objects. operationId: '%2Fapi%2Fspaces%2F_get_shareable_references#0' parameters: - description: The version of the API to use @@ -20992,11 +21029,14 @@ paths: required: - objects responses: {} - summary: '' - tags: [] + summary: Get shareable references + tags: + - spaces /api/spaces/_resolve_copy_saved_objects_errors: post: - description: Resolve conflicts copying saved objects + description: >- + Overwrite saved objects that are returned as errors from the copy saved + objects to space API. operationId: '%2Fapi%2Fspaces%2F_resolve_copy_saved_objects_errors#0' parameters: - description: The version of the API to use @@ -21050,17 +21090,33 @@ paths: type: object properties: createNewCopy: + description: >- + Creates new copies of the saved objects, regenerates + each object ID, and resets the origin. type: boolean destinationId: + description: >- + Specifies the destination identifier that the copied + object should have, if different from the current + identifier. type: string id: + description: The saved object identifier. type: string ignoreMissingReferences: + description: >- + When set to true, any missing references errors are + ignored. type: boolean overwrite: default: false + description: >- + When set to true, the saved object from the source + space overwrites the conflicting object in the + destination space. type: boolean type: + description: The saved object type. type: string required: - type @@ -21071,11 +21127,11 @@ paths: - retries - objects responses: {} - summary: '' + summary: Resolve conflicts copying saved objects tags: [] /api/spaces/_update_objects_spaces: post: - description: Update saved objects in spaces + description: Update one or more saved objects to add or remove them from some spaces. operationId: '%2Fapi%2Fspaces%2F_update_objects_spaces#0' parameters: - description: The version of the API to use @@ -21106,8 +21162,10 @@ paths: type: object properties: id: + description: The identifier of the saved object to update. type: string type: + description: The type of the saved object to update. type: string required: - type @@ -21115,10 +21173,16 @@ paths: type: array spacesToAdd: items: + description: >- + The identifiers of the spaces the saved objects should be + added to or removed from. type: string type: array spacesToRemove: items: + description: >- + The identifiers of the spaces the saved objects should be + added to or removed from. type: string type: array required: @@ -21126,11 +21190,11 @@ paths: - spacesToAdd - spacesToRemove responses: {} - summary: '' - tags: [] + summary: Update saved objects in spaces + tags: + - spaces /api/spaces/space: get: - description: Get all spaces operationId: '%2Fapi%2Fspaces%2Fspace#0' parameters: - description: The version of the API to use @@ -21141,7 +21205,10 @@ paths: enum: - '2023-10-31' type: string - - in: query + - description: >- + Specifies which authorization checks are applied to the API call. + The default value is `any`. + in: query name: purpose required: false schema: @@ -21150,7 +21217,15 @@ paths: - copySavedObjectsIntoSpace - shareSavedObjectsIntoSpace type: string - - in: query + - description: >- + When enabled, the API returns any spaces that the user is authorized + to access in any capacity and each space will contain the purposes + for which the user is authorized. This can be useful to determine + which spaces a user can read but not take a specific action in. If + the security plugin is not enabled, this parameter has no effect, + since no authorization checks take place. This parameter cannot be + used in with the `purpose` parameter. + in: query name: include_authorized_purposes required: true schema: @@ -21169,12 +21244,13 @@ paths: x-oas-optional: true - type: boolean x-oas-optional: true - responses: {} - summary: '' + responses: + '200': + description: Indicates a successful call. + summary: Get all spaces tags: - spaces post: - description: Create a space operationId: '%2Fapi%2Fspaces%2Fspace#1' parameters: - description: The version of the API to use @@ -21202,22 +21278,45 @@ paths: _reserved: type: boolean color: + description: >- + The hexadecimal color code used in the space avatar. By + default, the color is automatically generated from the space + name. type: string description: + description: A description for the space. type: string disabledFeatures: default: [] items: + description: The list of features that are turned off in the space. type: string type: array id: + description: >- + The space ID that is part of the Kibana URL when inside the + space. Space IDs are limited to lowercase alphanumeric, + underscore, and hyphen characters (a-z, 0-9, _, and -). You + are cannot change the ID with the update operation. type: string imageUrl: + description: >- + The data-URL encoded image to display in the space avatar. + If specified, initials will not be displayed and the color + will be visible as the background color for transparent + images. For best results, your image should be 64x64. Images + will not be optimized by this API call, so care should be + taken when using custom images. type: string initials: + description: >- + One or two characters that are shown in the space avatar. By + default, the initials are automatically generated from the + space name. maxLength: 2 type: string name: + description: 'The display name for the space. ' minLength: 1 type: string solution: @@ -21230,13 +21329,17 @@ paths: required: - id - name - responses: {} - summary: '' + responses: + '200': + description: Indicates a successful call. + summary: Create a space tags: - spaces '/api/spaces/space/{id}': delete: - description: Delete a space + description: >- + When you delete a space, all saved objects that belong to the space are + automatically deleted, which is permanent and cannot be undone. operationId: '%2Fapi%2Fspaces%2Fspace%2F%7Bid%7D#2' parameters: - description: The version of the API to use @@ -21254,17 +21357,21 @@ paths: schema: example: 'true' type: string - - in: path + - description: The space identifier. + in: path name: id required: true schema: type: string - responses: {} - summary: '' + responses: + '204': + description: Indicates a successful call. + '404': + description: Indicates that the request failed. + summary: Delete a space tags: - spaces get: - description: Get a space operationId: '%2Fapi%2Fspaces%2Fspace%2F%7Bid%7D#0' parameters: - description: The version of the API to use @@ -21275,17 +21382,19 @@ paths: enum: - '2023-10-31' type: string - - in: path + - description: The space identifier. + in: path name: id required: true schema: type: string - responses: {} - summary: '' + responses: + '200': + description: Indicates a successful call. + summary: Get a space tags: - spaces put: - description: Update a space operationId: '%2Fapi%2Fspaces%2Fspace%2F%7Bid%7D#1' parameters: - description: The version of the API to use @@ -21303,7 +21412,10 @@ paths: schema: example: 'true' type: string - - in: path + - description: >- + The space identifier. You are unable to change the ID with the + update operation. + in: path name: id required: true schema: @@ -21318,22 +21430,45 @@ paths: _reserved: type: boolean color: + description: >- + The hexadecimal color code used in the space avatar. By + default, the color is automatically generated from the space + name. type: string description: + description: A description for the space. type: string disabledFeatures: default: [] items: + description: The list of features that are turned off in the space. type: string type: array id: + description: >- + The space ID that is part of the Kibana URL when inside the + space. Space IDs are limited to lowercase alphanumeric, + underscore, and hyphen characters (a-z, 0-9, _, and -). You + are cannot change the ID with the update operation. type: string imageUrl: + description: >- + The data-URL encoded image to display in the space avatar. + If specified, initials will not be displayed and the color + will be visible as the background color for transparent + images. For best results, your image should be 64x64. Images + will not be optimized by this API call, so care should be + taken when using custom images. type: string initials: + description: >- + One or two characters that are shown in the space avatar. By + default, the initials are automatically generated from the + space name. maxLength: 2 type: string name: + description: 'The display name for the space. ' minLength: 1 type: string solution: @@ -21346,8 +21481,10 @@ paths: required: - id - name - responses: {} - summary: '' + responses: + '200': + description: Indicates a successful call. + summary: Update a space tags: - spaces /api/status: diff --git a/oas_docs/output/kibana.yaml b/oas_docs/output/kibana.yaml index 647ad65e617e02..6c1ad62cf7a2b5 100644 --- a/oas_docs/output/kibana.yaml +++ b/oas_docs/output/kibana.yaml @@ -20841,7 +20841,13 @@ paths: - roles /api/spaces/_copy_saved_objects: post: - description: Copy saved objects to spaces + description: >- + It also allows you to automatically copy related objects, so when you + copy a dashboard, this can automatically copy over the associated + visualizations, data views, and saved searches, as required. You can + request to overwrite any objects that already exist in the target space + if they share an identifier or you can use the resolve copy saved + objects conflicts API to do this on a per-object basis. operationId: '%2Fapi%2Fspaces%2F_copy_saved_objects#0' parameters: - description: The version of the API to use @@ -20868,12 +20874,26 @@ paths: properties: compatibilityMode: default: false + description: >- + Apply various adjustments to the saved objects that are + being copied to maintain compatibility between different + Kibana versions. Use this option only if you encounter + issues with copied saved objects. This option cannot be used + with the `createNewCopies` option. type: boolean createNewCopies: default: true + description: >- + Create new copies of saved objects, regenerate each object + identifier, and reset the origin. When used, potential + conflict errors are avoided. This option cannot be used + with the `overwrite` and `compatibilityMode` options. type: boolean includeReferences: default: false + description: >- + When set to true, all saved objects related to the specified + saved objects will also be copied into the target spaces. type: boolean objects: items: @@ -20881,8 +20901,10 @@ paths: type: object properties: id: + description: The identifier of the saved object to copy. type: string type: + description: The type of the saved object to copy. type: string required: - type @@ -20890,20 +20912,29 @@ paths: type: array overwrite: default: false + description: >- + When set to true, all conflicts are automatically + overridden. When a saved object with a matching type and + identifier exists in the target space, that version is + replaced with the version from the source space. This option + cannot be used with the `createNewCopies` option. type: boolean spaces: items: + description: >- + The identifiers of the spaces where you want to copy the + specified objects. type: string type: array required: - spaces - objects responses: {} - summary: '' - tags: [] + summary: Copy saved objects between spaces + tags: + - spaces /api/spaces/_disable_legacy_url_aliases: post: - description: Disable legacy URL aliases operationId: '%2Fapi%2Fspaces%2F_disable_legacy_url_aliases#0' parameters: - description: The version of the API to use @@ -20934,10 +20965,15 @@ paths: type: object properties: sourceId: + description: >- + The alias source object identifier. This is the legacy + object identifier. type: string targetSpace: + description: The space where the alias target object exists. type: string targetType: + description: 'The type of alias target object. ' type: string required: - targetSpace @@ -20947,11 +20983,12 @@ paths: required: - aliases responses: {} - summary: '' - tags: [] + summary: Disable legacy URL aliases + tags: + - spaces /api/spaces/_get_shareable_references: post: - description: Get shareable references + description: Collect references and space contexts for saved objects. operationId: '%2Fapi%2Fspaces%2F_get_shareable_references#0' parameters: - description: The version of the API to use @@ -20992,11 +21029,14 @@ paths: required: - objects responses: {} - summary: '' - tags: [] + summary: Get shareable references + tags: + - spaces /api/spaces/_resolve_copy_saved_objects_errors: post: - description: Resolve conflicts copying saved objects + description: >- + Overwrite saved objects that are returned as errors from the copy saved + objects to space API. operationId: '%2Fapi%2Fspaces%2F_resolve_copy_saved_objects_errors#0' parameters: - description: The version of the API to use @@ -21050,17 +21090,33 @@ paths: type: object properties: createNewCopy: + description: >- + Creates new copies of the saved objects, regenerates + each object ID, and resets the origin. type: boolean destinationId: + description: >- + Specifies the destination identifier that the copied + object should have, if different from the current + identifier. type: string id: + description: The saved object identifier. type: string ignoreMissingReferences: + description: >- + When set to true, any missing references errors are + ignored. type: boolean overwrite: default: false + description: >- + When set to true, the saved object from the source + space overwrites the conflicting object in the + destination space. type: boolean type: + description: The saved object type. type: string required: - type @@ -21071,11 +21127,11 @@ paths: - retries - objects responses: {} - summary: '' + summary: Resolve conflicts copying saved objects tags: [] /api/spaces/_update_objects_spaces: post: - description: Update saved objects in spaces + description: Update one or more saved objects to add or remove them from some spaces. operationId: '%2Fapi%2Fspaces%2F_update_objects_spaces#0' parameters: - description: The version of the API to use @@ -21106,8 +21162,10 @@ paths: type: object properties: id: + description: The identifier of the saved object to update. type: string type: + description: The type of the saved object to update. type: string required: - type @@ -21115,10 +21173,16 @@ paths: type: array spacesToAdd: items: + description: >- + The identifiers of the spaces the saved objects should be + added to or removed from. type: string type: array spacesToRemove: items: + description: >- + The identifiers of the spaces the saved objects should be + added to or removed from. type: string type: array required: @@ -21126,11 +21190,11 @@ paths: - spacesToAdd - spacesToRemove responses: {} - summary: '' - tags: [] + summary: Update saved objects in spaces + tags: + - spaces /api/spaces/space: get: - description: Get all spaces operationId: '%2Fapi%2Fspaces%2Fspace#0' parameters: - description: The version of the API to use @@ -21141,7 +21205,10 @@ paths: enum: - '2023-10-31' type: string - - in: query + - description: >- + Specifies which authorization checks are applied to the API call. + The default value is `any`. + in: query name: purpose required: false schema: @@ -21150,7 +21217,15 @@ paths: - copySavedObjectsIntoSpace - shareSavedObjectsIntoSpace type: string - - in: query + - description: >- + When enabled, the API returns any spaces that the user is authorized + to access in any capacity and each space will contain the purposes + for which the user is authorized. This can be useful to determine + which spaces a user can read but not take a specific action in. If + the security plugin is not enabled, this parameter has no effect, + since no authorization checks take place. This parameter cannot be + used in with the `purpose` parameter. + in: query name: include_authorized_purposes required: true schema: @@ -21169,12 +21244,13 @@ paths: x-oas-optional: true - type: boolean x-oas-optional: true - responses: {} - summary: '' + responses: + '200': + description: Indicates a successful call. + summary: Get all spaces tags: - spaces post: - description: Create a space operationId: '%2Fapi%2Fspaces%2Fspace#1' parameters: - description: The version of the API to use @@ -21202,22 +21278,45 @@ paths: _reserved: type: boolean color: + description: >- + The hexadecimal color code used in the space avatar. By + default, the color is automatically generated from the space + name. type: string description: + description: A description for the space. type: string disabledFeatures: default: [] items: + description: The list of features that are turned off in the space. type: string type: array id: + description: >- + The space ID that is part of the Kibana URL when inside the + space. Space IDs are limited to lowercase alphanumeric, + underscore, and hyphen characters (a-z, 0-9, _, and -). You + are cannot change the ID with the update operation. type: string imageUrl: + description: >- + The data-URL encoded image to display in the space avatar. + If specified, initials will not be displayed and the color + will be visible as the background color for transparent + images. For best results, your image should be 64x64. Images + will not be optimized by this API call, so care should be + taken when using custom images. type: string initials: + description: >- + One or two characters that are shown in the space avatar. By + default, the initials are automatically generated from the + space name. maxLength: 2 type: string name: + description: 'The display name for the space. ' minLength: 1 type: string solution: @@ -21230,13 +21329,17 @@ paths: required: - id - name - responses: {} - summary: '' + responses: + '200': + description: Indicates a successful call. + summary: Create a space tags: - spaces '/api/spaces/space/{id}': delete: - description: Delete a space + description: >- + When you delete a space, all saved objects that belong to the space are + automatically deleted, which is permanent and cannot be undone. operationId: '%2Fapi%2Fspaces%2Fspace%2F%7Bid%7D#2' parameters: - description: The version of the API to use @@ -21254,17 +21357,21 @@ paths: schema: example: 'true' type: string - - in: path + - description: The space identifier. + in: path name: id required: true schema: type: string - responses: {} - summary: '' + responses: + '204': + description: Indicates a successful call. + '404': + description: Indicates that the request failed. + summary: Delete a space tags: - spaces get: - description: Get a space operationId: '%2Fapi%2Fspaces%2Fspace%2F%7Bid%7D#0' parameters: - description: The version of the API to use @@ -21275,17 +21382,19 @@ paths: enum: - '2023-10-31' type: string - - in: path + - description: The space identifier. + in: path name: id required: true schema: type: string - responses: {} - summary: '' + responses: + '200': + description: Indicates a successful call. + summary: Get a space tags: - spaces put: - description: Update a space operationId: '%2Fapi%2Fspaces%2Fspace%2F%7Bid%7D#1' parameters: - description: The version of the API to use @@ -21303,7 +21412,10 @@ paths: schema: example: 'true' type: string - - in: path + - description: >- + The space identifier. You are unable to change the ID with the + update operation. + in: path name: id required: true schema: @@ -21318,22 +21430,45 @@ paths: _reserved: type: boolean color: + description: >- + The hexadecimal color code used in the space avatar. By + default, the color is automatically generated from the space + name. type: string description: + description: A description for the space. type: string disabledFeatures: default: [] items: + description: The list of features that are turned off in the space. type: string type: array id: + description: >- + The space ID that is part of the Kibana URL when inside the + space. Space IDs are limited to lowercase alphanumeric, + underscore, and hyphen characters (a-z, 0-9, _, and -). You + are cannot change the ID with the update operation. type: string imageUrl: + description: >- + The data-URL encoded image to display in the space avatar. + If specified, initials will not be displayed and the color + will be visible as the background color for transparent + images. For best results, your image should be 64x64. Images + will not be optimized by this API call, so care should be + taken when using custom images. type: string initials: + description: >- + One or two characters that are shown in the space avatar. By + default, the initials are automatically generated from the + space name. maxLength: 2 type: string name: + description: 'The display name for the space. ' minLength: 1 type: string solution: @@ -21346,8 +21481,10 @@ paths: required: - id - name - responses: {} - summary: '' + responses: + '200': + description: Indicates a successful call. + summary: Update a space tags: - spaces /api/status: diff --git a/oas_docs/overlays/kibana.overlays.shared.yaml b/oas_docs/overlays/kibana.overlays.shared.yaml new file mode 100644 index 00000000000000..5f16b6dfa67192 --- /dev/null +++ b/oas_docs/overlays/kibana.overlays.shared.yaml @@ -0,0 +1,47 @@ +# overlays.yaml +overlay: 1.0.0 +info: + title: Overlays that are applicable to both serverless and non-serverless documentas + version: 0.0.1 +actions: +# Add some spaces API examples + - target: "$.paths['/api/spaces/space']['post']" + description: "Add example to create space API" + update: + requestBody: + content: + application/json; Elastic-Api-Version=2023-10-31: + examples: + createSpaceRequest: + $ref: "../examples/create_space_request.yaml" + - target: "$.paths['/api/spaces/space/{id}']['put']" + description: "Add example to update space API" + update: + requestBody: + content: + application/json; Elastic-Api-Version=2023-10-31: + examples: + updateSpaceRequest: + $ref: "../examples/update_space_request.yaml" + - target: "$.paths['/api/spaces/space/{id}']['get']" + description: "Add example to get space API" + update: + responses: + 200: + content: + application/json; Elastic-Api-Version=2023-10-31: + examples: + getSpaceResponseExample: + $ref: "../examples/get_space_response.yaml" + - target: "$.paths['/api/spaces/space']['get']" + description: "Add example to get all spaces API" + update: + responses: + 200: + content: + application/json; Elastic-Api-Version=2023-10-31: + examples: + getSpacesResponseExample1: + $ref: "../examples/get_spaces_response1.yaml" + getSpacesResponseExample2: + $ref: "../examples/get_spaces_response2.yaml" diff --git a/oas_docs/overlays/kibana.overlays.yaml b/oas_docs/overlays/kibana.overlays.yaml index c4747d7d13a0ac..4a21c029ef80aa 100644 --- a/oas_docs/overlays/kibana.overlays.yaml +++ b/oas_docs/overlays/kibana.overlays.yaml @@ -4,7 +4,7 @@ info: title: Overlays for the Kibana API document version: 0.0.1 actions: - # Add an introduction to spaces +# Add an introduction to spaces - target: '$' description: Add an extra page about spaces update: @@ -24,7 +24,7 @@ actions: If you use the Kibana console to send API requests, it automatically adds the appropriate space identifier. To learn more, check out [Spaces](https://www.elastic.co/guide/en/kibana/master/xpack-spaces.html). - # Add some tag descriptions and displayNames +# Add some tag descriptions and displayNames - target: '$.tags[?(@.name=="alerting")]' description: Change tag description and displayName update: @@ -91,7 +91,77 @@ actions: x-displayName: "System" description: > Get information about the system status, resource usage, and installed plugins. - # Remove extra tags from operations +# Remove extra tags from operations - target: "$.paths[*][*].tags[1:]" description: Remove all but first tag from operations - remove: true \ No newline at end of file + remove: true +# Examples that are not applicable to serverless + - target: "$.paths['/api/spaces/_copy_saved_objects']['post']" + description: "Add example to copy saved objects to space API" + update: + requestBody: + content: + application/json; Elastic-Api-Version=2023-10-31: + examples: + copySavedObjectsRequestExample1: + $ref: "../examples/copy_saved_objects_request1.yaml" + copySavedObjectsRequestExample2: + $ref: "../examples/copy_saved_objects_request2.yaml" + responses: + 200: + content: + application/json; Elastic-Api-Version=2023-10-31: + examples: + copySavedObjectsResponseExample1: + $ref: "../examples/copy_saved_objects_response1.yaml" + copySavedObjectsResponseExample2: + $ref: "../examples/copy_saved_objects_response2.yaml" + copySavedObjectsResponseExample3: + $ref: "../examples/copy_saved_objects_response3.yaml" + copySavedObjectsResponseExample4: + $ref: "../examples/copy_saved_objects_response4.yaml" + - target: "$.paths['/api/spaces/_resolve_copy_saved_objects_errors']['post']" + description: "Add example to resolve copy saved objects to space conflicts API" + update: + requestBody: + content: + application/json; Elastic-Api-Version=2023-10-31: + examples: + resolveCopySavedObjectsRequestExample1: + $ref: "../examples/resolve_copy_saved_objects_request1.yaml" + resolveCopySavedObjectsRequestExample2: + $ref: "../examples/resolve_copy_saved_objects_request2.yaml" + responses: + 200: + content: + application/json; Elastic-Api-Version=2023-10-31: + examples: + resolveCopySavedObjectsResponseExample1: + $ref: "../examples/copy_saved_objects_response1.yaml" + resolveCopySavedObjectsResponseExample2: + $ref: "../examples/copy_saved_objects_response2.yaml" + - target: "$.paths['/api/spaces/_disable_legacy_url_aliases']['post']" + description: "Add example to disable legacy URL aliases API" + update: + requestBody: + content: + application/json; Elastic-Api-Version=2023-10-31: + examples: + disableLegacyURLRequestExample1: + $ref: "../examples/disable_legacy_url_request1.yaml" + - target: "$.paths['/api/spaces/_update_objects_spaces']['post']" + description: "Add example to update saved object spaces API" + update: + requestBody: + content: + application/json; Elastic-Api-Version=2023-10-31: + examples: + updateObjectSpacesRequestExample1: + $ref: "../examples/update_saved_objects_spaces_request1.yaml" + responses: + 200: + content: + application/json; Elastic-Api-Version=2023-10-31: + examples: + updateObjectSpacesResponseExample1: + $ref: "../examples/update_saved_objects_spaces_response1.yaml" \ No newline at end of file diff --git a/x-pack/plugins/spaces/server/lib/space_schema.ts b/x-pack/plugins/spaces/server/lib/space_schema.ts index 852e1a98096c47..b5206e534129e5 100644 --- a/x-pack/plugins/spaces/server/lib/space_schema.ts +++ b/x-pack/plugins/spaces/server/lib/space_schema.ts @@ -18,10 +18,29 @@ const spaceSchema = schema.object({ return `must be lower case, a-z, 0-9, '_', and '-' are allowed`; } }, + meta: { + description: + 'The space ID that is part of the Kibana URL when inside the space. Space IDs are limited to lowercase alphanumeric, underscore, and hyphen characters (a-z, 0-9, _, and -). You are cannot change the ID with the update operation.', + }, + }), + name: schema.string({ + minLength: 1, + meta: { description: 'The display name for the space. ' }, }), - name: schema.string({ minLength: 1 }), - description: schema.maybe(schema.string()), - initials: schema.maybe(schema.string({ maxLength: MAX_SPACE_INITIALS })), + description: schema.maybe( + schema.string({ + meta: { description: 'A description for the space.' }, + }) + ), + initials: schema.maybe( + schema.string({ + maxLength: MAX_SPACE_INITIALS, + meta: { + description: + 'One or two characters that are shown in the space avatar. By default, the initials are automatically generated from the space name.', + }, + }) + ), color: schema.maybe( schema.string({ validate: (value) => { @@ -29,9 +48,20 @@ const spaceSchema = schema.object({ return `must be a 6 digit hex color, starting with a #`; } }, + meta: { + description: + 'The hexadecimal color code used in the space avatar. By default, the color is automatically generated from the space name.', + }, }) ), - disabledFeatures: schema.arrayOf(schema.string(), { defaultValue: [] }), + disabledFeatures: schema.arrayOf( + schema.string({ + meta: { + description: 'The list of features that are turned off in the space.', + }, + }), + { defaultValue: [] } + ), _reserved: schema.maybe(schema.boolean()), imageUrl: schema.maybe( schema.string({ @@ -40,6 +70,10 @@ const spaceSchema = schema.object({ return `must start with 'data:image'`; } }, + meta: { + description: + 'The data-URL encoded image to display in the space avatar. If specified, initials will not be displayed and the color will be visible as the background color for transparent images. For best results, your image should be 64x64. Images will not be optimized by this API call, so care should be taken when using custom images.', + }, }) ), }); diff --git a/x-pack/plugins/spaces/server/routes/api/external/copy_to_space.ts b/x-pack/plugins/spaces/server/routes/api/external/copy_to_space.ts index f1f1f22b55e32f..b0758f5645cc18 100644 --- a/x-pack/plugins/spaces/server/routes/api/external/copy_to_space.ts +++ b/x-pack/plugins/spaces/server/routes/api/external/copy_to_space.ts @@ -39,8 +39,10 @@ export function initCopyToSpacesApi(deps: ExternalRouteDeps) { path: '/api/spaces/_copy_saved_objects', options: { access: isServerless ? 'internal' : 'public', - tags: ['access:copySavedObjectsToSpaces'], - description: `Copy saved objects to spaces`, + tags: ['access:copySavedObjectsToSpaces', 'oas-tag:spaces'], + summary: `Copy saved objects between spaces`, + description: + 'It also allows you to automatically copy related objects, so when you copy a dashboard, this can automatically copy over the associated visualizations, data views, and saved searches, as required. You can request to overwrite any objects that already exist in the target space if they share an identifier or you can use the resolve copy saved objects conflicts API to do this on a per-object basis.', }, validate: { body: schema.object( @@ -52,6 +54,10 @@ export function initCopyToSpacesApi(deps: ExternalRouteDeps) { return `lower case, a-z, 0-9, "_", and "-" are allowed`; } }, + meta: { + description: + 'The identifiers of the spaces where you want to copy the specified objects.', + }, }), { validate: (spaceIds) => { @@ -63,8 +69,12 @@ export function initCopyToSpacesApi(deps: ExternalRouteDeps) { ), objects: schema.arrayOf( schema.object({ - type: schema.string(), - id: schema.string(), + type: schema.string({ + meta: { description: 'The type of the saved object to copy.' }, + }), + id: schema.string({ + meta: { description: 'The identifier of the saved object to copy.' }, + }), }), { validate: (objects) => { @@ -74,17 +84,40 @@ export function initCopyToSpacesApi(deps: ExternalRouteDeps) { }, } ), - includeReferences: schema.boolean({ defaultValue: false }), - overwrite: schema.boolean({ defaultValue: false }), - createNewCopies: schema.boolean({ defaultValue: true }), - compatibilityMode: schema.boolean({ defaultValue: false }), + includeReferences: schema.boolean({ + defaultValue: false, + meta: { + description: + 'When set to true, all saved objects related to the specified saved objects will also be copied into the target spaces.', + }, + }), + overwrite: schema.boolean({ + defaultValue: false, + meta: { + description: + 'When set to true, all conflicts are automatically overridden. When a saved object with a matching type and identifier exists in the target space, that version is replaced with the version from the source space. This option cannot be used with the `createNewCopies` option.', + }, + }), + createNewCopies: schema.boolean({ + defaultValue: true, + meta: { + description: + 'Create new copies of saved objects, regenerate each object identifier, and reset the origin. When used, potential conflict errors are avoided. This option cannot be used with the `overwrite` and `compatibilityMode` options.', + }, + }), + compatibilityMode: schema.boolean({ + defaultValue: false, + meta: { + description: + 'Apply various adjustments to the saved objects that are being copied to maintain compatibility between different Kibana versions. Use this option only if you encounter issues with copied saved objects. This option cannot be used with the `createNewCopies` option.', + }, + }), }, { validate: (object) => { if (object.overwrite && object.createNewCopies) { return 'cannot use [overwrite] with [createNewCopies]'; } - if (object.compatibilityMode && object.createNewCopies) { return 'cannot use [compatibilityMode] with [createNewCopies]'; } @@ -158,13 +191,19 @@ export function initCopyToSpacesApi(deps: ExternalRouteDeps) { options: { access: isServerless ? 'internal' : 'public', tags: ['access:copySavedObjectsToSpaces'], - description: `Resolve conflicts copying saved objects`, + summary: `Resolve conflicts copying saved objects`, + description: + 'Overwrite saved objects that are returned as errors from the copy saved objects to space API.', }, validate: { body: schema.object( { retries: schema.recordOf( schema.string({ + meta: { + description: + 'The retry operations to attempt, which can specify how to resolve different types of errors. Object keys represent the target space identifiers.', + }, validate: (spaceId) => { if (!SPACE_ID_REGEX.test(spaceId)) { return `Invalid space id: ${spaceId}`; @@ -173,12 +212,38 @@ export function initCopyToSpacesApi(deps: ExternalRouteDeps) { }), schema.arrayOf( schema.object({ - type: schema.string(), - id: schema.string(), - overwrite: schema.boolean({ defaultValue: false }), - destinationId: schema.maybe(schema.string()), - createNewCopy: schema.maybe(schema.boolean()), - ignoreMissingReferences: schema.maybe(schema.boolean()), + type: schema.string({ meta: { description: 'The saved object type.' } }), + id: schema.string({ meta: { description: 'The saved object identifier.' } }), + overwrite: schema.boolean({ + defaultValue: false, + meta: { + description: + 'When set to true, the saved object from the source space overwrites the conflicting object in the destination space.', + }, + }), + destinationId: schema.maybe( + schema.string({ + meta: { + description: + 'Specifies the destination identifier that the copied object should have, if different from the current identifier.', + }, + }) + ), + createNewCopy: schema.maybe( + schema.boolean({ + meta: { + description: + 'Creates new copies of the saved objects, regenerates each object ID, and resets the origin.', + }, + }) + ), + ignoreMissingReferences: schema.maybe( + schema.boolean({ + meta: { + description: 'When set to true, any missing references errors are ignored.', + }, + }) + ), }) ) ), diff --git a/x-pack/plugins/spaces/server/routes/api/external/delete.ts b/x-pack/plugins/spaces/server/routes/api/external/delete.ts index 515f8811e5dcf8..06bef75774aa0f 100644 --- a/x-pack/plugins/spaces/server/routes/api/external/delete.ts +++ b/x-pack/plugins/spaces/server/routes/api/external/delete.ts @@ -22,7 +22,8 @@ export function initDeleteSpacesApi(deps: ExternalRouteDeps) { .delete({ path: '/api/spaces/space/{id}', access: 'public', - description: `Delete a space`, + summary: `Delete a space`, + description: `When you delete a space, all saved objects that belong to the space are automatically deleted, which is permanent and cannot be undone.`, options: { tags: ['oas-tag:spaces'], }, @@ -33,9 +34,19 @@ export function initDeleteSpacesApi(deps: ExternalRouteDeps) { validate: { request: { params: schema.object({ - id: schema.string(), + id: schema.string({ + meta: { description: 'The space identifier.' }, + }), }), }, + response: { + 204: { + description: 'Indicates a successful call.', + }, + 404: { + description: 'Indicates that the request failed.', + }, + }, }, }, createLicensedRouteHandler(async (context, request, response) => { diff --git a/x-pack/plugins/spaces/server/routes/api/external/disable_legacy_url_aliases.ts b/x-pack/plugins/spaces/server/routes/api/external/disable_legacy_url_aliases.ts index 6b3c70eb64ffa8..a1610bbfed9754 100644 --- a/x-pack/plugins/spaces/server/routes/api/external/disable_legacy_url_aliases.ts +++ b/x-pack/plugins/spaces/server/routes/api/external/disable_legacy_url_aliases.ts @@ -20,15 +20,25 @@ export function initDisableLegacyUrlAliasesApi(deps: ExternalRouteDeps) { path: '/api/spaces/_disable_legacy_url_aliases', options: { access: isServerless ? 'internal' : 'public', - description: `Disable legacy URL aliases`, + summary: 'Disable legacy URL aliases', + tags: ['oas-tag:spaces'], }, validate: { body: schema.object({ aliases: schema.arrayOf( schema.object({ - targetSpace: schema.string(), - targetType: schema.string(), - sourceId: schema.string(), + targetSpace: schema.string({ + meta: { description: 'The space where the alias target object exists.' }, + }), + targetType: schema.string({ + meta: { description: 'The type of alias target object. ' }, + }), + sourceId: schema.string({ + meta: { + description: + 'The alias source object identifier. This is the legacy object identifier.', + }, + }), }) ), }), diff --git a/x-pack/plugins/spaces/server/routes/api/external/get.ts b/x-pack/plugins/spaces/server/routes/api/external/get.ts index 8d4e3c0c359ef9..b1ab2dc5757747 100644 --- a/x-pack/plugins/spaces/server/routes/api/external/get.ts +++ b/x-pack/plugins/spaces/server/routes/api/external/get.ts @@ -20,7 +20,7 @@ export function initGetSpaceApi(deps: ExternalRouteDeps) { .get({ path: '/api/spaces/space/{id}', access: 'public', - description: `Get a space`, + summary: `Get a space`, options: { tags: ['oas-tag:spaces'], }, @@ -31,9 +31,14 @@ export function initGetSpaceApi(deps: ExternalRouteDeps) { validate: { request: { params: schema.object({ - id: schema.string(), + id: schema.string({ meta: { description: 'The space identifier.' } }), }), }, + response: { + 200: { + description: 'Indicates a successful call.', + }, + }, }, }, createLicensedRouteHandler(async (context, request, response) => { diff --git a/x-pack/plugins/spaces/server/routes/api/external/get_all.ts b/x-pack/plugins/spaces/server/routes/api/external/get_all.ts index baa47ca6956dc6..746735bb3736e4 100644 --- a/x-pack/plugins/spaces/server/routes/api/external/get_all.ts +++ b/x-pack/plugins/spaces/server/routes/api/external/get_all.ts @@ -19,7 +19,7 @@ export function initGetAllSpacesApi(deps: ExternalRouteDeps) { .get({ path: '/api/spaces/space', access: 'public', - description: `Get all spaces`, + summary: `Get all spaces`, options: { tags: ['oas-tag:spaces'], }, @@ -31,20 +31,39 @@ export function initGetAllSpacesApi(deps: ExternalRouteDeps) { request: { query: schema.object({ purpose: schema.maybe( - schema.oneOf([ - schema.literal('any'), - schema.literal('copySavedObjectsIntoSpace'), - schema.literal('shareSavedObjectsIntoSpace'), - ]) + schema.oneOf( + [ + schema.literal('any'), + schema.literal('copySavedObjectsIntoSpace'), + schema.literal('shareSavedObjectsIntoSpace'), + ], + { + meta: { + description: + 'Specifies which authorization checks are applied to the API call. The default value is `any`.', + }, + } + ) ), include_authorized_purposes: schema.conditional( schema.siblingRef('purpose'), schema.string(), schema.maybe(schema.literal(false)), - schema.maybe(schema.boolean()) + schema.maybe(schema.boolean()), + { + meta: { + description: + 'When enabled, the API returns any spaces that the user is authorized to access in any capacity and each space will contain the purposes for which the user is authorized. This can be useful to determine which spaces a user can read but not take a specific action in. If the security plugin is not enabled, this parameter has no effect, since no authorization checks take place. This parameter cannot be used in with the `purpose` parameter.', + }, + } ), }), }, + response: { + 200: { + description: 'Indicates a successful call.', + }, + }, }, }, createLicensedRouteHandler(async (context, request, response) => { diff --git a/x-pack/plugins/spaces/server/routes/api/external/get_shareable_references.ts b/x-pack/plugins/spaces/server/routes/api/external/get_shareable_references.ts index 93a210cd82b3e7..f49070be66fe2d 100644 --- a/x-pack/plugins/spaces/server/routes/api/external/get_shareable_references.ts +++ b/x-pack/plugins/spaces/server/routes/api/external/get_shareable_references.ts @@ -19,7 +19,9 @@ export function initGetShareableReferencesApi(deps: ExternalRouteDeps) { path: '/api/spaces/_get_shareable_references', options: { access: isServerless ? 'internal' : 'public', - description: `Get shareable references`, + summary: `Get shareable references`, + tags: ['oas-tag:spaces'], + description: 'Collect references and space contexts for saved objects.', }, validate: { body: schema.object({ diff --git a/x-pack/plugins/spaces/server/routes/api/external/post.ts b/x-pack/plugins/spaces/server/routes/api/external/post.ts index c47ea4ad5f9bf8..de1ec53aaee447 100644 --- a/x-pack/plugins/spaces/server/routes/api/external/post.ts +++ b/x-pack/plugins/spaces/server/routes/api/external/post.ts @@ -22,7 +22,7 @@ export function initPostSpacesApi(deps: ExternalRouteDeps) { .post({ path: '/api/spaces/space', access: 'public', - description: `Create a space`, + summary: `Create a space`, options: { tags: ['oas-tag:spaces'], }, @@ -34,6 +34,11 @@ export function initPostSpacesApi(deps: ExternalRouteDeps) { request: { body: getSpaceSchema(isServerless), }, + response: { + 200: { + description: 'Indicates a successful call.', + }, + }, }, }, createLicensedRouteHandler(async (context, request, response) => { diff --git a/x-pack/plugins/spaces/server/routes/api/external/put.ts b/x-pack/plugins/spaces/server/routes/api/external/put.ts index 10374dc94f6000..740e81bac446ef 100644 --- a/x-pack/plugins/spaces/server/routes/api/external/put.ts +++ b/x-pack/plugins/spaces/server/routes/api/external/put.ts @@ -21,7 +21,7 @@ export function initPutSpacesApi(deps: ExternalRouteDeps) { .put({ path: '/api/spaces/space/{id}', access: 'public', - description: `Update a space`, + summary: `Update a space`, options: { tags: ['oas-tag:spaces'], }, @@ -32,10 +32,20 @@ export function initPutSpacesApi(deps: ExternalRouteDeps) { validate: { request: { params: schema.object({ - id: schema.string(), + id: schema.string({ + meta: { + description: + 'The space identifier. You are unable to change the ID with the update operation.', + }, + }), }), body: getSpaceSchema(isServerless), }, + response: { + 200: { + description: 'Indicates a successful call.', + }, + }, }, }, createLicensedRouteHandler(async (context, request, response) => { diff --git a/x-pack/plugins/spaces/server/routes/api/external/update_objects_spaces.ts b/x-pack/plugins/spaces/server/routes/api/external/update_objects_spaces.ts index 68b89d0934cf12..9fb2a8626a8416 100644 --- a/x-pack/plugins/spaces/server/routes/api/external/update_objects_spaces.ts +++ b/x-pack/plugins/spaces/server/routes/api/external/update_objects_spaces.ts @@ -18,6 +18,10 @@ export function initUpdateObjectsSpacesApi(deps: ExternalRouteDeps) { const spacesSchema = schema.arrayOf( schema.string({ + meta: { + description: + 'The identifiers of the spaces the saved objects should be added to or removed from.', + }, validate: (value) => { if (value !== ALL_SPACES_ID && !SPACE_ID_REGEX.test(value)) { return `lower case, a-z, 0-9, "_", and "-" are allowed, OR "*"`; @@ -38,11 +42,22 @@ export function initUpdateObjectsSpacesApi(deps: ExternalRouteDeps) { path: '/api/spaces/_update_objects_spaces', options: { access: isServerless ? 'internal' : 'public', - description: `Update saved objects in spaces`, + summary: `Update saved objects in spaces`, + tags: ['oas-tag:spaces'], + description: 'Update one or more saved objects to add or remove them from some spaces.', }, validate: { body: schema.object({ - objects: schema.arrayOf(schema.object({ type: schema.string(), id: schema.string() })), + objects: schema.arrayOf( + schema.object({ + type: schema.string({ + meta: { description: 'The type of the saved object to update.' }, + }), + id: schema.string({ + meta: { description: 'The identifier of the saved object to update.' }, + }), + }) + ), spacesToAdd: spacesSchema, spacesToRemove: spacesSchema, }),