Use schemas OpenAPI para validação de requisições

Este artigo de referência explica o que são schemas OpenAPI, como funcionam e como usá-los para confirmar que suas requisições aos endpoints da REST API da Braze estão estruturadas corretamente antes de enviá-las.

Cada página de endpoint da REST API da Braze exibe uma referência interativa gerada a partir de uma especificação OpenAPI. Cada especificação inclui um schema: uma descrição precisa e legível por máquina dos dados que um endpoint aceita e retorna. Você pode usar esse schema para validar suas requisições, identificando erros estruturais nas suas próprias ferramentas em vez de descobri-los a partir de uma chamada de API que falhou.

Para uma visão geral mais ampla de como a Braze publica essas especificações e os outros fluxos de trabalho que elas suportam, consulte Usando especificações OpenAPI da Braze.

O que é um esquema OpenAPI

Um esquema é o contrato para os dados de um endpoint. Em um documento OpenAPI, o Schema Object define cada campo que um endpoint utiliza, incluindo o nome do campo, o tipo de dados, se é obrigatório, seus valores permitidos e como objetos aninhados e arrays são estruturados.

Os esquemas OpenAPI são baseados no JSON Schema, um padrão amplamente adotado para descrever a estrutura de dados JSON. Como o contrato é expresso em um formato padrão e legível por máquina, você pode validar uma carga útil com ferramentas prontas, em vez de verificar os campos manualmente. Para saber mais sobre os conceitos envolvidos, consulte Learn OpenAPI e Understanding JSON Schema.

Como os schemas funcionam

Um schema descreve dados usando um pequeno conjunto de blocos de construção. Os mais comuns são:

• Tipo. O tipo de dado de um valor, como string, integer, number, boolean, array ou object. Consulte Tipos de dados na documentação do Swagger.
• Campos obrigatórios. Uma lista das propriedades que precisam estar presentes para que os dados sejam válidos.
• Restrições. Regras que limitam o que um valor pode ser, como um enum de valores permitidos, um format (por exemplo, date-time), um padrão de string ou valores mínimos e máximos.
• Estrutura aninhada. Objetos podem conter outros objetos, e arrays declaram o schema dos itens que contêm, permitindo que um schema descreva cargas úteis com estruturas profundas.

Um validador lê essas regras e compara seus dados com elas. Se um campo obrigatório estiver ausente, um valor tiver o tipo errado ou um valor estiver fora do conjunto permitido, o validador reporta o problema específico. A especificação do JSON Schema define esse comportamento de validação em detalhes.

Como um schema define uma requisição válida

Para endpoints que aceitam um corpo de requisição, o schema do corpo de requisição na especificação descreve exatamente como uma carga útil válida deve ser. Muitos endpoints da Braze reutilizam as mesmas estruturas de requisição, como identificadores de usuário, objetos de envio de mensagens e filtros de público. Para uma referência campo a campo dessas estruturas compartilhadas, consulte Objetos e filtros. Considere um schema simplificado para uma requisição que exige uma string external_id e um inteiro points, onde points não pode ser negativo:

1
2
3
4
5
6
7
8

{
  "type": "object",
  "required": ["external_id", "points"],
  "properties": {
    "external_id": { "type": "string" },
    "points": { "type": "integer", "minimum": 0 }
  }
}

Uma carga útil que satisfaz esse schema é válida:

1

{ "external_id": "user-123", "points": 50 }

Cada uma das cargas úteis a seguir é inválida, e um validador explica o motivo:

• { "points": 50 } omite o campo obrigatório external_id.
• { "external_id": "user-123", "points": "50" } envia points como uma string em vez de um inteiro.
• { "external_id": "user-123", "points": -5 } envia um valor que viola a restrição minimum.

Ao ler o schema primeiro, você sabe quais campos enviar, qual tipo cada valor deve ter e quais valores são permitidos — antes mesmo de fazer uma única chamada.

Validar uma requisição contra um schema

Para validar uma carga útil contra o schema de um endpoint:

1. Baixe a spec do endpoint desejado. Cada spec está disponível em uma URL pública e estável no formato https://www.braze.com/docs/assets/api/openapi/{spec_filename}.yaml.
2. Extraia o schema do corpo da requisição a partir da spec.
3. Valide sua carga útil contra esse schema com um validador de JSON Schema, como o Ajv para JavaScript, ou outra biblioteca da lista de ferramentas JSON Schema para a sua linguagem.
4. Corrija qualquer campo que o validador indicar como ausente, com tipo incorreto ou fora do intervalo permitido e, em seguida, envie sua requisição.

Você também pode verificar e validar especificações completas com ferramentas como o Spectral, ou gerar modelos de requisição tipados com o OpenAPI Generator para que seu código produza cargas úteis válidas por construção. Para fluxos de trabalho passo a passo que utilizam essas specs, consulte Como usar os schemas.

Por que a validação de esquema é importante

Validar as requisições com base no esquema ajuda você a:

• Identificar erros mais cedo. Encontre campos ausentes ou digitados incorretamente no seu próprio ambiente, em vez de descobri-los por meio de uma chamada de API rejeitada.
• Reduzir chamadas com falha. Envie requisições bem formadas logo na primeira tentativa, diminuindo novas tentativas e a necessidade de solução de problemas.
• Integrar com confiança. Conte com um contrato único e legível por máquina em vez de copiar formatos de requisição manualmente.
• Automatizar verificações. Adicione validação aos seus testes ou pipeline de CI para que as integrações continuem corretas conforme seu código evolui.

Recursos relacionados

• documentação da braze
• referências externas