PrograMaria 2021

# Como testar e documentar REST APIs com ScanAPI

https://www.programaria.org/programariasummit2021/

https://www.programaria.org/programariasummit2021/brilha/

Transcript

1. Como testar e documentar REST APIs com ScanAPI
   PrograMaria - Set 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. Motivação
   Tudo começou numa bela semana de firefighter… 🔥
   

   View Slide

6. Motivação
   Erros de integração 💥
   - Clientes enviando campos
   diferentes do esperado
   - Frontend recebendo campos
   diferentes do esperado
   

   View Slide

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

   View Slide

8. /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

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

   View Slide

10. View Slide

11. View Slide

12. ● 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

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

    View Slide

14. View Slide

15. View Slide

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

    View Slide

17. # 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

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

    View Slide

19. Documentação 📄
    

    View Slide

20. Documentação 📄
    

    View Slide

21. Documentação 📄
    

    View Slide

22. Documentação 📄
    

    View Slide

23. ...
    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?
    https://requests.readthedocs.io
    Testes de Integração ✅
    

    View Slide

24. 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. Próximos passos
    E o futuro? 🔮
    ● Foco: aumentar a adoção da ferramenta. Divulgação!
    Falando em novas features, e se….
    ● Exportar: OpenAPI, Postman Collection, Insomnia…
    Esforço quase nulo para adoção!
    

    View Slide

33. 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

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

    View Slide

35. github.com/scanapi ⭐
    

    View Slide

36. Bora usar!
    

    View Slide

37. E compartilhar! 🚀
    

    View Slide

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

    View Slide