Azion API

Uma interface de programação de aplicações (API) permite que um programa atue sobre um serviço sem usar a interface web dele. Uma REST API dá a cada objeto do serviço a sua própria URL: o cliente lê o objeto com GET, cria com POST, altera com PUT ou PATCH e remove com DELETE. Como cada ação é uma requisição HTTP, a mesma chamada roda de um terminal, de um script ou de um pipeline de CI/CD.

Azion API expõe os recursos da sua conta Azion como uma REST API sobre HTTPS, na URL base https://api.azion.com/v4. Cada requisição leva um personal token, as respostas retornam JSON e cada alteração também aparece no Azion Console. Use a Azion API para criar, ler, atualizar e excluir applications, firewalls, functions, network lists, workloads e os demais recursos da sua conta a partir do seu próprio código.

Você também pode gerenciar os mesmos recursos com a Azion CLI ou com o Azion Terraform Provider. Para consultar dados de métricas, eventos, billing e consumo, use a GraphQL API.

Estrutura da requisição

Uma requisição indica o caminho de um recurso sob a URL base e envia o personal token em um header. Esta requisição lista os IDs dos workloads de uma conta:

Um 200 retorna uma página de resultados:

• Caminho: os endpoints de recursos ficam sob /v4/workspace/, como /v4/workspace/workloads e /v4/workspace/network_lists.
• Header: Authorization leva o personal token com o esquema Token.
• Parâmetros de query: page_size=100 pede até 100 resultados na página, e fields=id mantém apenas o id de cada resultado.
• Envelope da lista: count é o número de workloads da conta, total_pages e page situam a página na lista, e results contém os workloads. next e previous são null porque a lista tem uma única página.

Se você já chamou uma REST API que retorna JSON, o modelo é o mesmo: um método, uma URL, um header de credencial e um corpo JSON. A referência da Azion API lista cada caminho, método, parâmetro e resposta. A API serve a sua especificação OpenAPI em https://api.azion.com/v4/openapi/openapi.yaml.

Clientes da API

O seu código é um entre vários clientes da Azion API. A Azion CLI e o Azion Terraform Provider chegam aos mesmos endpoints.

1. O seu código, ou um cliente HTTP como o curl, envia uma requisição para https://api.azion.com/v4 com o seu personal token no header Authorization.
2. A Azion CLI e o Azion Terraform Provider chamam a mesma API.
3. A API autentica o token e, em seguida, cria, lê, altera ou exclui os recursos da sua conta.
4. O Azion Console mostra os mesmos recursos, então uma alteração feita pela API também aparece nele.

Métodos e erros

A maioria dos endpoints aceita os mesmos métodos, divididos entre um caminho de coleção e um caminho de item, e os erros compartilham um único formato de resposta:

• Métodos: um caminho de coleção, como /v4/workspace/network_lists, aceita GET para listar e POST para criar. Um caminho de item, como /v4/workspace/network_lists/<network-list-id>, aceita GET, PUT, PATCH e DELETE. Outro método retorna 405 com o código 10007, e o header Allow da resposta lista os métodos que o caminho aceita.
• Corpos de sucesso: uma requisição de um único recurso o retorna dentro de data. Um POST ou um PATCH retorna "state": "executed" ao lado de data, e um DELETE retorna apenas {"state": "executed"}.
• Corpos de erro: um erro retorna um array errors. Cada item traz um code, um title, um detail, um status escrito como string e, em geral, um source que indica o header ou o campo do corpo com problema. Um POST que omite dois campos obrigatórios retorna dois itens, um por campo.

Para os erros que uma requisição pode retornar e como corrigir cada um, consulte Solucionar problemas da Azion API.

Autenticação

Cada requisição para a Azion API leva um personal token no header Authorization, com o esquema Token:

A API também aceita um personal token com o esquema Bearer, como Authorization: Bearer [TOKEN VALUE], e aceita o esquema Token escrito em minúsculas. Você cria um personal token no Azion Console ou com a Azion CLI, e a Azion mostra o valor dele apenas uma vez, na criação. Para criar um, consulte Gerencie personal tokens.

Uma requisição sem o header retorna 401 com o código 10002. Uma requisição cujo token a API não aceita retorna 401 com o código 10001. As duas respostas trazem o header WWW-Authenticate: Bearer realm="api".

Paginação e parâmetros de query

Uma requisição de lista retorna uma página de resultados, e cinco parâmetros de query escolhem qual página e o que cada resultado contém. O número de páginas volta em total_pages, e next e previous são null quando não existe uma página seguinte ou anterior. Para ler a página seguinte, envie a mesma requisição com page acrescido de um.

Um valor de ordering que não indica nenhum campo é ignorado: a requisição retorna 200 e a lista mantém a ordem padrão por ID. Em um único recurso, fields pode retornar mais do que os campos que você indicou: em uma network list, fields=id,name também retorna is_versioned e version. Para os termos que a API usa, consulte Glossário.

Versões da API

A Azion API v4 é a versão que estas páginas documentam, servida em https://api.azion.com/v4, e a sua especificação OpenAPI declara a versão 4.0.0. Uma conta passa da API v3 para ela por meio de uma migração. Para os recursos e endpoints que mudam, consulte Migração para API v4. Para verificar a versão da sua conta, consulte Verifique a versão da API da sua conta.

Limites

Dois limites valem para cada requisição de lista, e cada um retorna um erro quando o valor é ultrapassado:

Cada resposta autenticada também traz quatro headers de rate limit. Os headers têm esta forma:

X-RateLimit-Limit é 200 e X-RateLimit-Scope é global-default em todas as respostas. X-RateLimit-Remaining faz a contagem regressiva a partir do limite conforme você envia requisições. X-RateLimit-Reset informa o horário do próximo reset como um timestamp ISO 8601 sem fuso horário, cerca de um minuto após a requisição.

Próximos passos