"API Design First" pt-br

Uma visão geral de onde a abordagem de criar o contrato da API primeiro pode ser útil.

Apresentação para o curso Fullstack da Python Pro
organizar readme

https://huogerac.hashnode.dev/tres-formas-de-fazer-mock-da-sua-api-com-javascript-or-entenda-onde-isto-te-ajuda

https://pythonpro.com.br/

https://github.com/confraria-devpro/hackernews-clone

Transcript

1. OpenAPI & API design First Roger Camargo Outubro 2021
2. API Application Programming Interface
3. Quem vai consumir nossa API?
4. Backend Data Frontend API Código é a documentação 👉 ✔
5. Backend Data Frontend API Client 2 Onde está a documentação? 🤔
6. Backend Data Client 1 API System A SDK Client JS System B Client 2 😱
7. Backend Data Client 1 API Client 2 System A SDK Client JS System B Internet 😱 😱
8. Como usar sua API? Quais “endpoints”? Quais códigos de retorno? https://http.cat/
9. Soluções: - Documentar depois - Gerar documentação a partir do código - Criar um contrato 1 2
10. Faz funcionar primeiro Quando der a gente volta pra fazer documentação == Nunca vamos fazer a documentação 👉
11. 201 Como documentar uma API? ✔
13. - Implementar a API - Usar swagger e gerar a documentação
17. “Desenho da API primeiro” API Design First approach 🤔
18. “Design first” implica que outras abordagens NÃO pensam na API antes!? Big design up front? 🤔 WAIT...
19. ❌ “Design first” significa escrever uma API de uma forma que humanos e máquinas possam entender! ✔ “Design first” implica que outras abordagem NÃO pensam na API antes!
21. Forma mais comum... Código Documentação
22. Contrato Código Testes Documentação “Schemas” “Client” “Mock” YAML API Design First
23. OpenAPI Specification (OAS3) https://spec.openapis.org/oas/latest.html
24. O que é OAS3? - Contrato para definir APIs RESTful - Open source, padrão que evolui - Coleção de ferramentas - Agnóstico (linguagem) - Para ser entendido por humanos e máquinas
25. O que é API design first? - Guiado por contrato (YAML) - Receber feedback o quanto antes - Fácil para alterar e evoluir - Uma fonte da verdade
26. Por que API design first? - Implementação emergente e descentralizado - Empoderar as pessoas e promover participação de todos na construção da API - Ferramental para facilitar implementação (DRY)
27. Automatic live documentation API Mock server Frontend For quick UX validation Quick feedback Frontend TEAM Backend TEAM Real Implementation API Tests Business Tests Minimize the ReWork YAML
28. Conclusões: - Alguns casos tudo bem não ter documentação - Outros também pode ser interessante ganhar a documentação (geração automática) - Uma implementação guiada por um contrato tem objetivos maiores que apenas gerar documentação
29. References: https://swagger.io/resources/webinars/adopting-a-design-first-approach/ https://apisyouwonthate.com/blog/api-design-first-vs-code-first https://www.openapis.org/ https://spec.openapis.org/oas/latest.html https://www.youtube.com/watch?v=TfGHNBaK9a0 https://http.cat/ Tools: https://github.com/zalando/connexion https://openapi.tools/ https://editor.swagger.io/ https://stoplight.io/ Code sample: https://github.com/billcode/jarless https://github.com/confraria-devpro/hackernews-api Books https://www.goodreads.com/book/show/4099.The_Pragmatic_Programmer API Design First https://pythonpro.com.br
30. Obrigado Keep in touch @huogerac https://huogerac.hashnode.dev huogerac@gmail.com https://speakerdeck.com/huogerac