Table of Contents

Introduction

Kong Enterprise’s Workspaces feature is configurable through Kong’s Admin API.

Workspace Object

The Workspace object describes the workspece entity, which has an ID and a name.

Add Workspace

Endpoint

/workspaces/

Request Body

Attribute Description
name The Workspace name.

Response

HTTP 201 Created
{
  "name": "teamA",
  "created_at": 1528838706000,
  "id": "5396b1b3-ff46-4cb2-8065-5a4b35be342d"
}

List Workspaces

Endpoint

/workspaces/

Response

HTTP 200 OK
{
  "total": 1,
  "data": [
    {
      "created_at": 1528806517000,
      "id": "9f8008c5-722f-4637-8080-5ee96b535c33",
      "name": "default"
    }
  ]
}

Update or Create a Workspace

Endpoint

/workspaces/

Request Body

Attribute Description
name The Workspace name.

The behavior of PUT endpoints is the following: if the request payload does not contain an entity’s primary key (id for Workspaces), the entity will be created with the given payload. If the request payload does contain an entity’s primary key, the payload will “replace” the entity specified by the given primary key. If the primary key is not that of an existing entity, 404 NOT FOUND will be returned.

Response

HTTP 201 Created or HTTP 200 OK

Retrieve a Workspace

Endpoint

/workspaces/{name or id}
Attributes Description
name or id
required
The unique identifier or the name of the Workspace to retrieve

Response

HTTP 200 OK
{
  "created_at": 1528838706000,
  "id": "5396b1b3-ff46-4cb2-8065-5a4b35be342d",
  "name": "teamA"
}

Retrieve Workspace Metadata

Endpoint

/workspaces/{name or id}/meta
Attributes Description
name or id
required
The unique identifier or the name of the Workspace to retrieve

Response

HTTP 200 OK
{
    "counts": {
        "acls": 0,
        "apis": 0,
        "basicauth_credentials": 0,
        "consumers": 1234,
        "files": 41,
        "hmacauth_credentials": 0,
        "jwt_secrets": 0,
        "keyauth_credentials": 0,
        "oauth2_authorization_codes": 0,
        "oauth2_credentials": 0,
        "oauth2_tokens": 0,
        "plugins": 0,
        "rbac_roles": 3,
        "rbac_users": 0,
        "routes": 15,
        "services": 2,
        "ssl_certificates": 0,
        "ssl_servers_names": 0,
        "targets": 1,
        "upstreams": 1
    }
}

Delete a Workspace

Endpoint

/workspaces/{name or id}
Attributes Description
name or id
required
The unique identifier or the name of the Workspace to delete

Response

HTTP 204 No Content

Update a Workspace

Endpoint

/workspaces/{name or id}
Attributes Description
name or id
required
The unique identifier or the name of the Workspace to delete

Request Body

Attributes Description
comment A string describing the workspace

The behavior of PATCH endpoints prevents the renaming of a workspace.

Response

HTTP 200 OK
{
  "name": "teamB",
  "created_at": 1528838706000,
  "id": "5396b1b3-ff46-4cb2-8065-5a4b35be342d"
}

Add entities to a Workspace

Workspaces are groups of entities. This endpoint allows one to add an entity, identified by its unique identifier, to a workspace.

Endpoint

/workspaces/{name or id}/entities

Request Body

Attribute Description
entities Comma-delimited list of entity identifiers

Response

HTTP 200 No Content
{
  "host": "example.com",
  "created_at": 1528927690,
  "connect_timeout": 60000,
  "id": "ecdc96cd-39d7-4a72-b661-8481a3e14e1e",
  "protocol": "http",
  "name": null,
  "read_timeout": 60000,
  "port": 80,
  "path": "/",
  "updated_at": 1528927690,
  "retries": 5,
  "write_timeout": 60000
}

The response is the representation of the entity that was added to the workspace—in this case, a Service.

List entities that are part of a Workspace

Endpoint

/workspaces/{name or id}/entities

Response

HTTP 200 OK
{
  "data": [
    {
      "workspace_id": "5396b1b3-ff46-4cb2-8065-5a4b35be342d",
      "entity_id": "d766d5a8-4dc8-49e8-928d-29ff5aebb927",
      "entity_type": "services",
    },
    {
      "workspace_id": "5396b1b3-ff46-4cb2-8065-5a4b35be342d",
      "entity_id": "65b66412-df45-485d-8fa8-13cda8c892ac",
      "entity_type": "consumers",
    }
  ],
  "total": 2
}

In this case, the workspace references two entities: a Service and a Consumer.

Delete entities from a Workspace

Endpoint

/workspaces/{name or id}/entities

Request Body

Attribute Description
entities Comma-delimited list of entity identifiers

Response

HTTP 204 No Content

Retrieve an entity from a Workspace

This endpoint allows one to retrieve an entity from a workspace—useful, say, for checking if a given entity is part of a given workspace.

Endpoint

/workspaces/{name or id}/entities/{name or id}

Response

HTTP 200 OK
{
  "workspace_id": "5396b1b3-ff46-4cb2-8065-5a4b35be342d",
  "entity_id": "d766d5a8-4dc8-49e8-928d-29ff5aebb927",
  "entity_type": "services"
}

Delete a particular entity from a workspace

Endpoint

/workspaces/{name or id}/entities/{name or id}

Response

HTTP 204 No Response

Next: Workspaces Examples ›