The document discusses documentation-driven development for APIs. It describes the benefits of designing API documentation like OpenAPI specifications before building servers and clients. It also discusses how to validate implementations against documentation using tools like Dredd and schemathesis. Additionally, it covers building clients using mock servers from tools like Prism, Stoplight, Postman, MockLab, and microapis.io. The presentation aims to demonstrate how documentation-driven development can help deliver successful API integrations.

1. Delivering successful API
integrations with
documentation-driven
development
• Jose Haro Peralta
• Full stack consultant
• Cofounder of microapis.io
@JoseHaroPeralta
@microapisio
PyCon India 2021

2. $ whoami
35% discount code: TBD
• 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/pycon-india-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

12. Dredd / schemathesis

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

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

17. Run Dredd tests with hooks

18. Running tests with Dredd

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

20. Run schemathesis tests with stateful links

21. Run schemathesis tests with stateful links

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

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

24. Running a mock server with prism

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

27. Running a mock server in the cloud

28. Running a mock server with microapis.io

29. Calling a mock server with microapis.io

30. Configuration for the Travis file

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

32. 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)