Caravana Cloud: Como testar e documentar REST APIs com ScanAPI

Essa semana passamos pelo Módulo 04 do conteúdo do nosso Programa de Mentoria e nessa sexta-feira teremos a ilustre participação da @cmaiacd que vai conversar com nossos mentorados sobre REST APIs e o projeto open source dela - o @scanapi\_ - ao vivo na mentoria coletiva! 🤩

https://twitter.com/CaravanaCloud/status/1408084280497127426?ref_src=twsrc%5Etfw

Caravana Cloud: http://site.caravana.cloud

Transcript

1. Como testar e documentar REST APIs com ScanAPI
   Caravana Cloud - Jun 2021
   Camila Maia
   

   View Slide

2. Esta apresentação está disponível em:
   speakerdeck.com/cmaiacd
   

   View Slide

3. Quem sou eu?
   - Desenvolvedora Backend
   - 10+ anos xp 👵
   - Python 🐍 e Ruby 💎
   - OpenSource e Comunidades ❤
   - Organização de eventos:
   Pyjamas, EuroPython, Python Brasil….
   

   View Slide

4. - Primeiro perfil aprovado no
   programa de Sponsors para quem
   reside no Brasil 󰎙
   Quem sou eu?
   

   View Slide

5. Testes Automatizados 🤖
   

   View Slide

6. ● São rotinas que verificam o funcionamento do seu código
   ● Substituem os teste manuais
   ● Economizam seu tempo
   ● Não apenas identificam problemas, eles os evitam
   ● Ajudam no trabalho em equipe
   ● Garantem código de qualidade e robusto
   Testes
   O quê são?
   

   View Slide

7. Testes
   ● Alguns testes podem se aplicar pequenos detalhes do sistema.
   Um método de modelo específico retorna valores conforme o esperado?
   ● Outros examinam a operação geral do sistema
   Uma sequência de entradas do usuário no site produz o resultado
   desejado?
   ● Existem os que avaliam a comunicação entre sistemas
   Os diferentes tipos
   

   View Slide

8. Motivação
   

   View Slide

9. Motivação
   Tudo começou numa bela semana de firefighter… 🔥
   

   View Slide

10. Motivação
    Erros de integração 💥
    API de Terceiros
    API interna
    (Backend)
    Frontend
    

    View Slide

11. - Endpoints e campos faltantes
    - Desinformação
    Motivação
    Documentação desatualizada 📜
    

    View Slide

12. /reservar/:id_do_assento
    id_do_voo?
    id_da_aeronave?
    id_do_passageiro?
    Aeronave está disponível?
    ????
    Motivação
    Dificuldade em recriar o cenário 😤
    

    View Slide

13. Motivação
    Dificuldade em recriar o cenário 😤
    

    View Slide

14. Motivação
    Erros de integração 💥
    API de Terceiros
    API interna
    (Backend)
    Frontend
    

    View Slide

15. View Slide

16. View Slide

17. ● Framework de código aberto
    ● Command line interface (CLI)
    ● Escrito em Python
    Objetivos:
    1. Fornecer Live Documentation
    2. Possibilitar a implementação de Testes de Integração
    O quê é?
    

    View Slide

18. PokéAPI: https://pokeapi.co
    $ http https://pokeapi.co/api/v2/pokemon/
    Como funciona?
    Exemplo: PokéAPI
    

    View Slide

19. Como funciona?
    ● Python
    ● $ pip install scanapi
    Exemplo: PokéAPI
    

    View Slide

20. # scanapi.yaml
    endpoints:
    - name: pokeapi
    path: https://pokeapi.co/api/v2/
    endpoints:
    - name: pokemon
    path: pokemon
    requests:
    - name: list_all
    method: get
    path: /
    Como funciona?
    Exemplo: PokéAPI
    path: https://pokeapi.co/api/v2/ pokemon /
    name: pokeapi :: pokemon :: list_all
    

    View Slide

21. Como funciona?
    Executar...
    Exemplo: PokéAPI
    

    View Slide

22. Documentação 📄
    

    View Slide

23. ● import requests
    ● response = requests.get("https://pokeapi.co/api/v2/pokemon/")
    ● dir(response)
    ● response.status_code
    ● response.headers
    ● response.elapsed.total_seconds()
    ● response.json()
    https://requests.readthedocs.io
    Python requests
    

    View Slide

24. ...
    requests:
    - name: list_all
    method: get
    path: /
    tests:
    - name: status_code_is_200
    assert: ${{ response.status_code == 200 }}
    - name: response_time_is_under_half_second
    assert: ${{ response.elapsed.total_seconds() < 0.5 }}
    - name: results_length_is_20
    assert: ${{ len(response.json()["results"]) == 20 }}
    - name: count_is_gte_1118
    assert: ${{ response.json()["count"] >= 1118 }}
    Como funciona?
    Testes de Integração ✅
    

    View Slide

25. Testes de Integração ✅
    

    View Slide

26. Como funciona?
    - Pegar detalhes de um Pokémon
    - Neste caso o dado é “estático”, mas poderia não ser
    https://pokeapi.co/api/v2/pokemon/bulbasaur
    Encadeamento ⛓
    

    View Slide

27. Como funciona?
    ...
    endpoints:
    - name: pokemon
    path: pokemon
    requests:
    - name: list_all
    method: get
    path: /
    vars:
    pokemon_name: ${{ response.json()["results"][0]["name"] }}
    tests: ...
    - name: details
    method: get
    path: ${pokemon_name} pokemon/${pokemon_name}
    

    View Slide

28. Encadeamento ⛓
    

    View Slide

29. Como funciona?
    E tem mais 🎉
    - Especificação também é aceita em JSON
    - Especificação em vários arquivos
    - Delay entre requests
    - Relatórios Customizados
    - VS Code Plugin
    

    View Slide

30. scanapi.dev 🌐
    

    View Slide

31. scanapi/examples
    

    View Slide

32. Por que utilizar ScanAPI? 8 motivos!
    1. Funciona para qualquer API REST
    2. Excelente para testar e documentar APIs próprias e de terceiros
    3. É possível encadear requests, o que é essencial para testar cenários
    complexos
    4. A documentação é gerada automaticamente, ela nunca fica desatualizada
    5. É simples. A sintaxe é simples e não requer quase nenhum conhecimento
    específico da linguagem
    6. É extremamente flexível
    7. É seguro
    8. Não há nada no mercado que faça o que o ScanAPI faz
    

    View Slide

33. GitHub
    - https://github.com/scanapi
    Twitter
    - @ScanAPI_
    Discord
    - discord.scanapi.dev
    Comunicação
    Bora trocar uma ideia! 🗣
    

    View Slide

34. github.com/scanapi ⭐
    

    View Slide

35. Bora usar!
    

    View Slide

36. E compartilhar! 🚀
    

    View Slide

37. MUITO OBRIGADA!
    @cmaiacd camilamaia
    󰠁
    cmaiacd.com
    

    View Slide