The response format is JSON. Examples are found in the use-cases.
Also see the deploy guide.
Note:
To build a multi-application system, use one or three config server(s) per application.
Best practise is using a containerized architecture,
also see multinode-HA.
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/default/session.
All operations are synchronous across the cluster of config servers,
meaning that requests return after the operations complete on all servers.
Entities:
session-id
The session-id used in this API is generated by the server and is required
for all operations after creating a session.
The session is valid as long as it is one of the last 10 session-ids created.
path
An application file path in a request URL or parameter refers to a
relative path in the application package.
A path ending with "/" refers to a directory.
Note:
Use convergence
to confirm configuration activation on all nodes.
POST /application/v2/tenant/default/prepareandactivate
Creates a new session with the application package that is included in the request,
prepares it and then activates it.
See details in the steps later in this document
{"log":[{"time":1619448107299,"level":"WARNING","message":"Host named 'vespa-container' may not receive any config since it is not a canonical hostname. Disregard this warning when testing in a Docker container."}],"tenant":"default","session-id":"3","url":"http://localhost:19071/application/v2/tenant/default/application/default/environment/prod/region/default/instance/default","message":"Session 3 for tenant 'default' prepared and activated.","configChangeActions":{"restart":[],"refeed":[],"reindex":[]}}
POST /application/v2/tenant/default/session
Creates a new session with the application package that is included in the request.
Parameters
Name
Default
Description
from
N/A
Should only be used when you want to create a session based on an active application.
Valid values are a URL to an active application.
A new session will be created based on the corresponding application.
Examples (both requests return the same response):
POST /application/v2/tenant/default/session
POST /application/v2/tenant/default/session?from=http://myconfigserver.mydomain.com:19071/application/v2/tenant/default/application/default/environment/default/region/default/instance/default
Any errors or warnings from deleting the resource.
PUT /application/v2/tenant/default/session/[session-id]/prepared
Prepares an application with the session-id given.
Parameters
Parameter
Default
Description
applicationName
N/A
Name of the application to be deployed
environment
default
Environment where application should be deployed
region
default
Region where application should be deployed
instance
default
Name of application instance
debug
false
If true, include stack trace in response if prepare fails.
timeout
300 seconds
Timeout in seconds to wait for session to be prepared.
Request body
None
Response
Returns a session-id and a link to activate the session.
Log with any errors or warnings from preparing the application.
An activate URL for activating
the application with this session-id, if there were no errors.
A list of actions (possibly empty) that must be performed in order to apply some config changes
between the current active application and this next prepared application.
These actions are organized into three categories; restart, reindex, and refeed:
Restart actions are done after the application has been activated
and are handled by restarting all listed services.
See
schemas for details.
Reindex actions are special refeed actions that Vespa
handles automatically, if the
reindex endpoint below is used.
Refeed actions require several steps to handle.
See schemas for details.
Example:
PUT /application/v2/tenant/default/session/3/prepared
{"tenant":"default","session-id":"3","activate":"http://myconfigserver.mydomain.com:19071/application/v2/tenant/default/session/3/active","message":"Session 3 for tenant 'default' prepared.","log":[{"level":"WARNING","message":"Warning message 1","time":1430134091319},{"level":"WARNING","message":"Warning message 2","time":1430134091320}],"configChangeActions":{"restart":[{"clusterName":"mycluster","clusterType":"search","serviceType":"searchnode","messages":["Document type 'test': Field 'f1' changed: add attribute aspect"],"services":[{"serviceName":"searchnode","serviceType":"searchnode","configId":"mycluster/search/cluster.mycluster/0","hostName":"myhost.mydomain.com"}]}],"reindex":[{"documentType":"test","clusterName":"mycluster","messages":["Document type 'test': Field 'f1' changed: add index aspect"],"services":[{"serviceName":"searchnode","serviceType":"searchnode","configId":"mycluster/search/cluster.mycluster/0","hostName":"myhost.mydomain.com"}]}]}}
GET /application/v2/tenant/default/session/[session-id]/prepared
Returns the state of a prepared session.
The response is the same as a successful prepare operation (above),
however the configChangeActions element will be empty.
PUT /application/v2/tenant/default/session/[session-id]/active
Activates an application with the session-id given.
The session-id must be for a prepared session.
The operation will make sure the session is activated on all config servers.
Parameters
Parameter
Default
Description
timeout
60 seconds
Timeout in seconds to wait for session to be activated (when
several config servers are used, they might need to sync
before activate can be done).
Request body
None
Response
Returns a session-id, a message and a URL to the activated application.
POST /application/v2/tenant/default/application/default/environment/default/region/default/instance/default/reindex
Triggers reindexing of specified document types in
specified clusters of an application.
Reindexing starts with the next redeployment of the application.
All document types in all clusters are reindexed unless restricted, using parameters as specified:
Parameters
Name
Description
clusterId
A comma-separated list of content clusters to limit reindexing to.
All clusters are reindexed if this is not present.
documentType
A comma-separated list of document types to limit reindexing to.
All document types are reindexed if this is not present.
indexedOnly
Boolean: whether to trigger reindexing only for document types with indexing
mode index and at least one with field the indexing statement
index. Default is false.
speed
Number (0-10], default 1: Relative indexing speed -
balance speed vs. resource use. Example: speed=0.1
Request body
N/A
Response
A human-readable message indicating what reindexing was triggered.
Example:
POST /application/v2/tenant/default/application/default/environment/default/region/default/instance/default/reindex?clusterId=foo,bar&documentType=moo,baz&indexedOnly=true
{"message":"Reindexing document types [moo, baz] in 'foo', [moo] in 'bar' of application default.default"}
GET /application/v2/tenant/default/application/default/environment/default/region/default/instance/default/content/[path]
Returns content at the given path for an application.
See getting content for usage and response.
Errors are returned using standard HTTP status codes.
Any additional info is included in the body of the return call, JSON-formatted.
The general format for an error response is:
Bad request. Client error. The error message should indicate the cause.
400
INVALID_APPLICATION_PACKAGE
There is an error in the application package. The error message should indicate the cause.
400
OUT_OF_CAPACITY
Not enough nodes available for the request to be fulfilled.
401
Not authorized. The error message should indicate the cause.
404
NOT_FOUND
Not found. E.g. when using a session-id that doesn't exist.
405
METHOD_NOT_ALLOWED
Method not implemented. E.g. using GET where only POST or PUT is allowed.
409
CONFLICT
Conflict, returned when activating an application fails due
to a conflict with other changes to the same application (in
another session). Client should retry.
500
INTERNAL_SERVER_ERROR
Internal server error. Generic error. The error message should indicate the cause.
Access log
Requests are logged in the access log which can be found at
$VESPA_HOME/logs/vespa/configserver/access-json.log, example:
To add the file files/test1.txt, first create the directory, then add the file:
$ curl -s -X PUT "http://host:19071/application/v2/tenant/default/session/2/content/files/"
$ curl -s -X PUT --data-binary @app/files/test1.txt \
"http://host:19071/application/v2/tenant/default/session/2/content/files/test1.txt"
Prepare and activate the session:
$ curl -s -X PUT "http://host:19071/application/v2/tenant/default/session/2/prepared?applicationName=fooapp"
$ curl -s -X PUT "http://host:19071/application/v2/tenant/default/session/2/active"
Rollback
If you need to roll back to a previous version of the application package
this can be achieved by creating a new session based on the previous known
working version by passing the corresponding session-id in the
from argument, see creating a session