API integrations are at the core of everything we do online. They enable integrations between different services, and they power the servers that bring our applications to life. The pervasiveness of APIs has led to the emergence of the so-called API economy, and most digital products are nowadays built around APIs, both for internal and for public consumption. The sustainability of our APIs relies on our ability to deliver successful API integrations. However, more often than not, API integrations tend to fail. This is due to a variety of factors, such as lack of API documentation or bad API documentation, lack of API design, and the use of ineffective workflows for API development. Lack of documentation, or bad documentation, prevents API client developers from building effective integrations with the backend, while lack of design makes APIs difficult to understand and therefore difficult to integrate with. In this presentation, I want to present API development workflows that I’ve successfully used with my clients over the past years to deliver successful API integrations. I’ll present strategies for consolidating the API documentation, and I’ll show how we use documentation-driven development to leverage API documentation and deliver successful API integrations. Through this approach, we can use mock servers and robust API testing frameworks for testing and validating our implementations. Video: https://youtu.be/kAWvM-CVcnw?list=PLcx_iGeB-Nxi54fIfinPnGfn6lPOLnLXQ GitHub repo: https://github.com/abunuwas/api-specs-conf-2021

1. Leveraging API
documentation to deliver
reliable API integrations
Jose Haro Peralta
Full stack consultant
Co-founder of microapis.io
API Specifications Conference
28-29 Sept 2021
@microapisio
@JoseHaroPeralta

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

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

4. Connect with me!
• 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 can we do to manage and reduce
the risk of API integration failure?
• What is documentation-driven
development and why it matters?
• How to you can adopt documentation-
driven development?
@JoseHaroPeralta
@microapisio
Repository for this presentation:
https://github.com/abunuwas/api-specs-conf-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

15. API server development workflow
• We build the API server against the specification
• We use the specification to validate the API server implementation

16. • GitHub: https://github.com/apiaryio/dredd
Validating the API server implementation with Dredd

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

20. Development workflow for the API client
We use a mock API server to build the client

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

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

24. Running a mock server in the cloud

25. Running a mock server with microapis.io

26. Calling a mock server with microapis.io

27. Run a local GraphQL server
• APIs Guru’s graphql-faker
• GitHub: https://github.com/APIs-guru/graphql-faker

29. Configuration for a Travis file for CI

30. It’s an ideal process, but!
• Designing an API requires tinkering and
experimentation
• Leverage frameworks that generate API
documentation from code

31. API design and collaboration
tools
• Insomnia Designer
(https://insomnia.rest/product/design)
• Stoplight’s Studio (https://stoplight.io/studio/)
• Postman’s API Builder
(https://learning.postman.com/docs/designing-
and-developing-your-api/the-api-workflow/)
Humans shouldn’t write YAML or JSON files

32. There’s already an undocumented API in place
• API visibility software
• Akita: https://www.akitasoftware.com/

33. Documentation-driven development
workflow

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

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