Agenda O que é versionamento? O que uma API resiliente tem a ver com isso? INTRODUÇÃO DOCUMENTAÇÃO PONTOS DE ATENÇÃO E, onde a documentação entra nisso? Essa parte é importante, ein? Boas práticas e ferramentas para usar ao nosso favor. BOAS PRÁTICAS
o que é versionamento? uma forma de diferenciar pontos no tempo em que a API muda de uma forma que exige que os consumidores da API modifiquem seu aplicativo.
quando aplicar? MAJOR MINOR PATCH quando impacta em breaking changes pode ser ignorado por clientes que não querem usar esses novos recursos. são pequenas mudanças que não afetam códigos. Mudanças (renomear ou excluir) em campos ou rotas. Alteração de payload. Remoção endpoints para corrigir HTTP design. novas features, métodos ou recursos. atualizações de documentações semantic versioning
URI PATH https://apiexample.com/api/v1/categories PRÓS Fácil de usar. Não requer ferramenta extra. Estratégias de cache vão se beneficiar. CONTRAS Pode gerar várias versões com alguns conflitos (ambiguidade, cache, manutenção etc). Viola um dos princípios REST.
QUERY STRING PARAMETER https://apiexample.com/api/categories?v=1.1 PRÓS Fácil de implementar e usar. Pode definir versão mais recente como padrão. CONTRAS Pode quebrar links permanentes.
curl -H “accepts-version: v1” https://apiexample.com/api/categories PRÓS Não adiciona preenchimento na URI Subversões podem ser adicionadas como cabeçalhos. CONTRAS Complexidade ao gerenciar configuração de versões. Difícil de armazenar cache. CUSTOM HEADERS
GET https://apiexample.com/api/categories Accept: application/vnd.exmaple.api+json;version=2 PRÓS Não adiciona preenchimento na URI Não quebra tipos de metadados de documentos correspondentes. CONTRAS É necessário uso de ferramentas pra explorar todas versões. Pode se tornar de difícil gerenciamento para clientes. CONTENT NEGOTIATION
melhores práticas ESTRUTURA DE DOCUMENTAÇÃO POR VERSÃO DESTAQUE AS DIFERENÇAS Organize sua documentação de forma que cada versão da API tenha sua seção separada. Forneça uma seção destacada que descreva as principais diferenças entre as versões.
melhores práticas ESTRUTURA DE DOCUMENTAÇÃO POR VERSÃO DESTAQUE AS DIFERENÇAS EXEMPLOS DE MIGRAÇÃO Organize sua documentação de forma que cada versão da API tenha sua seção separada. Forneça uma seção destacada que descreva as principais diferenças entre as versões. Se houver mudanças que afetem a integração de maneira significativa, forneça exemplos claros de migração da versão anterior para a nova.
melhores práticas ESTRUTURA DE DOCUMENTAÇÃO POR VERSÃO DESTAQUE AS DIFERENÇAS EXEMPLOS DE MIGRAÇÃO INDICADORES DE OBSOLESCÊNCIA Organize sua documentação de forma que cada versão da API tenha sua seção separada. Forneça uma seção destacada que descreva as principais diferenças entre as versões. Se houver mudanças que afetem a integração de maneira significativa, forneça exemplos claros de migração da versão anterior para a nova. Se uma versão mais antiga estiver prestes a ser descontinuada, destaque essa informação na documentação.
1 Use uma convenção de nomenclatura clara e não escolha números arbitrariamente. Defina um cronograma para versões obsoletas ou permita APIs side-by-side. 2
Tenha documentação clara e detalhada estabelecendo suas diretrizes de controle de versão. 1 Use uma convenção de nomenclatura clara e não escolha números arbitrariamente. Defina um cronograma para versões obsoletas ou permita APIs side-by-side. 2 3
Tenha documentação clara e detalhada estabelecendo suas diretrizes de controle de versão. Faça adições compatíveis com versões anteriores. Seus clientes agradecerão! 1 Use uma convenção de nomenclatura clara e não escolha números arbitrariamente. Defina um cronograma para versões obsoletas ou permita APIs side-by-side. 2 3 4
Obrigada pelo seu tempo Nos vemos em breve! :) 21/09 Trilha Microsservices (14:10) Além do olho mágico: monitorando a integridade dos microsserviços com o OpenTelemetry 21/09 Trilha Arquitetura Java (17:15 às 17:50) Decisões arquiteturais: o que se encaixa no meu projeto? 20/09 Trilha Design de Código (11:15) Transformando o caos em clareza: o poder da refatoração
monicaribeiro
ohakutsu
h0r15h0
kasacchiful
ivargrimstad
skanehira
niftycorp
codehex
morikann
aridlehoover
ivanova1991
yahiru
zerebom
bcantrill
lauravandoore
addyosmani
jcasabona
eileencodes
garrettdimon
marcduiker
afnizarnur
smashingmag
skipperchong
vanstee
paulrobertlloyd