Controle de versão

  • Artigo

Cada solicitação do cliente deve fornecer uma versão explícita da API como um parâmetro de cadeia de caracteres de consulta. Por exemplo: https://{myconfig}.azconfig.io/kv?api-version=1.0.

api-version é expresso no formato SemVer (major.minor). Não há suporte para negociação de intervalo ou versão.

Este artigo se aplica à versão 1.0 da API.

O exemplo a seguir descreve um resumo das possíveis respostas de erro retornadas pelo servidor quando a versão da API solicitada não pode ser corresponder.

Versão da API não especificada

Esse erro ocorre quando um cliente faz uma solicitação sem fornecer uma versão da API.

HTTP/1.1 400 Bad Request
Content-Type: application/problem+json; charset=utf-8
{
  "type": "https://azconfig.io/errors/invalid-argument",
  "title": "API version is not specified",
  "name": "api-version",
  "detail": "An API version is required, but was not specified.",
  "status": 400
}

Versão de API sem suporte

Esse erro ocorre quando uma versão da API solicitada pelo cliente não corresponder a nenhuma das versões de API com suporte pelo servidor.

HTTP/1.1 400 Bad Request
Content-Type: application/problem+json; charset=utf-8
{
  "type": "https://azconfig.io/errors/invalid-argument",
  "title": "Unsupported API version",
  "name": "api-version",
  "detail": "The HTTP resource that matches the request URI '{request uri}' does not support the API version '{api-version}'.",
  "status": 400
}

Versão da API Inválida

Esse erro ocorre quando um cliente faz uma solicitação com uma versão de API, mas o valor está malformado ou não pode ser analisado pelo servidor.

HTTP/1.1 400 Bad Request
Content-Type: application/problem+json; charset=utf-8  
{
  "type": "https://azconfig.io/errors/invalid-argument",
  "title": "Invalid API version",
  "name": "api-version",
  "detail": "The HTTP resource that matches the request URI '{request uri}' does not support the API version '{api-version}'.",
  "status": 400
}

Versão da API ambígua

Esse erro ocorre quando um cliente solicita uma versão de API ambígua para o servidor (por exemplo, vários valores diferentes).

HTTP/1.1 400 Bad Request
Content-Type: application/problem+json; charset=utf-8
{
  "type": "https://azconfig.io/errors/invalid-argument",
  "title": "Ambiguous API version",
  "name": "api-version",
  "detail": "The following API versions were requested: {comma separated api versions}. At most, only a single API version may be specified. Please update the intended API version and retry the request.",
  "status": 400
}