Versionamento
| Versão | 1.0 |
|---|---|
| Tipo URI Path | https://app.vindi.com.br/api/v1/{recurso} |
Com é o Versionamento de APIs
Versionamento de APIs é o processo de atualizar uma API quando há mudanças em sua estrutura. Utiliza-se o versionamento semântico, onde:
Major (v1, v2, etc.): Indica grandes mudanças que podem quebrar a compatibilidade com versões anteriores.
Minor (v1.1, v1.2, etc.): Para mudanças menores que não afetam a compatibilidade existente.
APIs são consumidas com base em um contrato (swagger), definido pela OpenAPI Specification. Alterações nesse contrato podem quebrar as integrações existentes. Cada organização define suas próprias regras para o que constitui uma "quebra de contrato".
URI Path (PATH URL):
O modelo mais comum, onde a versão é incluída na URI da requisição (e.g., /api/v1/resource). Este método é fácil de configurar e entender, e que usamos nas soluções Vindi por sua simplicidade e clareza.
Inspirado na postagem da Sensedia
Manutenção
A API Vindi está constante processo de evolução e novos métodos ou atributos podem ser adicionados a qualquer momento. Mesmo assim nos comprometemos, sempre que possível, a não efetuar nenhuma mudança que não seja retrocompatível. Nesses casos, uma nova versão será lançada e a versão antiga será mantida por um prazo determinado. Ainda assim, alterações que incompatibilizem implementações existentes poderão ocorrer em casos excepcionais, como por exemplo, em situações que envolvam riscos de segurança.
Considerando que novos atributos podem ser incluídos em métodos existentes, solicitamos que sua implementação não dependa da ordem dos atributos JSON na resposta da API. Faça a referência utilizando os nomes.
Segue abaixo um exemplo de implementação em pseudocódigo que deve ser evitado:
response = get('/api/v1/customers/1001')
customerId = response[0]
customerName = response[1]
customerCode = response[5]
O código acima é extremamente frágil.
Pois caso a Vindi insira um novo atributo no cliente, a implementação deixará de funcionar.
Em vez disso, utilize como referência apenas os nomes definidos na documentação:
response = get('/api/v1/customers/1001')
customerId = response['id']
customerName = response['name']
customerCode = response['code']