Ir para o conteúdo

Esta página foi traduzida automaticamente e pode conter imprecisões. Para relatar um erro de tradução, use o componente de feedback na parte inferior do sumário, à direita da página.

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 schema OpenAPI

Um schema é o contrato para os dados de um endpoint. Em um documento OpenAPI, o Schema Object define cada campo que um endpoint usa, 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 schemas 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 contra ele usando 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 conjunto pequeno de blocos de construção. Os mais comuns são:

Tipo. O tipo de dados de um valor, como string, integer, number, boolean, array ou object. Consulte Data types na documentação do Swagger.
Campos obrigatórios. Uma lista das propriedades que devem 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 complexas.

Um validador lê essas regras e compara seus dados contra 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 um external_id do tipo string e um points do tipo inteiro, onde points não pode ser negativo:

{
  "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:

{ "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 de fazer uma única chamada.

Validar uma requisição contra um schema

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

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

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

Por que a validação de schema é importante

Validar requisições contra o schema ajuda você a:

Identificar erros mais cedo. Encontre campos ausentes ou com tipo incorreto no seu próprio ambiente, em vez de a partir de uma chamada de API rejeitada.
Reduzir chamadas com falha. Envie requisições bem formadas logo na primeira vez, reduzindo tentativas repetidas e tempo de solução de problemas.
Integrar com confiança. Baseie-se em um contrato único e legível por máquina, em vez de copiar estruturas 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.

Documentação da Braze:

Referências externas:

New Stuff!