Vertica Documentation – Management API

Connecting-To: cURL

Mon, 01 Jan 0001 00:00:00 +0000

cURL is a command-line tool and application library used to transfer data to or from a server. All API requests sent to a Vertica server must be made with HTTPS.

There are four HTTP requests that can be passed using cURL to call API methods:

GET: Retrieves data.
PUT: Updates data.
POST: Creates new data.
DELETE: Deletes data.

Syntax

curl https://<NODE>:5444/

Options

The following is a truncated list of options. For a complete list, see the cURL documentation.

`-h --help`	Lists all available options.
`-H --header`	Specifies custom headers. This is useful for sending a request that requires a Vertica API key. Example: `$ curl -H "VerticaApiKey: ValidAPIKey" https://<NODE>:5444/`
`-k --insecure`	Connects with TLS without validating the database's server certificate. Example: `$ curl -k https://<NODE>:5444/`
`-X --request`	Specifies a request type, one of the following: GET (default) PUT POST DELETE Example: `$ curl -X REQUEST https://<NODE>:5444/`

Configuring HTTPS

HTTPS encrypts your connection with TLS. The following procedure enables HTTPS by using the predefined server TLS Configuration. To create a custom TLS Configuration, see TLS configurations.

Generate or import the following according to your use case:
- Server Mode: server certificate private key, server certificate
- Mutual Mode: server certificate private key, server certificate, CA certificate(s)
Run the following commands according to your desired configuration. New connections will use TLS.
- To use Server Mode, set the server certificate for the server TLS Configuration:
```
=> ALTER TLS CONFIGURATION server CERTIFICATE server_cert;
```
- To use Mutual Mode, set a server and CA certificate. This CA certificate is used to verify client certificates:
```
=> ALTER TLS CONFIGURATION server CERTIFICATE server_cert ADD CA CERTIFICATES ca_cert;
```
  To use multiple CA certificates, separate them with commas:
```
=> ALTER TLS CONFIGURATION server CERTIFICATE server_cert
   ADD CA CERTIFICATES intermediate_ca_cert, ca_cert;
```
Enable TLS (disabled by default). Choose one of the following TLSMODEs, listed in ascending security.
- DISABLE: Disables TLS. All other options for this parameter enable TLS.
- ENABLE: Enables TLS. Vertica does not check client certificates.
- TRY_VERIFY: Establishes a TLS connection if one of the following is true:
  - the client presents a valid certificate
  - the client doesn't present a certificate
  If the client presents an invalid certificate, the connection will use plaintext.
- VERIFY_CA: Connection succeeds if Vertica verifies that the client certificate is from a trusted CA. If the client does not present a client certificate, the connection uses plaintext.
TLS Configurations also support the TLSMODE VERIFY_FULL, but this TLSMODE is unsupported for HTTPS and behaves like VERIFY_CA.

For Server Mode, choose ENABLE:
```
=> ALTER TLS CONFIGURATION server TLSMODE 'ENABLE';
```
For Mutual Mode, choose TRY_VERIFY or higher:
```
=> ALTER TLS CONFIGURATION server TLSMODE 'VERIFY_CA';
```

Verify that the HttpsTLSConfig parameters is set to the server TLS Configuration:

=> SHOW CURRENT HttpsTLSConfig;
  level  |      name       | setting
---------+-----------------+---------
 DEFAULT | HttpsTLSConfig  | server
(1 row)

If not, set the HttpsTLSConfig parameter:

=> ALTER DATABASE DEFAULT SET HttpsTLSConfig = 'server';

Connecting-To: General API information

Mon, 01 Jan 0001 00:00:00 +0000

These API calls can interact with either standard Vertica nodes or Management Console nodes.

GET /	Returns the agent-specific information useful for version checking and service discovery.
GET api	Returns a list of api objects and properties.

Connecting-To: Rest APIs for the agent

Mon, 01 Jan 0001 00:00:00 +0000

These API calls interact with standard Vertica nodes.

Backup and restore

GET backups	Returns all the backups that have been created for all vbr configuration files ( *.ini ) that are located in the `/opt/vertica/config` directory.
POST backups/:config_script_base	Creates a new backup as defined by the given vbr configuration script base (filename without the .ini extension).
GET backups/:config_script_base/:archive_id	Returns details for a specific backup archive.
DELETE backups/:config_script_base/:backup_id	Deletes a backup.
POST restore/:archive_id	Restores a backup.

Databases

GET databases	Returns a list of databases, their properties, and current status.
POST databases	Creates a new database by supplying a valid set of parameters.
GET databases/:database_name	Returns details about a specific database.
PUT databases/:database_name	Starts, stops, rebalances, or runs Workload Analyzer on a database.
DELETE databases/:database_name	Deletes an existing database.
GET databases/:database_name/configuration	Returns the current configuration parameters from the database.
PUT databases/:database_name/configuration	Sets one or more configuration parameters in the database.
GET databases/:database_name/hosts	Returns hosts details for a specific database.
POST databases/:database_name/hosts	Adds a new host to the database.
DELETE databases/:database_name/hosts/:host_id	Removes a host from the database.
POST databases/:database_name/hosts/:host_id/process	Starts the database process on a specific host.
DELETE databases/:database_name/hosts/:host_id/process	Stops the database on a specific host.
POST databases/:database_name/hosts/:host_id/replace_with/:host_id_new	Replaces a host with a standby host in the database.
GET databases/:database_name/license	Returns the Vertica license that the specified database is using.
PUT databases/:database_name/license	Upgrades the license in the database.
GET databases/:database_name/licenses	Returns all the feature licenses that the specified database is using.
GET databases/:database_name/nodes	Returns a list of nodes for the specified database.
GET databases/:database_name/nodes/:node_id	Returns details on a specific node for the specified database.
POST databases/:database_name/process	Starts the specified database.
GET databases/:database_name/process	Returns the state of the database as either UP or DOWN.
DELETE databases/:database_name/process	Stops the specified database on all hosts.
POST databases/:database_name/rebalance/process	Rebalances the specified database. This option can have a long run time.
GET databases/:database_name/status [broken]	Retrieves the database properties structure.
POST databases/:database_name/Workload Analyzer/process	Runs the analyze workload action against the specified database.This option can have a long run time.

Hosts

GET hosts	Returns a list of hosts in this cluster.
GET hosts/:hostid	Returns details for a specific host in this cluster.

Jobs

GET jobs	Returns a list of jobs the agent is tracking, along with their current status and exit codes.
DELETE jobs/:id	Deletes a specific job by canceling any outstanding activity associated with it.
GET jobs/:id	Returns the details (the saved output) for a specific job.

Licenses

POST licenses	Uploads and applies a new license to this cluster.
GET licenses	Returns the license field that databases created on this cluster use.

Nodes

GET nodes	Returns a list of nodes in this cluster.
GET nodes/:nodeid	Returns details for a specific node in this cluster.

Webhooks

GET webhooks	Returns a list of active webhooks.
POST webhooks/subscribe	Creates a new webhook.
DELETE webhooks/:subscriber_id	Deletes an existing webhook.

Connecting-To: Rest APIs for the Management Console

Mon, 01 Jan 0001 00:00:00 +0000

These API calls interact with Management Console nodes.

Alerts

GET alerts

Returns alerts for the current user.

Time information

GET mcTimeInfo

Returns the current time for the MC server and the timezone of the location where the MC server is located.