[UPDATED] APIs are the pillars that enable communication through the web. Microservices talk to each other through APIs, and frontend applications connect to our backends through APIs. Yet, despite their importance, API integrations failures are a daily occurrence. There're many reasons why this happens, but a common denominator is the lack of API documentation, or the use of bad API documentation. In this presentation, I'll show how we can use documentation-driven development to minimise the risk of API integration failure, and I'll discuss the tools and frameworks that help us leverage the benefits of this approach. Although the risk of API integration failure can never be ruled out, the approach discussed in this presentation helps to reduce the chances of its occurrence.

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

2. $ whoami
• 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
• Misunderstandings about the API
• Lack of validation

8. Backend-driven design of the API
• The API server development team decides what the API looks like
• Popular approach in code-first approach
• Ends up in arbitrary API designs that are difficult to understand for the API client
development team
?

9. Misunderstandings drive API integration
failures
• Misunderstanding about data formats, e.g. "2021-07-29" vs "2021/07/29”
• Misunderstanding about data types, e.g. "2021" vs 2021 or true vs "True”
• Misunderstanding about optional fields
vs

10. What causes misunderstandings about the API?
Lack of documentation
(e.g. JSON examples)
vs

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

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

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

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

20. Run Dredd tests with hooks

21. Running tests with Dredd

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

23. Run schemathesis tests with stateful links

24. Run schemathesis tests with stateful links

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

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

27. Running a mock server with prism

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

31. Running a mock server in the cloud

32. Running a mock server with microapis.io

33. Calling a mock server with microapis.io

34. Configuration for the Travis file

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

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