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
@JoseHaroPeralta
@microapisio
Repository for this presentation:
https://github.com/abunuwas/europython-2021

6.
API integrations are tricky
API server
API client

7.
Major causes of API
integration failures
• Backend-driven API development
• Lack of separation between API layer and the rest of the
app
• Misunderstandings about the API
• Lack of validation

8.
Fundamental
law of API
integrations
No API survives first contact
with its client

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

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

11.
Dredd / schemathesis

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

13.
• GitHub: https://github.com/apiaryio/dredd
Generate tests with Dredd

14.
Run Dredd tests with hooks

15.
Running tests with Dredd

16.
Validating the API server implementation with schemathesis
• GitHub: https://github.com/schemathesis/schemathesis

17.
Run schemathesis tests with stateful links

18.
Run schemathesis tests with stateful links

19.
Building API clients against mock servers
We use a mock API server to build the client

20.
Run a local server with Prism
• Stoplight’s Prism library
• GitHub: https://github.com/stoplightio/prism

21.
Running a mock server with prism

22.
Running a mock server in the cloud
• Stoplight
• Postman
• MockLab
• microapis.io

23.
Running a mock server in the cloud

24.
Running a mock server with microapis.io

25.
Calling a mock server with microapis.io

26.
Configuration for the Travis file

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

28.
Links
• Microservice APIs in Python by J Haro (mng.bz/nz48)
• Building and deploying reliable APIs with FastAPI by J Haro
(https://www.twitch.tv/videos/1088283640)
• Documentation-driven development for APIs by J Haro
(https://link.medium.com/m2A3rOxUfib)
• Developing API clients doesn’t need to be a pain by J Haro
(https://link.medium.com/0B9vt7DUfib)
• Design patterns for modern web APIs by D Luecke
(https://blog.feathersjs.com/design-patterns-for-modern-web-apis-1f046635215)
• The design of web APIs by A Lauret (https://www.manning.com/books/the-
design-of-web-apis)
• API Design Patterns by JJ Geewax (https://www.manning.com/books/api-design-
patterns)