Design First Web APIs - OpenAPI 3

Design first web APIs and why Django did not help!

Transcript

1. Design first APIs and why Django did not help! by Roger Camargo - Jun/2021
2. Design first APIs and why Django did not help! WEB by Roger Camargo - Jun/2021
3. DISCLAIMER
4. Why API?
5. Backend Data Frontend API Code is the documentation. (It’s okay) 👉
6. Backend Data Client 1 API Client 2 Where is the API documentation? 👉
7. Backend Data Client 1 API System A SDK Client JS System B Client 2
8. Backend Data Client 1 API Client 2 System A SDK Client JS System B Internet It can be hard to keep an API documentation updated... 👉
9. How to use your API? What are the endpoints? Methods? Status codes??
10. How to use your API? What are the endpoints? Methods? Status codes?? https://http.cat/
11. /users Code-First, Write Docs "When We Have Time" 👉 It means "We will not write documentation"
12. 201 API Specs/Docs
13. 👉 It can fail to maintain parity between our documentation and our underlying implementation API Specs/Docs
14. OpenAPI Specification (OAS3)
15. What is OAS3? - Contract for defining RESTful APIs - Source of truth for everyone - Open source, evolving standard - Collection of tools - Language-agnostic - Readable by both humans and machines
16. What is OAS3? - Design by contract (YAML) (The pragmatic programmer) - Get feedback on the API before coding - Easier to make changes - One source of truth - Generate code, mock, tests, docs etc...
17. Wait... Big design up front?
18. https://editor.swagger.io/ 👉 One source of truth
19. https://github.com/zalando/connexion 👉
20. Low coupling, High cohesion
21. api.py YAML service.py (CONTRACT) Routes Request validation Response validation Schema casting FACADE API Layer Business Layer DATA ORM
22. Django land...
23. Models Managers TEMPLATE FILTERS Exception Middlewares View Exception Handlers
24. /polls/
25. Django It’s hard to produce API Guided by the YAML contract...
26. However, there is django-ninja DOCS Code first, but there is an API documentation 👉
27. The design first way… (Flask, Falcon etc…)
28. 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
29. Design first API Links: https://swagger.io/resources/webinars/adopting-a-design-first-approach/ https://apisyouwonthate.com/blog/api-design-first-vs-code-first https://docs.djangoproject.com/en/3.2/ref/request-response/ https://www.openapis.org/ https://github.com/zalando/connexion https://http.cat/ Tools: https://editor.swagger.io/ https://stoplight.io/ Code sample: https://github.com/billcode/jarless Books https://www.goodreads.com/book/show/4099.The_Pragmatic_Programmer
30. THANK YOU Keep in touch @huogerac https://huogerac.hashnode.dev huogerac@gmail.com https://speakerdeck.com/huogerac