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
Beginners Guide to TikTok for Search - Rachel Pearson - We are Tilt __ Bright...
Leveraging API documentation to deliver reliable API integrations
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
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
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
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
14.
15. API server development workflow
• We build the API server against the specification
• We use the specification to validate the API server implementation
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/
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)