Usando as especificações OpenAPI da Braze
Este artigo de referência explica como a Braze publica especificações OpenAPI para seus endpoints de REST API e como você pode usar os schemas nessas especificações para acelerar seus fluxos de trabalho de desenvolvimento.
Cada página de endpoint de REST API da Braze exibe uma referência interativa gerada a partir de uma especificação OpenAPI. A referência mostra os parâmetros do endpoint, corpo da requisição, schemas de resposta e exemplos de resposta em um formato consistente e estruturado. Cada especificação também é um arquivo legível por máquina que você pode baixar e usar diretamente em suas próprias ferramentas.
A referência em cada página de endpoint é somente leitura. Ela não envia requisições reais a partir do site de documentação. Para chamar um endpoint, copie o exemplo cURL gerado ou use a especificação baixada no seu próprio cliente, conforme descrito em Como usar os schemas.
Onde encontrar uma especificação
Em qualquer página de endpoint da REST API, encontre a seção Endpoint reference. Para abrir a especificação bruta, use a opção de download de especificação nessa seção. Cada arquivo está em uma URL pública e estável no seguinte formato:
https://www.braze.com/docs/assets/api/openapi/{spec_filename}.yaml
Cada arquivo é um documento OpenAPI 3 único e independente para um endpoint. O documento inclui os schemas de requisição e resposta que descrevem o formato exato dos dados que o endpoint aceita e retorna.
Por que os esquemas são valiosos
Um esquema é o contrato estruturado de um endpoint: ele define o nome de cada campo, o tipo de dados, se o campo é obrigatório, seus valores permitidos e como os objetos se aninham. Como esse contrato é legível por máquina, você pode confiar nele em vez de copiar manualmente os formatos de requisições e respostas. Para os objetos e filtros reutilizáveis compartilhados por vários endpoints, consulte Objetos e filtros. Os esquemas ajudam você a:
- Gerar código de cliente e SDKs. Produzir modelos tipados de requisição e resposta, ou uma biblioteca de cliente completa, na sua linguagem preferida, sem precisar escrever manualmente os corpos das requisições.
- Validar requisições e respostas. Verificar as cargas úteis em relação ao esquema antes de enviá-las e confirmar que as respostas correspondem ao esperado, o que detecta bugs de integração mais cedo.
- Simular a API. Criar um servidor mock a partir da especificação para que você possa desenvolver e testar contra os endpoints da Braze antes de escrever código de integração em tempo real.
- Importar em clientes de API. Carregar a especificação em ferramentas como Postman ou Insomnia para obter requisições pré-preenchidas, descrições de parâmetros e autocompletar.
- Manter integrações sincronizadas. Comparar uma cópia armazenada de uma especificação com a versão atual para detectar quando um campo é adicionado ou alterado e, então, atualizar sua integração com confiança.
Como usar os esquemas
As instruções a seguir assumem que você já baixou um arquivo de especificação de uma página de endpoint.
Visualizar e explorar uma especificação
Para ler uma especificação em uma visualização estruturada e interativa, use qualquer visualizador OpenAPI:
- Baixe o arquivo de especificação do endpoint desejado.
- Abra o Swagger Editor ou um visualizador semelhante.
- Cole ou faça upload do arquivo para navegar pela operação, seus parâmetros e todos os esquemas definidos.
Gerar um cliente ou modelos
Para transformar um esquema em código tipado na sua linguagem, use um gerador OpenAPI:
- Instale um gerador como o OpenAPI Generator.
- Aponte o gerador para o arquivo de especificação e selecione a linguagem desejada.
- Use os modelos de request e response gerados, ou o cliente completo, na sua aplicação em vez de construir corpos de requisição manualmente.
Validar suas cargas úteis
Para confirmar que o corpo de uma requisição corresponde ao contrato do endpoint antes de enviá-lo:
- Extraia o esquema do corpo da requisição a partir da especificação.
- Use um validador de JSON Schema, ou uma biblioteca na sua linguagem, para validar sua carga útil em relação a esse esquema.
- Corrija quaisquer campos que o validador indicar como ausentes, com tipo incorreto ou fora do intervalo permitido.
Importar para o Postman ou outro cliente
Para obter requisições pré-preenchidas e descrições de campos inline:
- No Postman, selecione Import e escolha o arquivo de especificação baixado.
- O Postman cria uma coleção com o endpoint, seus parâmetros e valores de exemplo.
- Adicione sua chave da API REST e o endpoint REST de destino e envie sua requisição.
Simular o endpoint
Para desenvolver contra um endpoint antes de escrever o código de integração em tempo real:
- Carregue a especificação em uma ferramenta de mock, como o Prism.
- Inicie o servidor de mock, que retorna respostas compatíveis com os esquemas da especificação.
- Aponte sua aplicação para o servidor de mock durante o desenvolvimento e depois mude para o seu endpoint REST em tempo real quando estiver tudo pronto.