mirror of
https://github.com/status-im/consul.git
synced 2025-01-10 13:55:55 +00:00
afa1cc98d1
Fixes: #4222 # Data Filtering This PR will implement filtering for the following endpoints: ## Supported HTTP Endpoints - `/agent/checks` - `/agent/services` - `/catalog/nodes` - `/catalog/service/:service` - `/catalog/connect/:service` - `/catalog/node/:node` - `/health/node/:node` - `/health/checks/:service` - `/health/service/:service` - `/health/connect/:service` - `/health/state/:state` - `/internal/ui/nodes` - `/internal/ui/services` More can be added going forward and any endpoint which is used to list some data is a good candidate. ## Usage When using the HTTP API a `filter` query parameter can be used to pass a filter expression to Consul. Filter Expressions take the general form of: ``` <selector> == <value> <selector> != <value> <value> in <selector> <value> not in <selector> <selector> contains <value> <selector> not contains <value> <selector> is empty <selector> is not empty not <other expression> <expression 1> and <expression 2> <expression 1> or <expression 2> ``` Normal boolean logic and precedence is supported. All of the actual filtering and evaluation logic is coming from the [go-bexpr](https://github.com/hashicorp/go-bexpr) library ## Other changes Adding the `Internal.ServiceDump` RPC endpoint. This will allow the UI to filter services better.
88 lines
2.7 KiB
Markdown
88 lines
2.7 KiB
Markdown
---
|
|
layout: api
|
|
page_title: HTTP API
|
|
sidebar_current: api-introduction
|
|
description: |-
|
|
Consul exposes a RESTful HTTP API to control almost every aspect of the
|
|
Consul agent.
|
|
---
|
|
|
|
# HTTP API Structure
|
|
|
|
The main interface to Consul is a RESTful HTTP API. The API can perform basic
|
|
CRUD operations on nodes, services, checks, configuration, and more.
|
|
|
|
## Authentication
|
|
|
|
When authentication is enabled, a Consul token should be provided to API
|
|
requests using the `X-Consul-Token` header. This reduces the probability of the
|
|
token accidentally getting logged or exposed. When using authentication,
|
|
clients should communicate via TLS.
|
|
|
|
Here is an example using `curl`:
|
|
|
|
```text
|
|
$ curl \
|
|
--header "X-Consul-Token: abcd1234" \
|
|
http://127.0.0.1:8500/v1/agent/members
|
|
```
|
|
|
|
Previously this was provided via a `?token=` query parameter. This functionality
|
|
exists on many endpoints for backwards compatibility, but its use is **highly
|
|
discouraged**, since it can show up in access logs as part of the URL.
|
|
|
|
## Version Prefix
|
|
|
|
All API routes are prefixed with `/v1/`. This documentation is only for the v1 API.
|
|
|
|
## Formatted JSON Output
|
|
|
|
By default, the output of all HTTP API requests is minimized JSON. If the client
|
|
passes `pretty` on the query string, formatted JSON will be returned.
|
|
|
|
## HTTP Methods
|
|
|
|
Consul's API aims to be RESTful, although there are some exceptions. The API
|
|
responds to the standard HTTP verbs GET, PUT, and DELETE. Each API method will
|
|
clearly document the verb(s) it responds to and the generated response. The same
|
|
path with different verbs may trigger different behavior. For example:
|
|
|
|
```text
|
|
PUT /v1/kv/foo
|
|
GET /v1/kv/foo
|
|
```
|
|
|
|
Even though these share a path, the `PUT` operation creates a new key whereas
|
|
the `GET` operation reads an existing key.
|
|
|
|
Here is the same example using `curl`:
|
|
|
|
```shell
|
|
$ curl \
|
|
--request PUT \
|
|
--data 'hello consul' \
|
|
http://127.0.0.1:8500/v1/kv/foo
|
|
```
|
|
|
|
## Translated Addresses
|
|
|
|
Consul 0.7 added the ability to translate addresses in HTTP response based on
|
|
the configuration setting for
|
|
[`translate_wan_addrs`](/docs/agent/options.html#translate_wan_addrs). In order
|
|
to allow clients to know if address translation is in effect, the
|
|
`X-Consul-Translate-Addresses` header will be added if translation is enabled,
|
|
and will have a value of `true`. If translation is not enabled then this header
|
|
will not be present.
|
|
|
|
## UUID Format
|
|
|
|
UUID-format identifiers generated by the Consul API use the
|
|
[hashicorp/go-uuid](https://github.com/hashicorp/go-uuid) library.
|
|
|
|
These UUID-format strings are generated using high quality, purely random bytes.
|
|
It is not intended to be RFC compliant, merely to use a well-understood string
|
|
representation of a 128-bit value.
|
|
|
|
|
|
|