Construindo APIs resilientes: CARINE BERTAGNOLLI MÔNICA RIBEIRO práticas de versionamento e documentação

versionamento é uma preocupação pro meu eu do futuro? só que não. não mesmo! ¯\_( ツ)_/¯

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

Hello world :) Carine Bertagnolli Backend Dev @ Zup Mônica Ribeiro Backend Dev Specialist @ Zup

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

APIs resilientes? Ok, mas, o que tem a ver com

resiliência + versionamento = TRANSIÇÕES SUAVES COMPATIBILIDADE RETROATIVA MANUTENÇÃO CONTÍNUA FEEDBACK ITERATIVO

boas práticas de versionamento

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

documentação onde que a documentação entra nisso? por quê? como?

benefícios da documentação + versionamento clareza e compreensão

mudanças controladas benefícios da documentação + versionamento clareza e compreensão

mudanças controladas benefícios da documentação + versionamento compatibilidade clareza e compreensão

mudanças controladas benefícios da documentação + versionamento compatibilidade aviso de descontinuação clareza e compreensão

melhores práticas ESTRUTURA DE DOCUMENTAÇÃO POR VERSÃO Organize sua documentação de forma que cada versão da API tenha sua seção separada.

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.

ferramentas swagger

ferramentas postman

ferramentas insomnia

ferramentas readme

pontos de atenção melhores práticas

1 Use uma convenção de nomenclatura clara e não escolha números arbitrariamente.

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

EXTRA Automatize a segurança das suas APIs. Você pode ficar tranquilo sabendo que sua API está protegida com automação.

obrigada! Carine Bertagnolli Backend Dev @ Zup Mônica Ribeiro Backend Dev Specialist @ Zup

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