API v2 - Conventions and shared behaviors

Este documento descreve os comportamentos padrão, regras e formatos que se aplicam a todos os endpoints da API v2 do A2A. Leia este documento antes de integrar com qualquer endpoint v2.

Headers de resposta

Toda resposta da API v2 inclui os headers a seguir, independentemente do endpoint ou do código de status HTTP.

Nota: Quando o limite de requisições é excedido, a API retorna 429 Too Many Requests. Aguarde até X-RateLimit-Reset antes de tentar novamente.

Requisições condicionais

If-None-Match — leituras condicionais (GET)

Use o valor do ETag de uma resposta anterior como header If-None-Match em uma requisição GET subsequente. Se o recurso não tiver sido alterado, o servidor retorna 304 Not Modified sem corpo, economizando largura de banda.

GET /api/v2/pam/credentials/101
If-None-Match: "abc123etag"

If-Match — escritas condicionais (PUT, PATCH, DELETE)

Use o valor do ETag de uma leitura anterior como header If-Match em uma requisição de escrita. Isso impede a sobrescrita de alterações feitas por outro processo desde a sua última leitura (controle de concorrência otimista).

PUT /api/v2/pam/credentials/101
If-Match: "abc123etag"

Formato de erros

Todas as respostas de erro v2 usam uma estrutura JSON consistente, independentemente do endpoint.

{
    "error": {
        "code": "api.fields.invalid",
        "message": "One or more requested fields do not exist in the canonical model.",
        "details": [
            {
                "field": "credential.nonexistent",
                "reason": "Field not found in CredentialV2 schema."
            }
        ]
    }
}

Política de 403 vs 404

A API v2 distingue deliberadamente entre falhas de autorização e recursos inexistentes.

Nota: A Segura® nunca retorna 404 para mascarar um 403. Se você receber 404, o recurso não existe. Se receber 403, o recurso existe, mas está fora do escopo da sua autorização.

Paginação

Todos os endpoints de listagem suportam duas estratégias de paginação. Cada endpoint documenta quais estratégias são suportadas.

Paginação por offset

Use para navegação padrão e conjuntos de dados de tamanho moderado.

Campos da resposta:

Paginação por cursor

Recomendada para conjuntos de dados acima de 100.000 registros. Mais eficiente que a paginação por offset para grandes volumes.

Campos da resposta:

Aviso: page/limit e cursor são mutuamente exclusivos. Enviar ambos na mesma requisição retorna 422 Unprocessable Content. Para conjuntos de dados grandes onde calcular total_items seria impraticável, o campo pode ser null ou uma estimativa — use has_more como sinal de continuação.

Projeção de campos (fields)

Endpoints que suportam fields retornam apenas o subconjunto solicitado do modelo canônico, reduzindo o tamanho do payload.

Uso:

GET /api/v2/pam/credentials/101?fields=credential.username,device.name,jit.credential_enabled

Regras:

• Use notação de ponto para referenciar campos aninhados (ex.: credential.username, device.tags).
• Solicite um objeto completo nomeando-o sem um caminho filho (ex.: fields=device retorna todos os campos não sensíveis de device).
• Quando fields é omitido, todos os campos públicos do modelo canônico são retornados, com null para campos não aplicáveis.
• Campos não presentes no modelo canônico retornam 422 com código api.fields.invalid.
• Campos sensíveis retornam 403 com código api.fields.sensitive.not.allowed. Veja Campos sensíveis.
• Campos fora do escopo da autorização vigente retornam 403.

Campos sensíveis — nunca retornados:

Os campos a seguir são permanentemente excluídos de todas as respostas. Solicitá-los retorna 403:

• credential.password
• certificate.key_file
• certificate.key_password
• totp.secret_key

Ordenação (sort_by)

Endpoints de listagem que suportam ordenação aceitam o parâmetro de query sort_by.

Uso:

GET /api/v2/pam/credentials?sort_by=criticality:desc,credential.username

Regras:

Filtros

Endpoints de listagem aceitam parâmetros de filtro como query strings. Todos os parâmetros de filtro são opcionais.

Lógica AND e OR

Nota: O caractere pipe (|) não é suportado como separador OR. Use valores separados por vírgula.

Valores booleanos em filtros

Parâmetros booleanos aceitam apenas true ou false como valores de string. Os valores 0, 1, yes e no não são aceitos e retornam 422.

Validação

Todos os parâmetros de filtro inválidos retornam um erro explícito — a API nunca ignora silenciosamente um filtro não reconhecido.

Exemplos

Correspondência exata:

GET /api/v2/pam/credentials?credential.username=svc-payments

AND — múltiplos campos:

GET /api/v2/pam/credentials?device_id=123&credential.criticality=high&jit.credential_enabled=true

AND — mesmo campo (array):

GET /api/v2/pam/credentials?credential.tags=prod&credential.tags=finance

OR — valores separados por vírgula:

GET /api/v2/pam/credentials?credential.criticality=high,medium

Ordenação por múltiplos campos:

GET /api/v2/pam/credentials?sort_by=criticality:desc,credential.username

Convenções de nomenclatura

Todos os endpoints da API v2 seguem estas convenções de forma consistente.

Erros de autenticação

Os erros de autenticação a seguir se aplicam a todos os endpoints v2.

Documentos relacionados

• GET | Listar todas as credenciais (v2)
• GET | Listar uma credencial por [id] (v2)
• Sobre aplicações e autorizações no A2A