$30 off During Our Annual Pro Sale. View Details »

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

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

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

Mônica Ribeiro

September 19, 2023
Tweet

More Decks by Mônica Ribeiro

Other Decks in Programming

Transcript

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

    View Slide

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

    View Slide

  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

    View Slide

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

    View Slide

  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.

    View Slide

  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

    View Slide

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

    View Slide

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

    View Slide

  9. boas práticas de
    versionamento

    View Slide

  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.

    View Slide

  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.

    View Slide

  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

    View Slide

  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

    View Slide

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

    View Slide

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

    View Slide

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

    View Slide

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

    View Slide

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

    View Slide

  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.

    View Slide

  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.

    View Slide

  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.

    View Slide

  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.

    View Slide

  23. ferramentas
    swagger

    View Slide

  24. ferramentas
    postman

    View Slide

  25. ferramentas
    insomnia

    View Slide

  26. ferramentas
    readme

    View Slide

  27. pontos de
    atenção
    melhores práticas

    View Slide

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

    View Slide

  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

    View Slide

  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

    View Slide

  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

    View Slide

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

    View Slide

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

    View Slide

  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

    View Slide