APIs are the fundamental tenets of the Internet. They enable integrations between different services, and they power the servers that bring our applications to life. API integrations lay at the core of our API-driven world, and delivering successful API integrations is fundamental to sustain it. However, more often than not, API integrations tend to fail due to ineffective development workflows. In this presentation, I want to present various API development workflows that have helped me and my clients deliver successful API integrations. I’ll show how documentation-driven development, using mock servers, robust API testing frameworks, and API visibility tools can help to significantly reduce the chances of API integration failure and to keep errors under control.

1. Pure APIs: Development
workflows for
successful API integrations
Jose Haro Peralta
Full stack consultant
Co-founder of microapis.io
API World Conference
26-28 Oct 2021
@microapisio
@JoseHaroPeralta

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

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-world-2021

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

7. API integrations are tricky
API server
API client

8. Major causes of API
integration failures
• Backend-driven API development
• Misunderstandings about the API
• Lack of validation

9. 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
?

10. Organic growth of APIs
GET /forecast
GET /countries
GET /countries/{country_id}/stores
GET /periods
GET /countries/{country_id}/stores
POST /forecast
GET /user
GET /countries/{country_id}/stores
GET /scenario/{scenario_id}
POST /scenarios
PUT /scenario/{scenario_id}
DELETE /scenario/{scenario_id}
GET/new-store
GET /shares-totals
GET /countries/{country_id}/stores
GET /job/{job_id}
POST /new-store-shares-totals
GET /scenario/{scenario_id}/dataset
GET /dimensions
#/components/schemas/Dataset
#/components/schemas/SharesTotals

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

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

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

14. 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. API server development workflow
• We build the API server against the specification
• We use the specification to validate the API server implementation

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

19. Validating the API server implementation with schemathesis
• GitHub: https://github.com/schemathesis/schemathesis
• Uses property-based testing

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

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

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

25. Running a mock server in the cloud

26. Running a mock server with microapis.io

27. Calling a mock server with microapis.io

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

30. Configuration for a Travis file for CI

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

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: ctwapiworld21

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)