These are the old slides of my presentation at EuroPython 2021. The updated version, which contains new slides and some corrections, is this one: https://www.slideshare.net/JosntonioHaroPeralta/documentationdriven-development-for-python-web-apis-v2-249878010 This presentation shows how we can use documentation-driven development to minimise the risk of API integration failures. APIs are the gateways that connect our web applications to the world. Microservices rely on them to work together, and frontend applications use them to connect to our backend. Despite their importance, API integration failures are a daily occurrence. There’re many reasons for this, but a common factor is the lack of API documentation, or the use of bad API documentation. Often, API documentation comes in unstructured formats or in JSON examples, instead of standard formats such as OpenAPI or Schema Definition Language. When we don’t use standards to document our APIs, we give up the whole ecosystem of frameworks and tools built around those standards. Such tools and frameworks are designed to make our lives easier when managing the lifecycle of our APIs. In documentation-driven development, we write the API specification first, and then we implement the API server and the client against the specification. I’ll show how we can use mock servers to test the client while the backend is being developed, and tools like Dredd and schemathesis to validate the backend implementation. I’ll show how we can use these tools in a CI server to validate our code before it’s released. This approach doesn’t eliminate completely the risk of API integration failures, but it helps to minimise it.

1. Documentation-driven
development for
Python web APIs
• Jose Haro Peralta
• Full stack consultant
• Cofounder of microapis.io
@JoseHaroPeralta
@microapisio
EuroPython 2021

2. $ whoami
35% discount code: ctweuro21
• I’m Jose
• Independent contractor | London
• Full stack developer
• Microservices and APIs
@JoseHaroPeralta
@microapisio

3. microapis.io
39% discount code: ctwapi21
One-click API mock servers
@JoseHaroPeralta
@microapisio

4. Connect with Jose
• Twitter: @JoseHaroPeralta
• GitHub: @abunuwas
• Medium: @joseharoperalta /@python-geek
• LinkedIn: https://www.linkedin.com/in/jose-haro-peralta/
@JoseHaroPeralta
@microapisio

5. This
presentation
covers
• Complexity of API integrations
• What is documentation-driven development and why
it matters?
• How to you can adopt documentation-driven
development?
• REST API (OpenAPI)
• FastAPI
• Validate server implementation with Dredd and
schemathesis
• Build API clients with mock servers
• Continuous Integration and deployment to Heroku
• API visibitility
• Code for this presentation:
https://github.com/abunuwas/europython-2021
@JoseHaroPeralta
@microapisio

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

7. Misunderstandings drive API integration
failures
• Misunderstanding about data formats
• "2021-07-29" vs "2021/07/29"
• "$21" vs 21
• true vs "True"

8. Misunderstandings drive API integration
failures
• Misunderstanding about data types
• "2021" vs 2021
• 202.1 vs 202

9. Misunderstandings drive API integration
failures
• Misunderstanding about optional fields
vs

10. Misunderstandings drive API integration
failures
• Misunderstanding about the usability of the endpoints

11. How API
integrations
fail
Lack of
documentation
Bad documentation
Lack of design stage

12. What is API documentation?
REST -> OpenAPI
GraphQL -> Schema Definition
Language
gRPC -> Protobuf

13. What is
documentation-
driven
development?
• Also known as design-first, API-first
or contract-first approach
• Design and produce the API
specification first
• Build your server and your API
client (if you have one) against the
specification
• Use the specification to validate
your implementation

15. Dredd / schemathesis

17. datamodel-code-generator
(https://github.com/koxudaxi/datamodel-code-generator)

19. Run Dredd tests with hooks

20. Run schemathesis tests with stateful links

21. Running a mock server with prism

22. Calling a mock server with prism

23. Running a mock server with microapis.io

24. Calling a mock server with microapis.io

25. Configuration for the Travis file

26. Thanks for listening!
Twitter: @JoseHaroPeralta
GitHub: @abunuwas
Medium: @joseharoperalta /@python-geek
LinkedIn: https://www.linkedin.com/in/jose-haro-peralta/
35% discount code: ctweuro21