From 4de15e822ffe9c8f8bf946adf84e891b79fc6c67 Mon Sep 17 00:00:00 2001 From: Jared Kirschner Date: Wed, 16 Feb 2022 10:19:00 -0800 Subject: [PATCH] Document API ability to URL-decode resource names All Consul HTTP API endpoints now URL-decode resource names specified in the path, enabling resource names containing URL-invalid characters to be used in HTTP API requests if URL-encoded into the path. Functionality implemented in Github Pull Requests: - #11335 - #11957 - #12103 - #12190 - #12297 Also documents CLI accepting URL-invalid resource names. All Consul HTTP API endpoints now URL-decode resource names specified in the path, enabling resource names containing URL-invalid characters to be used in HTTP API requests if URL-encoded into the path. The Consul HTTP API always supported URL-decoding of query parameters. The CLI automatically URL-encodes arguments which are inserted as resource names in the URL path, enabling the CLI to also interact with resource names that contain URL-invalid characters. --- website/content/api-docs/index.mdx | 20 ++++++++++++++++++++ website/content/commands/index.mdx | 6 ++++++ 2 files changed, 26 insertions(+) diff --git a/website/content/api-docs/index.mdx b/website/content/api-docs/index.mdx index 23b3456eb..25a3f0c7b 100644 --- a/website/content/api-docs/index.mdx +++ b/website/content/api-docs/index.mdx @@ -79,6 +79,26 @@ $ curl \ http://127.0.0.1:8500/v1/kv/foo ``` +## URL-Encoded Resource Names + +Some Consul HTTP API endpoints accept resource names in URL path or query parameters. +To pass a resource name containing URL-invalid characters, such as `/` or ` `, +URL-encode the resource name into the URL. + +However, we generally recommend using resource names that don't require URL-encoding. +Depending on the validation that Consul applies to a resource name, +Consul may still reject a request if it considers the resource name invalid for that endpoint. +And even if Consul considers the resource name valid, it may degrade other functionality, +such as failed [DNS lookups](/docs/discovery/dns) +for nodes or services with names containing invalid DNS characters. + +This HTTP API capability also allows the +[CLI to accept arguments with URL-invalid characters](/commands#arguments-with-url-invalid-characters). + +### Invalid Characters + +The linefeed character (`%0a`) will cause a request to be rejected even if it is URL-encoded. + ## Translated Addresses Consul 0.7 added the ability to translate addresses in HTTP response based on diff --git a/website/content/commands/index.mdx b/website/content/commands/index.mdx index 47c4085b6..36aa5d19f 100644 --- a/website/content/commands/index.mdx +++ b/website/content/commands/index.mdx @@ -119,6 +119,12 @@ $ consul operator raft list-peers remove-peer ``` +## Arguments with URL-Invalid Characters + +The CLI automatically URL-encodes arguments, which are then +[URL-decoded by the underlying HTTP API endpoints](/api-docs#url-encoded-resource-names). +To avoid double-encoding arguments, do not URL-encode arguments passed to the CLI. + ## Environment Variables In addition to CLI flags, Consul reads environment variables for behavior