Successfully reported this slideshow.
We use your LinkedIn profile and activity data to personalize ads and to show you more relevant ads. You can change your ad preferences anytime.
Delivering successful API integrations
with documentation-driven
development
• Jose Haro Peralta
• Full stack consultant
•...
$ whoami
• I’m Jose
• Independent contractor | London
• Full stack developer
• Microservices and APIs
@JoseHaroPeralta
@mi...
microapis.io
39% discount code: ctwapi21
One-click API mock servers
@JoseHaroPeralta
@microapisio
Connect with Jose
• Twitter: @JoseHaroPeralta
• GitHub: @abunuwas
• Medium: @joseharoperalta /@python-geek
• LinkedIn: htt...
This
presentation
covers
• Complexity of API integrations
• What is documentation-driven development and why
it matters?
•...
API integrations are tricky
API server
API client
Major causes of API
integration failures
• Backend-driven API development
• Misunderstandings about the API
• Lack of vali...
Backend-driven design of the API
• The API server development team decides what the API looks like
• Popular approach in c...
Misunderstandings drive API integration
failures
• Misunderstanding about data formats, e.g. "2021-07-29" vs "2021/07/29”
...
What causes misunderstandings about the API?
Lack of documentation
(e.g. JSON examples)
vs
Fundamental
law of API
integrations
No API survives first contact
with its client
What is API documentation?
REST -> OpenAPI
GraphQL -> Schema Definition
Language
gRPC -> Protobuf
What is
documentation-
driven
development?
• Also known as design-first, API-first
or contract-first approach
• Design and...
datamodel-code-generator
(https://github.com/koxudaxi/datamodel-code-generator)
• GitHub: https://github.com/apiaryio/dredd
Generate tests with 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
Medium: @joseharoperalta /@python-geek
LinkedIn: https:/...
Links
• Microservice APIs in Python by J Haro (mng.bz/nz48)
• Building and deploying reliable APIs with FastAPI by J Haro
...
Delivering successful API integrations with documentation-driven development [updated]
Delivering successful API integrations with documentation-driven development [updated]
Delivering successful API integrations with documentation-driven development [updated]
Delivering successful API integrations with documentation-driven development [updated]
Delivering successful API integrations with documentation-driven development [updated]
Delivering successful API integrations with documentation-driven development [updated]
Upcoming SlideShare
Loading in …5
×

of

Delivering successful API integrations with documentation-driven development [updated] Slide 1 Delivering successful API integrations with documentation-driven development [updated] Slide 2 Delivering successful API integrations with documentation-driven development [updated] Slide 3 Delivering successful API integrations with documentation-driven development [updated] Slide 4 Delivering successful API integrations with documentation-driven development [updated] Slide 5 Delivering successful API integrations with documentation-driven development [updated] Slide 6 Delivering successful API integrations with documentation-driven development [updated] Slide 7 Delivering successful API integrations with documentation-driven development [updated] Slide 8 Delivering successful API integrations with documentation-driven development [updated] Slide 9 Delivering successful API integrations with documentation-driven development [updated] Slide 10 Delivering successful API integrations with documentation-driven development [updated] Slide 11 Delivering successful API integrations with documentation-driven development [updated] Slide 12 Delivering successful API integrations with documentation-driven development [updated] Slide 13 Delivering successful API integrations with documentation-driven development [updated] Slide 14 Delivering successful API integrations with documentation-driven development [updated] Slide 15 Delivering successful API integrations with documentation-driven development [updated] Slide 16 Delivering successful API integrations with documentation-driven development [updated] Slide 17 Delivering successful API integrations with documentation-driven development [updated] Slide 18 Delivering successful API integrations with documentation-driven development [updated] Slide 19 Delivering successful API integrations with documentation-driven development [updated] Slide 20 Delivering successful API integrations with documentation-driven development [updated] Slide 21 Delivering successful API integrations with documentation-driven development [updated] Slide 22 Delivering successful API integrations with documentation-driven development [updated] Slide 23 Delivering successful API integrations with documentation-driven development [updated] Slide 24 Delivering successful API integrations with documentation-driven development [updated] Slide 25 Delivering successful API integrations with documentation-driven development [updated] Slide 26 Delivering successful API integrations with documentation-driven development [updated] Slide 27 Delivering successful API integrations with documentation-driven development [updated] Slide 28 Delivering successful API integrations with documentation-driven development [updated] Slide 29 Delivering successful API integrations with documentation-driven development [updated] Slide 30 Delivering successful API integrations with documentation-driven development [updated] Slide 31 Delivering successful API integrations with documentation-driven development [updated] Slide 32 Delivering successful API integrations with documentation-driven development [updated] Slide 33 Delivering successful API integrations with documentation-driven development [updated] Slide 34 Delivering successful API integrations with documentation-driven development [updated] Slide 35 Delivering successful API integrations with documentation-driven development [updated] Slide 36
Upcoming SlideShare
What to Upload to SlideShare
Next
Download to read offline and view in fullscreen.

0 Likes

Share

Download to read offline

Delivering successful API integrations with documentation-driven development [updated]

Download to read offline

[UPDATED] 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.

Related Books

Free with a 30 day trial from Scribd

See all

Related Audiobooks

Free with a 30 day trial from Scribd

See all
  • Be the first to like this

Delivering successful API integrations with documentation-driven development [updated]

  1. 1. Delivering successful API integrations with documentation-driven development • Jose Haro Peralta • Full stack consultant • Co-founder of microapis.io PyCon India 17-19 September 2021 @JoseHaroPeralta @microapisio
  2. 2. $ whoami • I’m Jose • Independent contractor | London • Full stack developer • Microservices and APIs @JoseHaroPeralta @microapisio
  3. 3. microapis.io 39% discount code: ctwapi21 One-click API mock servers @JoseHaroPeralta @microapisio
  4. 4. Connect with Jose • Twitter: @JoseHaroPeralta • GitHub: @abunuwas • Medium: @joseharoperalta /@python-geek • LinkedIn: https://www.linkedin.com/in/jose-haro-peralta/ @JoseHaroPeralta @microapisio
  5. 5. This presentation covers • Complexity of API integrations • What is documentation-driven development and why it matters? • How to you can adopt documentation-driven development? • REST API (OpenAPI) • FastAPI • Validate server implementation with Dredd and schemathesis • Build API clients with mock servers • Continuous Integration and deployment to Heroku @JoseHaroPeralta @microapisio Repository for this presentation: https://github.com/abunuwas/pycon-india-2021
  6. 6. API integrations are tricky API server API client
  7. 7. Major causes of API integration failures • Backend-driven API development • Misunderstandings about the API • Lack of validation
  8. 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. 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
  10. 10. What causes misunderstandings about the API? Lack of documentation (e.g. JSON examples) vs
  11. 11. Fundamental law of API integrations No API survives first contact with its client
  12. 12. What is API documentation? REST -> OpenAPI GraphQL -> Schema Definition Language gRPC -> Protobuf
  13. 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. 14. datamodel-code-generator (https://github.com/koxudaxi/datamodel-code-generator)
  15. 15. • GitHub: https://github.com/apiaryio/dredd Generate tests with Dredd
  16. 16. Run Dredd tests with hooks
  17. 17. Running tests with Dredd
  18. 18. Validating the API server implementation with schemathesis • GitHub: https://github.com/schemathesis/schemathesis
  19. 19. Run schemathesis tests with stateful links
  20. 20. Run schemathesis tests with stateful links
  21. 21. Building API clients against mock servers We use a mock API server to build the client
  22. 22. Run a local server with Prism • Stoplight’s Prism library • GitHub: https://github.com/stoplightio/prism
  23. 23. Running a mock server with prism
  24. 24. Running a mock server in the cloud • Stoplight • Postman • MockLab • microapis.io
  25. 25. Running a mock server in the cloud
  26. 26. Running a mock server with microapis.io
  27. 27. Calling a mock server with microapis.io
  28. 28. Configuration for the Travis file
  29. 29. Thanks for listening! Twitter: @JoseHaroPeralta GitHub: @abunuwas Medium: @joseharoperalta /@python-geek LinkedIn: https://www.linkedin.com/in/jose-haro-peralta/
  30. 30. 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)

[UPDATED] 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.

Views

Total views

96

On Slideshare

0

From embeds

0

Number of embeds

0

Actions

Downloads

1

Shares

0

Comments

0

Likes

0

×