API integrations can be a pain. Anyone who has worked on API integrations has probably observed that, as a general rule, no API server survives first contact with the client. Reasons vary, from badly written API documentation to complete lack of API documentation. In this presentation, I want to address this problem by showing how developers can minimize the risk of API integration failures by using an approach called documentation-driven development. In documentation-driven development, we write the API specification first using a standard specification format. I'll show how we can leverage documentation to test and validate our API implementations before we release them. I'll show how we can use tools from the current ecosystem, such as Dredd, to automatically generate tests that validate our APIs.
4. About Jose
• Twitter: @JoseHaroPeralta
• GitHub: @abunuwas
• Medium: @joseharoperalta /@python-geek
• LinkedIn: https://www.linkedin.com/in/jose-haro-peralta/
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?
• How can you benefit from documentation-driven
development?
6. What is
documentation-
driven
development?
• Also known as design-first or API-
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
10. How API
integrations
fail
• We have to wait until the server is ready to begin
working on the client
• No design stage
• End up streamlining database models through HTTP
to the client
12. JSON
examples
are bad
Documentation in the form of JSON
examples
They tend to be incomplete
They’re often inaccurate (wrong
field names, wrong data types, etc.)
They become a maintenance
burden and are quickly deprecated
20. Mock
servers are
a life saver
for API
client
developers
NO MORE RANDOM AND
POSSIBLY DEPRECATED JSON
EXAMPLES
NO NEED TO SETUP AND RUN
THE ACTUAL API SERVER
LOCALLY
21. Run a local server with Prism
• Stoplight’s Prism library
• GitHub: https://github.com/stoplightio/prism
22.
23. Running a mock server in the cloud
• Stoplight
• Postman
• MockLab
• microapis.io
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/