Config API

The Cloud Config System (CCS) provides a REST API for listing and retrieving config - alternatives are the programmatic C++ or Java APIs. The Config API provides a way to inspect and retrieve all the config that can be generated by the config model for a given tenant's active application. Some, but not necessarily all, of those configs are used by services by subscribing to them.

The response format is JSON. The current API version is 2. All cloud config servers provide the REST API. The API port is 19071 - use vespa-model-inspect service configserver to find config server hosts. Example: http://myconfigserver.mydomain.com:19071/config/v2/tenant/msbe/application/articlesearch/

The API is available after an application has been deployed and activated.

The application id

The API provides two ways to identify your application, given a tenant: one using only an application name, and one using application name, environment, region and instance. For the former, "short" form, a default environment, region and instance is used.

More formally, an application id is a tuple of the form (application, environment, region, instance). The system currently provides shorthand to the id (application, "default", "default", "default").

Note: Multiple environments, regions and instances are not currently supported for application deployments, default is always used.

Example URL using only application name: http://myconfigserver.mydomain.com:19071/config/v2/tenant/media/application/articlesearch/media.config.server-list/clusters/0

PartDescription
mediaTenant
articlesearchApplication
media.configNamespace of the requested config
server-listName of the requested config
clusters/0Config id of the requested config

Example URL using full application id: http://myconfigserver.mydomain.com:19071/config/v2/tenant/media/application/articlesearch/environment/test/region/us/instance/staging/media.config.server-list/clusters/0

PartDescription
mediaTenant
articlesearchName of the application
testEnvironment
usRegion
stagingInstance
media.configNamespace of the requested config
server-listName of the requested config
clusters/0Config id of the requested config
In this API specification, the short form of the application id, i.e. only the application name, is used. The tenant mytenant and the application name myapplication is used throughout in examples.

GET /config/v2/tenant/mytenant/application/myapplication/

List the configs in the model, as config id specific URLs.

Parameters
ParameterDefaultDescription
recursive false If true, include each config id in the model which produces the config, and list only the links to the config payload. If false, include the first level of the config ids in the listing of new list URLs, as explained above.
Request body None
Response A list response includes two arrays:
  • List-links to descend one level down in the config id hierarchy, named children.
  • Config payload links for the current (top) level, named configs.
Error Response N/A
Examples:
GET /config/v2/tenant/mytenant/application/myapplication/
{
  "children": [
    "http://myconfigserver.mydomain.com:19071/config/v2/tenant/mytenant/application/myapplication/config.sentinel/myconfigserver.mydomain.com/",
    "http://myconfigserver.mydomain.com:19071/config/v2/tenant/mytenant/application/myapplication/config.sentinel/hosts/",
    "http://myconfigserver.mydomain.com:19071/config/v2/tenant/mytenant/application/myapplication/config.model/admin/",
    "http://myconfigserver.mydomain.com:19071/config/v2/tenant/mytenant/application/myapplication/container.components/search/"
  …  
  "configs": [
    "http://myconfigserver.mydomain.com:19071/config/v2/tenant/mytenant/application/myapplication/config.sentinel",
    "http://myconfigserver.mydomain.com:19071/config/v2/tenant/mytenant/application/myapplication/config.model",
    "http://myconfigserver.mydomain.com:19071/config/v2/tenant/mytenant/application/myapplication/container.components"
  …
GET /config/v2/tenant/mytenant/application/myapplication/?recursive=true
{
  "configs": [
    "http://myconfigserver.mydomain.com:19071/config/v2/tenant/mytenant/application/myapplication/config.sentinel/myconfigserver.mydomain.com",
    "http://myconfigserver.mydomain.com:19071/config/v2/tenant/mytenant/application/myapplication/config.sentinel/hosts/myconfigserver.mydomain.com"

GET /config/v2/tenant/mytenant/application/myapplication/[namespace.name]/

Parameters Same as above.
Request body None
Response List the configs in the model with the given namespace and name. List semantics as above.
Error Response 404 if the given namespace.name is not known to the config model.
Examples:
GET /config/v2/tenant/mytenant/application/myapplication/vespaclient.config.feeder/
{
  "children": [
    "http://myconfigserver.mydomain.com:19071/config/v2/tenant/mytenant/application/myapplication/vespaclient.config.feeder/search/",
    "http://myconfigserver.mydomain.com:19071/config/v2/tenant/mytenant/application/myapplication/vespaclient.config.feeder/clients/",
    "http://myconfigserver.mydomain.com:19071/config/v1/vespaclient.config.feeder/docproc/"
  ]
  "configs": [
    "http://myconfigserver.mydomain.com:19071/config/v2/tenant/mytenant/application/myapplication/vespaclient.config.feeder",
  ]
}
GET /config/v2/tenant/mytenant/application/myapplication/vespaclient.config.feeder/?recursive=true
{
  "configs": [
    "http://myconfigserver.mydomain.com:19071/config/v2/tenant/mytenant/application/myapplication/vespaclient.config.feeder/search/qrsclusters/default",
    "http://myconfigserver.mydomain.com:19071/config/v2/tenant/mytenant/application/myapplication/vespaclient.config.feeder/clients/gateways",
    "http://myconfigserver.mydomain.com:19071/config/v2/tenant/mytenant/application/myapplication/vespaclient.config.feeder/clients/gateways/gateway",

GET /config/v2/tenant/mytenant/application/myapplication/[namespace.name]/[config/subid]/

Parameters Same as above.
Request body None
Response List the configs in the model with the given namespace and name, and for which the given config id segment is a prefix.
Error Response
  • 404 if the given namespace.name is not known to the config model.
  • 404 if the given config id is not in the model.
Examples:
GET /config/v2/tenant/mytenant/application/myapplication/vespaclient.config.feeder/search/
{
  "children": [
    "http://myconfigserver.mydomain.com:19071/config/v2/tenant/mytenant/application/myapplication/vespaclient.config.feeder/search/qrsclusters/"
  ]
  "configs": [
    "http://myconfigserver.mydomain.com:19071/config/v2/tenant/mytenant/application/myapplication/vespaclient.config.feeder/search"
  ]
}
GET /config/v2/tenant/mytenant/application/myapplication/vespaclient.config.feeder/search/?recursive=true
{
    "configs": [
        "http://myhost.mydomain.com:19071/config/v2/tenant/mytenant/application/myapplication/vespaclient.config.feeder/search/qrsclusters/default"
    ]
}

GET /config/v2/tenant/mytenant/application/myapplication/[namespace.name]/[config/id]

Parameters None
Request body None
Response Returns the config payload of the given namespace.name/config/id, formatted as JSON.
Error Response Same as above.
Example:
GET /config/v2/tenant/mytenant/application/myapplication/container.core.container-http/search/qrsclusters/default/qrserver.0
{
  "enabled": "true",
  "requestbuffersize": "65536",
  "port": {
    "search": "8080",
    "host": ""
  },
  "fileserver": {
    "throughsearch": "true"
  }
}