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.
Leveraging API
documentation to deliver
reliable API integrations
Jose Haro Peralta
Full stack consultant
Co-founder of mi...
$ 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 me!
• Twitter: @JoseHaroPeralta
• GitHub: @abunuwas
• Medium: @joseharoperalta /@python-geek
• LinkedIn: http...
This
presentation
covers
• Complexity of API integrations
• What can we do to manage and reduce
the risk of API integratio...
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...
API server development workflow
• We build the API server against the specification
• We use the specification to validate...
• GitHub: https://github.com/apiaryio/dredd
Validating the API server implementation with Dredd
Validating the API server implementation with schemathesis
• GitHub: https://github.com/schemathesis/schemathesis
Development workflow for the API client
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 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
Run a local GraphQL server
• APIs Guru’s graphql-faker
• GitHub: https://github.com/APIs-guru/graphql-faker
Configuration for a Travis file for CI
It’s an ideal process, but!
• Designing an API requires tinkering and
experimentation
• Leverage frameworks that generate ...
API design and collaboration
tools
• Insomnia Designer
(https://insomnia.rest/product/design)
• Stoplight’s Studio (https:...
There’s already an undocumented API in place
• API visibility software
• Akita: https://www.akitasoftware.com/
Documentation-driven development
workflow
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 ...
Leveraging API documentation to deliver reliable API integrations
Leveraging API documentation to deliver reliable API integrations
Leveraging API documentation to deliver reliable API integrations
Leveraging API documentation to deliver reliable API integrations
Leveraging API documentation to deliver reliable API integrations
Upcoming SlideShare
Loading in …5
×

of

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

0 Likes

Share

Download to read offline

Leveraging API documentation to deliver reliable API integrations

Download to read offline

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

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

Leveraging API documentation to deliver reliable API integrations

  1. 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. 2. $ whoami • I’m Jose • Independent contractor | London • Full stack developer • Microservices and APIs @JoseHaroPeralta @microapisio 35% discount code: ctwasc21
  3. 3. microapis.io 39% discount code: ctwapi21 One-click API mock servers @JoseHaroPeralta @microapisio
  4. 4. Connect with me! • 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 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
  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. API server development workflow • We build the API server against the specification • We use the specification to validate the API server implementation
  15. 15. • GitHub: https://github.com/apiaryio/dredd Validating the API server implementation with Dredd
  16. 16. Validating the API server implementation with schemathesis • GitHub: https://github.com/schemathesis/schemathesis
  17. 17. Development workflow for the API client We use a mock API server to build the client
  18. 18. Run a local server with Prism • Stoplight’s Prism library • GitHub: https://github.com/stoplightio/prism
  19. 19. Running a mock server in the cloud • Stoplight • Postman • MockLab • microapis.io
  20. 20. Running a mock server in the cloud
  21. 21. Running a mock server with microapis.io
  22. 22. Calling a mock server with microapis.io
  23. 23. Run a local GraphQL server • APIs Guru’s graphql-faker • GitHub: https://github.com/APIs-guru/graphql-faker
  24. 24. Configuration for a Travis file for CI
  25. 25. It’s an ideal process, but! • Designing an API requires tinkering and experimentation • Leverage frameworks that generate API documentation from code
  26. 26. 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
  27. 27. There’s already an undocumented API in place • API visibility software • Akita: https://www.akitasoftware.com/
  28. 28. Documentation-driven development workflow
  29. 29. Thanks for listening! Twitter: @JoseHaroPeralta GitHub: @abunuwas Medium: @joseharoperalta /@python-geek LinkedIn: https://www.linkedin.com/in/jose-haro-peralta/ 35% discount code: ctwasc21
  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)

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

Views

Total views

78

On Slideshare

0

From embeds

0

Number of embeds

1

Actions

Downloads

0

Shares

0

Comments

0

Likes

0

×