This document discusses documentation-driven development for Python web APIs. It covers what documentation-driven development is, using REST API documentation standards like Swagger and OpenAPI to specify the API, and tools like FastAPI, Dredd, and CI/CD pipelines to implement, test, and deploy APIs based on their documentation. The goal is to write the API specification first before implementation to help catch errors and validate the final code matches the intended design.

1. Documentation-driven
development for Python web
APIs
Jose Haro Peralta
Algorizm Ltd
PyDay BCN 2020

2. About Jose
Discount code: ctwpydaybcn20
• Independent contractor
• Full stack developer
• Microservices and APIs

3. About Jose
• Twitter: @JoseHaroPeralta
• GitHub: @abunuwas
• Medium: @joseharoperalta
• LinkedIn: https://www.linkedin.com/in/jose-haro-peralta/

4. This presentation covers:
• What is documentation-driven development and why it matters?
• Example of documentation-driven development
• REST API (Swagger / OpenAPI)
• FastAPI for implementation
• Dredd for testing
• CI integration
• Deployment to Heroku
• Code for this presentation: https://github.com/abunuwas/pydaybcn2020

5. What is documentation-driven development?
• Write the specification first
• Use the specification to validate your implementation
• Also called API first

6. API integrations are tricky
API server
API client
12/12/2020 vs 12-12-2020

7. First law of API integrations
No API survives first contact with its client

8. What is API documentation?
• Using something like Google docs or Confluence is not enough
• We need standard formats: for REST -> Swagger / OpenAPI
• GraphQL -> Schema Query Language
• gRPC -> Protobuf

9. Misconceptions about API development
• API client work can’t start until the server is ready
• API changes should be driven by the backend
• The backend is the source of truth
• Documentation is only needed when you are an API vendor

10. Micorservices scenario
Service A
Service B
Service D
Service C