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, o corpo da requisição, os 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 nas suas próprias ferramentas.
Você pode enviar uma requisição a partir da referência com Test Request. Insira uma chave da API REST no campo Bearer Token e selecione seu endpoint REST na lista de servidores. A requisição é executada no seu espaço de trabalho e altera dados reais, então use uma chave de um espaço de trabalho de teste. Endpoints que usam PUT, PATCH ou DELETE não podem ser enviados a partir do site de documentação, por isso não exibem Test Request. Para esses endpoints, 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, selecione Download OpenAPI Document na referência ou use o link de download no final da página. Cada arquivo fica em um URL público 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 esquemas de solicitação e resposta. Esses esquemas 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 dado, se o campo é obrigatório, os 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 solicitação e resposta. Para conhecer os objetos e filtros reutilizáveis que muitos endpoints compartilham, consulte Objetos e filtros. Os esquemas ajudam você a:
- Gerar código de cliente e SDKs. Produza modelos tipados de solicitação e resposta, ou uma biblioteca de cliente completa, na linguagem de sua preferência. Assim, você não precisa escrever os corpos das solicitações à mão.
- Validar solicitações e respostas. Verifique as cargas úteis em relação ao esquema antes de enviá-las e confirme se as respostas correspondem ao esperado. Isso ajuda a detectar bugs de integração logo no início.
- Simular a API. Crie um servidor simulado a partir da especificação para compilar e testar com os endpoints da Braze antes de escrever o código de integração em tempo real.
- Importar em clientes de API. Carregue a especificação em ferramentas como Postman ou Insomnia para obter solicitações pré-preenchidas, descrições de parâmetros e preenchimento automático.
- Manter as 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. Depois, atualize sua integração com confiança.
Como usar os esquemas
As instruções a seguir pressupõem que você já baixou um arquivo de especificação na página de um 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, pelos parâmetros e por todos os esquemas que ela define.
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 de destino.
- Use os modelos de solicitação e resposta gerados, ou o cliente completo, na sua aplicação. Assim, você não precisa montar os corpos das solicitações manualmente.
Validar suas cargas úteis
Para confirmar que o corpo de uma solicitação está de acordo com o contrato do endpoint antes de enviá-la:
- Extraia o esquema do corpo da solicitação da especificação.
- Use um validador de JSON Schema, ou uma biblioteca na sua linguagem, para validar sua carga útil com base nesse esquema.
- Corrija os campos que o validador apontar como ausentes, com tipo incorreto ou fora do intervalo permitido.
Importar no Postman ou em outro cliente
Para obter solicitações pré-preenchidas e descrições dos campos em linha:
- 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, em seguida, envie sua solicitação.
Simular o endpoint
Para desenvolver com base em um endpoint antes de escrever o código de integração em produção:
- Carregue a especificação em uma ferramenta de simulação (mock), como o Prism.
- Inicie o servidor de simulação, que retorna respostas compatíveis com os esquemas da especificação.
- Aponte sua aplicação para o servidor de simulação durante o desenvolvimento. Quando estiver tudo pronto, mude para o seu endpoint REST em produção.