Tenant API

This is the Tenant API specification with examples for the HTTP REST API for listing, creating and deleting tenants, which can further be used to deploy applications.

A tenant is property or product within an organization. Each tenant can have several applications deployed to multiple environments and regions. The response format is JSON.

The current API version is 2. The API port is 19071 - use vespa-model-inspect service configserver to find config server hosts - example: http://myconfigserver.mydomain.com:19071/application/v2/tenant/

Valid tenant names contains word characters only: [a-zA-Z_0-9]

Entities:

Tenant The tenant name is required for all operations. Tenant names may only contain word characters and dash: [a-zA-Z_0-9-].

GET /application/v2/tenant/

Lists the tenants handled by this configserver.

Parameters None
Request body None
Response A list of tenant names handled by this server
Example: GET /application/v2/tenant/
[
    "foo",
    "bar",
    "baz"
]

GET /application/v2/tenant/[tenant name]

Get the tenant.

Parameters None
Request body None
Response A message with the tenant name
Example: GET /application/v2/tenant/[tenant name]
{
    "message": "Tenant 'default' exists."
}

PUT /application/v2/tenant/[tenant name]

Creates a new tenant with the name given in the URL. Note: this operation is asynchronous, it will eventually propagate to all config servers.

Parameters None
Request body None
Response A message with the tenant name of the tenant that was created
Example: PUT /application/v2/tenant/mytenant
{
    "message" : "Tenant mytenant created."
}

DELETE /application/v2/tenant/[tenant name]

Deletes a tenant with name given in URL. Note: this operation is asynchronous, it will eventually propagate to all config servers.

Parameters None
Request body None
Response A message with the tenant name of the tenant that was deleted
Example: DELETE /application/v2/tenant/mytenant
{
    "message" : "Tenant mytenant deleted."
}

Error Handling

Errors are returned using standard HTTP status codes. Any additional info is included in the body of the return call, JSON-formatted.

HTTP status codeDescription
400 Bad request. Client error. The error message should indicate the cause.
404 Not found. For example using a session id that does not exist.
405 Method not implemented. E.g. using GET where only POST or PUT is allowed.
500 Internal server error. Generic error. The error message should indicate the cause.