Delivering successful API integrations with documentation-driven development
Jose Haro Peralta (~jose) |
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.
Outline for the presentation:
- Introduction, what's the problem we are trying to solve, and why do we encounter this problem? Why are API integrations so tricky? Why do they tend to fail when we first release them? (10 minutes)
- What is documentation-driven development, and how exactly does it help? (5 minutes)
- Server mocking tools for API client development (10 minutes)
- API testing and validation tools for the backend (10 minutes)
- An example of development workflow for documentation-driven development and conclusions (5 minutes)
- Intermediate knowledge of Python
- Basic knowledge of web development
- Familiar with one or two Python web development frameworks, such as Flask or Django (the presentation will use FastAPI but knowledge of this framework is not required to follow the presentation)
- Familiar with the concept of web API
- Familiar with the concept of REST API
- The presentation will draw on the content of following two blog posts: Documentation-driven development for APIs and Developing API clients doesn’t have to be a pain
- It'll also use some code from this repository and this repository
- The slides for the presentation will build on top of these slides that I used in a previous presentation at PyBCN 2020, as well as these slides that I used for the API Conference 2021.
The above material will serve as inspiration, but ultimately the content of this presentation will be unique and different from the material listed above.
Jose Haro Peralta is the author of Developing Microservice APIs with Python (Manning) and the founder of microapis.io. He works as a full-stack software consultant based in London. He's a frequent speaker and blogger, and he specialises in Python and DevOps. He has worked in different industries, including IoT, financial services, and retail, helping clients architect and build microservices platforms, deliver successful API integrations, and write clean and maintainable Python code.