Key-values

{
  "etag": [string],
  "key": [string],
  "label": [string, optional],
  "content_type": [string, optional],
  "value": [string],
  "last_modified": [datetime ISO 8601],
  "locked": [boolean],
  "tags": [object with string properties, optional]
}

GET /kv/{key}?label={label}&api-version={api-version}

HTTP/1.1 200 OK
Content-Type: application/vnd.microsoft.appconfig.kv+json; charset=utf-8;
Last-Modified: Tue, 05 Dec 2017 02:41:26 GMT
ETag: "4f6dd610dd5e4deebc7fbaef685fb903"

{
  "etag": "4f6dd610dd5e4deebc7fbaef685fb903",
  "key": "{key}",
  "label": "{label}",
  "content_type": null,
  "value": "example value",
  "last_modified": "2017-12-05T02:41:26+00:00",
  "locked": "false",
  "tags": {
    "t1": "value1",
    "t2": "value2"
  }
}

HTTP/1.1 404 Not Found

GET /kv/{key}?api-version={api-version} HTTP/1.1
Accept: application/vnd.microsoft.appconfig.kv+json;
If-None-Match: "{etag}"

HTTP/1.1 304 NotModified

HTTP/1.1 200 OK

GET /kv?label=*&api-version={api-version} HTTP/1.1

Response:

HTTP/1.1 200 OK
Content-Type: application/vnd.microsoft.appconfig.kvset+json; charset=utf-8

Optional: tags (If not specified, it implies any tags.)

GET /kv?key=Test*&label=*&tags=tag1=value1&tags=tag2=value2&api-version={api-version} HTTP/1.1

Response:

HTTP/1.1 200 OK
Content-Type: application/vnd.microsoft.appconfig.kvset+json; charset=utf-8

For more options, see the "Filtering" section later in this article.

List key-values (conditionally)

To improve client caching, use If-Match or If-None-Match request headers. The etag argument is part of the list key-values response body and header. If If-Match or If-None-Match are omitted, the operation is unconditional.

The following response gets the key-value only if the current representation matches the specified etag:

GET /kv?key={key}label={label}&api-version={api-version} HTTP/1.1
If-Match: "4f6dd610dd5e4deebc7fbaef685fb903"

Responses:

HTTP/1.1 412 PreconditionFailed

or

HTTP/1.1 200 OK

The following response gets the key-values only if the current representation doesn't match the specified etag:

GET /kv?key={key}label={label}&api-version={api-version} HTTP/1.1
If-None-Match: "4f6dd610dd5e4deebc7fbaef685fb903"

Responses:

HTTP/1.1 304 NotModified

or

HTTP/1.1 200 OK

Pagination

The result is paginated if the number of items returned exceeds the response limit. Follow the optional Link response headers, and use rel="next" for navigation. Alternatively, the content provides a next link in form of the @nextLink property. The linked URI includes the api-version argument.

GET /kv?api-version={api-version} HTTP/1.1

Response:

HTTP/1.1 200 OK
Content-Type: application/vnd.microsoft.appconfig.kvs+json; charset=utf-8
Link: <{relative uri}>; rel="next"

{
    "items": [
        ...
    ],
    "@nextLink": "{relative uri}"
}

Filtering

A combination of key and label filtering is supported. Use the optional key and label query string parameters.

GET /kv?key={key}&label={label}&api-version={api-version}

A combination of key, label, and tags filtering is supported. Use the optional key, label, and tags query string parameters. Multiple tag filters can be provided as query string parameters in the tagName=tagValue format. Tag filters must be an exact match.

GET /kv?key={key}&label={label}&tags={tagFilter1}&tags={tagFilter2}&api-version={api-version}

Supported filters

Key filter	Effect
key is omitted or key=*	Matches any key
key=abc	Matches a key named abc
key=abc*	Matches keys names that start with abc
key=abc,xyz	Matches keys names abc or xyz (limited to 5 CSV)

Label filter	Effect
label is omitted or label=*	Matches any label
label=%00	Matches key-values with no label
label=prod	Matches the label prod
label=prod*	Matches labels that start with prod
label=prod,test	Matches labels prod or test (limited to 5 CSV)

Tags filter	Effect
tags is omitted or tags=	Matches any tag
tags=group=app1	Matches key-values that have a tag named group with value app1
tags=group=app1&tags=env=prod	Matches key-values that have a tag named group with value app1 and a tag named env with value prod(limited to 5 tag filters)
tags=tag1=%00	Matches key-values that have a tag named tag1 with value null
tags=tag1=	Matches key-values that have a tag named tag1 with empty value

Reserved characters

*, \, ,

If a reserved character is part of the value, then it must be escaped by using \{Reserved Character}. Non-reserved characters can also be escaped.

Filter validation

If filter validation fails, the response is HTTP 400 with error details:

HTTP/1.1 400 Bad Request
Content-Type: application/problem+json; charset=utf-8

{
  "type": "https://azconfig.io/errors/invalid-argument",
  "title": "Invalid request parameter '{filter}'",
  "name": "{filter}",
  "detail": "{filter}(2): Invalid character",
  "status": 400
}

Examples

• All

  GET /kv?api-version={api-version}
  

• Key name starts with abc and includes all labels

  GET /kv?key=abc*&label=*&api-version={api-version}
  

• Key name starts with abc and label equals v1 or v2

  GET /kv?key=abc*&label=v1,v2&api-version={api-version}
  

Request specific fields

Use the optional $select query string parameter and provide a comma-separated list of requested fields. If the $select parameter is omitted, the response contains the default set.

GET /kv?$select=key,value&api-version={api-version} HTTP/1.1

Time-based access

Obtain a representation of the result as it was at a past time. For more information, see section 2.1.1. Pagination is still supported as defined earlier in this article.

GET /kv?api-version={api-version} HTTP/1.1
Accept-Datetime: Sat, 12 May 2018 02:10:00 GMT

Response:

HTTP/1.1 200 OK
Content-Type: application/vnd.microsoft.appconfig.kvset+json"
Memento-Datetime: Sat, 12 May 2018 02:10:00 GMT
Link: <{relative uri}>; rel="original"

{
    "items": [
        ....
    ]
}

Set key

• Required: {key}
• Optional: label (If not specified, or label=%00, it implies key-value without a label.)

PUT /kv/{key}?label={label}&api-version={api-version} HTTP/1.1
Content-Type: application/vnd.microsoft.appconfig.kv+json

{
  "value": "example value",         // optional
  "content_type": "user defined",   // optional
  "tags": {                         // optional
    "tag1": "value1",
    "tag2": "value2",
  }
}

Responses:

HTTP/1.1 200 OK
Content-Type: application/vnd.microsoft.appconfig.kv+json; charset=utf-8
Last-Modified: Tue, 05 Dec 2017 02:41:26 GMT
ETag: "4f6dd610dd5e4deebc7fbaef685fb903"

{
  "etag": "4f6dd610dd5e4deebc7fbaef685fb903",
  "key": "{key}",
  "label": "{label}",
  "content_type": "user defined",
  "value": "example value",
  "last_modified": "2017-12-05T02:41:26.4874615+00:00",
  "tags": {
    "tag1": "value1",
    "tag2": "value2",
  }
}

If the item is locked, the following response is returned:

HTTP/1.1 409 Conflict
Content-Type: application/problem+json; charset="utf-8"

{
    "type": "https://azconfig.io/errors/key-locked",
    "title": "Modifing key '{key}' is not allowed",
    "name": "{key}",
    "detail": "The key is read-only. To allow modification unlock it first.",
    "status": 409
}

Set key (conditionally)

To prevent race conditions, use If-Match or If-None-Match request headers. The etag argument is part of the key representation. If If-Match or If-None-Match are omitted, the operation is unconditional.

The following response updates the value only if the current representation matches the specified etag:

PUT /kv/{key}?label={label}&api-version={api-version} HTTP/1.1
Content-Type: application/vnd.microsoft.appconfig.kv+json
If-Match: "4f6dd610dd5e4deebc7fbaef685fb903"

The following response updates the value only if the current representation doesn't match the specified etag:

PUT /kv/{key}?label={label}&api-version={api-version} HTTP/1.1
Content-Type: application/vnd.microsoft.appconfig.kv+json;
If-None-Match: "4f6dd610dd5e4deebc7fbaef685fb903"

The following request adds the value only if a representation already exists:

PUT /kv/{key}?label={label}&api-version={api-version} HTTP/1.1
Content-Type: application/vnd.microsoft.appconfig.kv+json;
If-Match: "*"

The following request adds the value only if a representation doesn't already exist:

PUT /kv/{key}?label={label}&api-version={api-version} HTTP/1.1
Content-Type: application/vnd.microsoft.appconfig.kv+json
If-None-Match: "*"

Responses

HTTP/1.1 200 OK
Content-Type: application/vnd.microsoft.appconfig.kv+json; charset=utf-8
...

or

HTTP/1.1 412 PreconditionFailed

Delete

• Required: {key}, {api-version}
• Optional: {label} (If not specified, or label=%00, it implies key-value without a label.)

DELETE /kv/{key}?label={label}&api-version={api-version} HTTP/1.1

Response: Return the deleted key-value, or none if the key-value didn't exist.

HTTP/1.1 200 OK
Content-Type: application/vnd.microsoft.appconfig.kv+json; charset=utf-8
...

or

HTTP/1.1 204 No Content

Delete key (conditionally)

This is similar to the "Set key (conditionally)" section earlier in this article.