Slide 1

Slide 1 text

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

Slide 2

Slide 2 text

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

Slide 3

Slide 3 text

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

Slide 4

Slide 4 text

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

Slide 5

Slide 5 text

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.

Slide 6

Slide 6 text

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

Slide 7

Slide 7 text

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

Slide 8

Slide 8 text

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

Slide 9

Slide 9 text

boas práticas de versionamento

Slide 10

Slide 10 text

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.

Slide 11

Slide 11 text

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.

Slide 12

Slide 12 text

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

Slide 13

Slide 13 text

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

Slide 14

Slide 14 text

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

Slide 15

Slide 15 text

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

Slide 16

Slide 16 text

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

Slide 17

Slide 17 text

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

Slide 18

Slide 18 text

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

Slide 19

Slide 19 text

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.

Slide 20

Slide 20 text

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.

Slide 21

Slide 21 text

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.

Slide 22

Slide 22 text

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.

Slide 23

Slide 23 text

ferramentas swagger

Slide 24

Slide 24 text

ferramentas postman

Slide 25

Slide 25 text

ferramentas insomnia

Slide 26

Slide 26 text

ferramentas readme

Slide 27

Slide 27 text

pontos de atenção melhores práticas

Slide 28

Slide 28 text

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

Slide 29

Slide 29 text

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

Slide 30

Slide 30 text

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

Slide 31

Slide 31 text

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

Slide 32

Slide 32 text

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

Slide 33

Slide 33 text

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

Slide 34

Slide 34 text

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