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.
Maximizing Efficiency and Profitability with OnePlan’s Professional Service A...
Pure APIs: Development workflows for successful API integrations
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
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
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
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
15.
16. API server development workflow
• We build the API server against the specification
• We use the specification to validate the API server implementation
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/
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)