[+] expand all

Config API

Vespa 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 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

Part	Description
media	Tenant
articlesearch	Application
media.config	Namespace of the requested config
server-list	Name of the requested config
clusters/0	Config 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

Part	Description
media	Tenant
articlesearch	Name of the application
test	Environment
us	Region
staging	Instance
media.config	Namespace of the requested config
server-list	Name of the requested config
clusters/0	Config 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

Parameter	Default	Description
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"
    }
}