Construindo APIs resilientes: práticas de versionamento e documentação

Palestra feita no evento TDC Business no dia 19 de Setembro de 2023.

Transcript

1. Construindo APIs resilientes: CARINE BERTAGNOLLI MÔNICA RIBEIRO práticas de versionamento e documentação
2. versionamento é uma preocupação pro meu eu do futuro? só que não. não mesmo! ¯\_( ツ)_/¯
3. 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
4. Hello world :) Carine Bertagnolli Backend Dev @ Zup Mônica Ribeiro Backend Dev Specialist @ Zup
5. 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.
6. 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
7. APIs resilientes? Ok, mas, o que tem a ver com
8. resiliência + versionamento = TRANSIÇÕES SUAVES COMPATIBILIDADE RETROATIVA MANUTENÇÃO CONTÍNUA FEEDBACK ITERATIVO
9. boas práticas de versionamento
10. 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.
11. 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.
12. 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
13. 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
14. documentação onde que a documentação entra nisso? por quê? como?
15. benefícios da documentação + versionamento clareza e compreensão
16. mudanças controladas benefícios da documentação + versionamento clareza e compreensão
17. mudanças controladas benefícios da documentação + versionamento compatibilidade clareza e compreensão
18. mudanças controladas benefícios da documentação + versionamento compatibilidade aviso de descontinuação clareza e compreensão
19. 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.
20. 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.
21. 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.
22. 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.
23. ferramentas swagger
24. ferramentas postman
25. ferramentas insomnia
26. ferramentas readme
27. pontos de atenção melhores práticas
28. 1 Use uma convenção de nomenclatura clara e não escolha números arbitrariamente.
29. 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
30. 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
31. 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
32. EXTRA Automatize a segurança das suas APIs. Você pode ficar tranquilo sabendo que sua API está protegida com automação.
33. obrigada! Carine Bertagnolli Backend Dev @ Zup Mônica Ribeiro Backend Dev Specialist @ Zup
34. 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