Delivering successful API

integrations with
documentation-driven
development
•Jose Haro Peralta
•Full stack consultant
•Cofounder of microapis.io

PyCon India 2021

@microapisio @JoseHaroPeralta
 $ whoami
• I’m Jose

• Independent contractor | London

• Full stack developer

• Microservices and APIs

35% discount code: TBD

@microapisio @JoseHaroPeralta
 microapis.io One-click API mock servers

39% discount code: ctwapi21

@microapisio @JoseHaroPeralta
 Connect with Jose
• Twitter: @JoseHaroPeralta

• GitHub: @abunuwas

• Medium: @joseharoperalta /@python-geek

• LinkedIn: https://www.linkedin.com/in/jose-haro-peralta/

@microapisio @JoseHaroPeralta
 • Complexity of API integrations

• What is documentation-driven development and why

it matters?

This • How to you can adopt documentation-driven

development?
presentation •
•
REST API (OpenAPI)
FastAPI
covers •
•
Validate server implementation with Dredd and schemathesis
Build API clients with mock servers

• Continuous Integration and deployment to Heroku

Repository for this presentation:
https://github.com/abunuwas/pycon-india-2021

@microapisio @JoseHaroPeralta
API integrations are tricky

API client API server

Major causes of API
integration failures
• Backend-driven API development

• Lack of separation between API layer and the rest of the

app

• Misunderstandings about the API

• Lack of validation
Fundamental
No API survives first contact
law of API
with its client
integrations
What is API documentation?

REST -> OpenAPI

GraphQL -> Schema Definition

Language

gRPC -> Protobuf

 • Also known as design-first, API-first
What is or contract-first approach
documentation-
• Design and produce the API
driven specification first
development?
• Build your server and your API
client (if you have one) against the
specification

• Use the specification to validate

your implementation
Dredd / schemathesis
datamodel-code-generator
(https://github.com/koxudaxi/datamodel-code-generator)
 Generate tests with Dredd

• GitHub: https://github.com/apiaryio/dredd
Run Dredd tests with hooks
Running tests with Dredd
 Validating the API server implementation with schemathesis

• GitHub: https://github.com/schemathesis/schemathesis
Run schemathesis tests with stateful links
Run schemathesis tests with stateful links
Building API clients against mock servers

We use a mock API server to build the client

Run a local server with Prism
• Stoplight’s Prism library

• GitHub: https://github.com/stoplightio/prism
Running a mock server with prism
Running a mock server in the cloud
• Stoplight

• Postman

• MockLab

• microapis.io
Running a mock server in the cloud
Running a mock server with microapis.io
Calling a mock server with microapis.io
Configuration for the Travis file
Thanks for listening!

Twitter: @JoseHaroPeralta

GitHub: @abunuwas
35% discount code: TBD
Medium: @joseharoperalta /@python-geek

LinkedIn: https://www.linkedin.com/in/jose-haro-peralta/
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)