[Spaces] - Experimental Public spaces api (#22501)

[skip ci]

docs/api/spaces-management/delete.asciidoc

@@ -0,0 +1,25 @@
+[[spaces-api-delete]]
+=== Delete space
+
+experimental[This API is *experimental* and may be changed or removed completely in a future release. The underlying Spaces concepts are stable, but the APIs for managing Spaces are currently experimental.]
+
+[WARNING]
+==================================================
+Deleting a space will automatically delete all saved objects that belong to that space. This operation cannot be undone!
+==================================================
+
+==== Request
+
+To delete a space, submit a DELETE request to the `/api/spaces/space/<space_id>`
+endpoint:
+
+[source,js]
+--------------------------------------------------
+DELETE /api/spaces/space/marketing
+--------------------------------------------------
+// KIBANA
+
+==== Response
+
+If the space is successfully deleted, the response code is `204`; otherwise, the response
+code is 404.

docs/api/spaces-management/get.asciidoc

@@ -0,0 +1,77 @@
+[[spaces-api-get]]
+=== Get Space
+
+experimental[This API is *experimental* and may be changed or removed completely in a future release. The underlying Spaces concepts are stable, but the APIs for managing Spaces are currently experimental.]
+
+Retrieves all {kib} spaces, or a specific space.
+
+==== Get all {kib} spaces
+
+===== Request
+
+To retrieve all spaces, issue a GET request to the
+/api/spaces/space endpoint.
+
+[source,js]
+--------------------------------------------------
+GET /api/spaces/space
+--------------------------------------------------
+// KIBANA
+
+===== Response
+
+A successful call returns a response code of `200` and a response body containing a JSON 
+representation of the spaces.
+
+[source,js]
+--------------------------------------------------
+[
+  {
+    "id": "default",
+    "name": "Default",
+    "description" : "This is the Default Space",
+    "_reserved": true
+  },
+  {
+    "id": "marketing",
+    "name": "Marketing",
+    "description" : "This is the Marketing Space",
+    "color": "#aabbcc",
+    "initials": "MK"
+  },
+  {
+    "id": "sales",
+    "name": "Sales",
+    "initials": "MK"
+  },
+]
+--------------------------------------------------
+
+==== Get a specific space
+
+===== Request
+
+To retrieve a specific space, issue a GET request to
+the `/api/spaces/space/<space_id>` endpoint:
+
+[source,js]
+--------------------------------------------------
+GET /api/spaces/space/marketing
+--------------------------------------------------
+// KIBANA
+
+===== Response
+
+A successful call returns a response code of `200` and a response body containing a JSON 
+representation of the space.
+
+[source,js]
+--------------------------------------------------
+{
+  "id": "marketing",
+  "name": "Marketing",
+  "description" : "This is the Marketing Space",
+  "color": "#aabbcc",
+  "initials": "MK"
+}
+--------------------------------------------------

docs/api/spaces-management/post.asciidoc

@@ -0,0 +1,50 @@
+[[spaces-api-post]]
+=== Create Space
+
+experimental[This API is *experimental* and may be changed or removed completely in a future release. The underlying Spaces concepts are stable, but the APIs for managing Spaces are currently experimental.]
+
+Creates a new {kib} space. To update an existing space, use the PUT command.
+
+==== Request
+
+To create a space, issue a POST request to the 
+`/api/spaces/space` endpoint.
+
+[source,js]
+--------------------------------------------------
+PUT /api/spaces/space
+--------------------------------------------------
+
+==== Request Body
+
+The following parameters can be specified in the body of a POST request to create a space:
+
+`id`:: (string) Required identifier for the space. This identifier becomes part of Kibana's URL when inside the space. This cannot be changed by the update operation.
+
+`name`:: (string) Required display name for the space.
+
+`description`:: (string) Optional description for the space.
+
+`initials`:: (string) Optionally specify the initials shown in the Space Avatar for this space. By default, the initials will be automatically generated from the space name.
+If specified, initials should be either 1 or 2 characters.
+
+`color`:: (string) Optioanlly specify the hex color code used in the Space Avatar for this space. By default, the color will be automatically generated from the space name.
+
+===== Example
+
+[source,js]
+--------------------------------------------------
+POST /api/spaces/space
+{
+  "id": "marketing",
+  "name": "Marketing",
+  "description" : "This is the Marketing Space",
+  "color": "#aabbcc",
+  "initials": "MK"
+}
+--------------------------------------------------
+// KIBANA
+
+==== Response
+
+A successful call returns a response code of `200` with the created Space.

docs/api/spaces-management/put.asciidoc

@@ -0,0 +1,50 @@
+[[spaces-api-put]]
+=== Update Space
+
+experimental[This API is *experimental* and may be changed or removed completely in a future release. The underlying Spaces concepts are stable, but the APIs for managing Spaces are currently experimental.]
+
+Updates an existing {kib} space. To create a new space, use the POST command.
+
+==== Request
+
+To update a space, issue a PUT request to the 
+`/api/spaces/space/<space_id>` endpoint.
+
+[source,js]
+--------------------------------------------------
+PUT /api/spaces/space/<space_id>
+--------------------------------------------------
+
+==== Request Body
+
+The following parameters can be specified in the body of a PUT request to update a space:
+
+`id`:: (string) Required identifier for the space. This identifier becomes part of Kibana's URL when inside the space. This cannot be changed by the update operation.
+
+`name`:: (string) Required display name for the space.
+
+`description`:: (string) Optional description for the space.
+
+`initials`:: (string) Optionally specify the initials shown in the Space Avatar for this space. By default, the initials will be automatically generated from the space name.
+If specified, initials should be either 1 or 2 characters.
+
+`color`:: (string) Optioanlly specify the hex color code used in the Space Avatar for this space. By default, the color will be automatically generated from the space name.
+
+===== Example
+
+[source,js]
+--------------------------------------------------
+PUT /api/spaces/space/marketing
+{
+  "id": "marketing",
+  "name": "Marketing",
+  "description" : "This is the Marketing Space",
+  "color": "#aabbcc",
+  "initials": "MK"
+}
+--------------------------------------------------
+// KIBANA
+
+==== Response
+
+A successful call returns a response code of `200` with the updated Space.

docs/api/spaces.asciidoc

@@ -0,0 +1,17 @@
+[role="xpack"]
+[[spaces-api]]
+== Kibana Spaces API
+
+experimental[This API is *experimental* and may be changed or removed completely in a future release. The underlying Spaces concepts are stable, but the APIs for managing Spaces are currently experimental.]
+
+The spaces API allows people to manage their spaces within {kib}.
+
+* <<spaces-api-put>>
+* <<spaces-api-post>>
+* <<spaces-api-get>>
+* <<spaces-api-delete>>
+
+include::spaces-management/put.asciidoc[]
+include::spaces-management/post.asciidoc[]
+include::spaces-management/get.asciidoc[]
+include::spaces-management/delete.asciidoc[]

x-pack/plugins/spaces/common/is_reserved_space.ts

@@ -13,6 +13,6 @@ import { Space } from './model/space';
  * @param space the space
  * @returns boolean
  */
-export function isReservedSpace(space: Space): boolean {
+export function isReservedSpace(space: Space | null): boolean {
   return get(space, '_reserved', false);
 }

x-pack/plugins/spaces/index.js

@@ -7,7 +7,8 @@
 import { resolve } from 'path';
 import { validateConfig } from './server/lib/validate_config';
 import { checkLicense } from './server/lib/check_license';
-import { initSpacesApi } from './server/routes/api/v1/spaces';
+import { initPublicSpacesApi } from './server/routes/api/public';
+import { initPrivateApis } from './server/routes/api/v1';
 import { initSpacesRequestInterceptors } from './server/lib/space_request_interceptors';
 import { createDefaultSpace } from './server/lib/create_default_space';
 import { createSpacesService } from './server/lib/create_spaces_service';
@@ -93,7 +94,8 @@ export const spaces = (kibana) => new kibana.Plugin({
       spacesSavedObjectsClientWrapperFactory(spacesService)
     );
 
-    initSpacesApi(server);
+    initPrivateApis(server);
+    initPublicSpacesApi(server);
 
     initSpacesRequestInterceptors(server);
 

x-pack/plugins/spaces/public/lib/spaces_manager.ts

@@ -16,12 +16,12 @@ export class SpacesManager extends EventEmitter {
   constructor(httpAgent: any, chrome: any) {
     super();
     this.httpAgent = httpAgent;
-    this.baseUrl = chrome.addBasePath(`/api/spaces/v1`);
+    this.baseUrl = chrome.addBasePath(`/api/spaces`);
   }
 
   public async getSpaces(): Promise<Space[]> {
     return await this.httpAgent
-      .get(`${this.baseUrl}/spaces`)
+      .get(`${this.baseUrl}/space`)
       .then((response: IHttpResponse<Space[]>) => response.data);
   }
 
@@ -43,7 +43,7 @@ export class SpacesManager extends EventEmitter {
 
   public async changeSelectedSpace(space: Space) {
     return await this.httpAgent
-      .post(`${this.baseUrl}/space/${space.id}/select`)
+      .post(`${this.baseUrl}/v1/space/${space.id}/select`)
       .then((response: IHttpResponse<any>) => {
         if (response.data && response.data.location) {
           window.location = response.data.location;

x-pack/plugins/spaces/server/lib/errors.js → x-pack/plugins/spaces/server/lib/errors.ts

@@ -3,9 +3,9 @@
  * or more contributor license agreements. Licensed under the Elastic License;
  * you may not use this file except in compliance with the Elastic License.
  */
-
+// @ts-ignore
 import { wrap as wrapBoom } from 'boom';
 
-export function wrapError(error) {
+export function wrapError(error: any) {
   return wrapBoom(error, error.status);
 }

x-pack/plugins/spaces/server/lib/route_pre_check_license.js → x-pack/plugins/spaces/server/lib/route_pre_check_license.ts

@@ -4,12 +4,12 @@
  * you may not use this file except in compliance with the Elastic License.
  */
 
-const Boom = require('boom');
+import Boom from 'boom';
 
-export function routePreCheckLicense(server) {
+export function routePreCheckLicense(server: any) {
   const xpackMainPlugin = server.plugins.xpack_main;
   const pluginId = 'spaces';
-  return function forbidApiAccess(request, reply) {
+  return function forbidApiAccess(request: any, reply: any) {
     const licenseCheckResults = xpackMainPlugin.info.feature(pluginId).getLicenseCheckResults();
     if (!licenseCheckResults.showSpaces) {
       reply(Boom.forbidden(licenseCheckResults.linksMessage));

x-pack/plugins/spaces/server/lib/space_schema.js → x-pack/plugins/spaces/server/lib/space_schema.ts

@@ -13,5 +13,5 @@ export const spaceSchema = Joi.object({
   description: Joi.string(),
   initials: Joi.string().max(MAX_SPACE_INITIALS),
   color: Joi.string().regex(/^#[a-z0-9]{6}$/, `6 digit hex color, starting with a #`),
-  _reserved: Joi.boolean()
+  _reserved: Joi.boolean(),
 }).default();

x-pack/plugins/spaces/server/lib/spaces_url_parser.js → x-pack/plugins/spaces/server/lib/spaces_url_parser.ts

@@ -5,8 +5,11 @@
  */
 import { DEFAULT_SPACE_ID } from '../../common/constants';
 
-export function getSpaceIdFromPath(requestBasePath = '/', serverBasePath = '/') {
-  let pathToCheck = requestBasePath;
+export function getSpaceIdFromPath(
+  requestBasePath: string = '/',
+  serverBasePath: string = '/'
+): string {
+  let pathToCheck: string = requestBasePath;
 
   if (serverBasePath && serverBasePath !== '/' && requestBasePath.startsWith(serverBasePath)) {
     pathToCheck = requestBasePath.substr(serverBasePath.length);
@@ -28,7 +31,11 @@ export function getSpaceIdFromPath(requestBasePath = '/', serverBasePath = '/')
   return spaceId;
 }
 
-export function addSpaceIdToPath(basePath = '/', spaceId = '', requestedPath = '') {
+export function addSpaceIdToPath(
+  basePath: string = '/',
+  spaceId: string = '',
+  requestedPath: string = ''
+): string {
   if (requestedPath && !requestedPath.startsWith('/')) {
     throw new Error(`path must start with a /`);
   }

x-pack/plugins/spaces/server/routes/api/__fixtures__/create_spaces.ts

@@ -0,0 +1,29 @@
+/*
+ * Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one
+ * or more contributor license agreements. Licensed under the Elastic License;
+ * you may not use this file except in compliance with the Elastic License.
+ */
+
+export function createSpaces() {
+  return [
+    {
+      id: 'a-space',
+      attributes: {
+        name: 'a space',
+      },
+    },
+    {
+      id: 'b-space',
+      attributes: {
+        name: 'b space',
+      },
+    },
+    {
+      id: 'default',
+      attributes: {
+        name: 'Default Space',
+        _reserved: true,
+      },
+    },
+  ];
+}