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 de REST API, encontre a seção Endpoint reference. Para abrir a especificação bruta, use a opção de download da 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 autocontido para um endpoint. O documento inclui os schemas de requisição e resposta que descrevem a forma exata dos dados que o endpoint aceita e retorna.
Por que os schemas são valiosos
Um schema é o contrato estruturado de um endpoint: ele define o nome de cada campo, o tipo de dado, 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 as estruturas de requisição e resposta. Para os objetos e filtros reutilizáveis que muitos endpoints compartilham, consulte Objetos e filtros. Os schemas ajudam você a:
- Gerar código de cliente e SDKs. Produza modelos tipados de requisição e resposta, ou uma biblioteca de cliente completa, na sua linguagem preferida para não precisar escrever corpos de requisição manualmente.
- Validar requisições e respostas. Verifique as cargas úteis em relação ao schema antes de enviá-las e confirme se as respostas correspondem ao esperado, o que detecta bugs de integração mais cedo.
- Simular a API. Crie um servidor mock a partir da especificação para que você possa construir e testar contra os endpoints da Braze antes de escrever código de integração real.
- Importar para clientes de API. Carregue a especificação em ferramentas como Postman ou Insomnia para obter requisições preenchidas, descrições de parâmetros e autocompletar.
- Manter integrações sincronizadas. Compare uma cópia armazenada de uma especificação com a versão atual para detectar quando um campo é adicionado ou alterado, e então atualize sua integração com confiança.
Como usar os schemas
As instruções a seguir pressupõem 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 similar.
- Cole ou faça upload do arquivo para navegar pela operação, seus parâmetros e cada schema definido.
Gerar um cliente ou modelos
Para transformar um schema 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 sua linguagem de destino.
- Use os modelos de requisição e resposta 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 um corpo de requisição corresponde ao contrato do endpoint antes de enviá-lo:
- Extraia o schema 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 schema.
- Corrija quaisquer campos que o validador indicar como ausentes, com tipo incorreto ou fora do intervalo.
Importar para o Postman ou outro cliente
Para obter requisições preenchidas e descrições inline dos campos:
- 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 então envie sua requisição.
Simular o endpoint
Para construir contra um endpoint antes de escrever código de integração real:
- Carregue a especificação em uma ferramenta de mock, como o Prism.
- Inicie o servidor mock, que retorna respostas que correspondem aos schemas da especificação.
- Aponte sua aplicação para o servidor mock enquanto desenvolve, e então mude para o seu endpoint REST real quando estiver pronto.