APIs com contrato claro, versão e documentação
Desenhamos e desenvolvemos APIs para o seu site, o seu app e os seus parceiros, com contrato escrito antes do código, versões e testes.
Para quem é
Para empresas que precisam abrir dados ou operações para apps, parceiros ou outros sistemas.
O que resolve
- Cada parceiro recebeu uma integração diferente, e manter todas virou um trabalho à parte.
- Uma mudança na API quebrou o app de quem já estava integrado.
- A documentação está desatualizada e o suporte responde dúvidas que ela deveria responder.
- Os erros voltam como mensagens genéricas e o parceiro não sabe o que corrigir.
O que fazemos
- Contrato antes do código
- A API descrita em OpenAPI e revisada por quem vai consumi-la, antes da implementação.
- Recursos e erros
- Nomes, paginação, filtros e mensagens de erro que dizem o que deu errado e como corrigir.
- Versões sem quebrar ninguém
- Política de versões e prazo de aviso antes de desativar algo que alguém usa.
- Autenticação e permissões
- Quem pode chamar o quê: chaves de API, OAuth e escopos por parceiro.
- Limites de uso
- Limites por cliente para que um parceiro não derrube a API para os outros.
- Ambiente de testes
- Um sandbox com dados fictícios para os parceiros testarem antes de entrar em produção.
- Testes de contrato
- Testes automáticos que avisam quando uma mudança quebra o que foi combinado.
O que você recebe
- Especificação OpenAPI da API, versionada no repositório
- API em produção, com autenticação, limites de uso e logs
- Documentação de referência e guia de primeiros passos para parceiros
- Sandbox com dados fictícios para testes de integração
- Testes automáticos de contrato rodando a cada mudança
Como fazemos
Quem consome
Quem vai usar a API, para quê e com que volume.
Contrato
Especificação escrita e revisada com a sua equipe e com um parceiro, se houver.
Desenvolvimento
Implementação seguindo o contrato, com testes que conferem cada resposta.
Sandbox e documentação
Ambiente de testes e guias publicados antes da produção.
Publicação
Entrada em produção com monitoramento de erros e de uso por cliente.
Exemplos de tecnologia
- OpenAPI
- GraphQL
- gRPC
- OAuth 2.0
- NestJS
- Spring Boot
- Pact
Serviços relacionados
Perguntas frequentes
REST, GraphQL ou gRPC?
Depende de quem consome. Para parceiros externos, REST com OpenAPI costuma ser o mais simples de adotar. GraphQL e gRPC entram quando o caso pede.
Vocês também fazem o app ou o site?
Não. Fazemos a API e combinamos o contrato com a sua equipe de front-end ou de app. Veja back-end para apps e front-end.
Dá para documentar uma API que já existe?
Sim. Descrevemos a API atual em OpenAPI, apontamos inconsistências e propomos uma versão nova sem quebrar quem já usa.
Como os parceiros ficam sabendo de uma mudança?
Pela política de versões: a mudança chega numa versão nova, a antiga continua funcionando por um prazo combinado e os parceiros recebem aviso com antecedência.
Escreva para a Balkan
Falar sobre o seu projeto