Prisma
Trabalhar com APIs é ótimo, mas às vezes você não precisa usar a API real para realizar o trabalho de desenvolvimento. Uma ferramenta que pode ser útil incluir no seu fluxo de trabalho de desenvolvimento é Prisma de Semáforo. O Prism é um servidor simulado que imita nossas APIs ativas. Você pode executá-lo localmente para testar suas chamadas de API durante o desenvolvimento, sem incorrer em nenhum custo de uso.
A Prism entende que o OpenAPI especificações que publicamos para cada uma de nossas APIs; assim, você pode usar essa abordagem para trabalhar com qualquer uma das APIs da Vonage.
Instalar o Prism
O Prism é uma ferramenta do Node.js; portanto, você precisará ter o Node.js instalado localmente. Completo documentação e instruções de instalação estão disponíveis, mas a versão resumida é uma npm install comando:
npm install -g @stoplight/prism-cli
Verifique se o comando está instalado e funcionando executando prism --version a partir de um terminal.
Obtenha a especificação OpenAPI
Para encontrar a especificação OpenAPI de qualquer uma de nossas APIs, acesse essa API a partir da Página inicial da documentação. Selecione a referência da API no menu à esquerda e use o botão de download em YAML para baixar a especificação da API.
Depois de ter o .yml arquivo desejado, você está pronto para iniciar o Prism.
Inicie um servidor simulado com o Prism
No terminal, inicie o prism com um comando como este:
prism mock [api-spec.yml]
Por exemplo, no caso da Number Insight API, meu comando e sua saída ficam assim:
$ prism mock number-insight.yml
[12:13:06] › [CLI] … awaiting Starting Prism…
[12:13:06] › [CLI] ℹ info GET http://127.0.0.1:4010/basic/json?number=1%295-2%209%2B2&country=UV
[12:13:06] › [CLI] ℹ info GET http://127.0.0.1:4010/standard/xml?number=67-64%298427&country=OU&cnam=false
[12:13:06] › [CLI] ℹ info GET http://127.0.0.1:4010/advanced/async/json?callback=sunt%20deserunt%20dolore%20id&number=%2B1208&country=CM&cnam=false&ip=accusamus
[12:13:06] › [CLI] ℹ info GET http://127.0.0.1:4010/advanced/xml?number=-47&country=MU&cnam=false&ip=non
[12:13:06] › [CLI] ▶ start Prism is listening on http://127.0.0.1:4010
A última linha da saída mostra onde o Prism está em execução; no meu caso, é localmente na porta 4010.
Fazer solicitações de API ao Prism
Usando a URL exibida na saída de inicialização do Prism como URL base, utilize seu cliente HTTP preferido para testar a API de exemplo. O exemplo acima utilizou a Number Insight API; portanto, você poderia fazer uma solicitação via curl da seguinte forma:
curl "http://localhost:4010/basic/json?api_key=abcd1234&api_secret=VerySecret1&number=44777000777"
A resposta do Prism possui os mesmos campos que a API ativa e alguns valores de exemplo, o que a torna um substituto ideal para a “versão real” durante os testes.
Para uma maneira ainda mais fácil de trabalhar com o Prism e fazer solicitações de API, experimente importar a mesma especificação OpenAPI que você forneceu ao Prism para o Postman e use a coleção de solicitações já pronta. Ao alterar o {{baseUrl}} variável, você pode usar rapidamente o Postman e o Prism para explorar a estrutura de qualquer API da Vonage sem custos.
Use o Prism com seu aplicativo
Todos os nossos SDKs oferecem suporte para alterar a URL base para a qual as solicitações de API são direcionadas (conforme detalhado no README (de cada uma das bibliotecas) para permitir que você utilize outros endpoints para testes.
Uso avançado do Prism
Depois que você se familiarizar com o Prism, aqui vão algumas dicas para levar seu conhecimento a um novo patamar.
Solicitar uma resposta específica
Nossas APIs podem retornar respostas de erro em algumas situações, e pode ser difícil recriar essas situações de erro na plataforma em produção. O uso do Prism oferece a oportunidade de testar as aplicações em relação a todas as respostas possíveis.
Algumas de nossas especificações de API contêm respostas de erro descritas em detalhes, e você pode usar o nome da resposta para solicitar que o Prism a retorne.
Por exemplo, na API Verify, você encontrará isso nas respostas de exemplo da especificação da API:
examples:
success:
summary: Request was started
value:
request_id: abcdef0123456789abcdef0123456789
status: "0"
throttled:
summary: Request limit exceeded
value:
status: "1"
error_text: Throttled
account-disabled:
summary: Account is barred
value:
status: "8"
error_text: The api_key you supplied is for an account that has been barred from submitting messages.
rejected:
summary: Rejected
value:
status: "15"
error_text: The destination number is not in a supported network
Por padrão, o Prism retorna a primeira resposta, o que é ótimo; esse é um bom exemplo do que a API costuma retornar.
No entanto, verificar se o seu código lida com algumas dessas outras respostas possíveis não seria o ideal. É aí que o Prism pode ajudar bastante! Ao anexar um __example parâmetro à sua solicitação, você pode selecionar qual dos exemplos o Prism deve retornar. Por exemplo, para enviar uma solicitação via curl à API Verify, mas fazer com que ela retorne a resposta “throttled”, ficaria assim:
curl "http://localhost:4010/json?api_key=abcd1234&api_secret=VerySecret1&number=44777000777&brand=Test&__example=throttled"
Ao usar o Prism dessa maneira, você pode verificar o comportamento do seu aplicativo com todas as respostas que a API pode retornar.
Melhor manuseio de JSON com o JQ
Se você estiver trabalhando com JSON na linha de comando, como nos exemplos do curl mostrados aqui, experimente a ferramenta jq para aprimorar a maneira como você trabalha com JSON. É um excelente formatador por si só e pode extrair campos específicos da resposta ou processar os dados de outras maneiras também.
Na sua forma mais simples, use-o para obter uma saída mais agradável do exemplo do curl que usamos quando testamos o Prism pela primeira vez:
curl "http://localhost:4010/basic/json?api_key=abcd1234&api_secret=VerySecret1&number=44777000777" | jq "."