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.

1. Documentation-driven
development for web
APIs
Jose Haro Peralta
Full stack consultant / creator of microapis.io
API Conference 2021

2. About Jose
39% discount code: ctwapi21
• Independent contractor (London)
• Full stack developer
• Microservices and APIs

3. microapis.io
39% discount code: ctwapi21
One-click API mock servers

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

7. API integrations are tricky
API server
API client
12/12/2020 vs 12-12-2020

8. Fundamental law of API integrations
No API survives first contact with its client

9. How API
integrations
fail
Lack of
documentation
Bad documentation
Lack of design stage

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

11. Micorservices scenario
Service A
Service B
Service D
Service C

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

13. How API
integrations
fail
There’s documentation, but…
not really
Documentation written in a
non-standard format
Shared in platforms like
SharePoint, Google Docs,
Confluence, etc.

14. What is API documentation?
REST -> OpenAPI
GraphQL -> Schema Definition
Language
gRPC -> Protobuf

15. Advantages of documentation-driven
development
API server and client can be
developed in parallel

16. Advantages of documentation-driven
development
API server implementation can be validated against the specification

17. Generate tests with Dredd
• Apiary’s Dredd library
• GitHub: https://github.com/apiaryio/dredd

18. Running tests with Dredd

19. Advantages of documentation-driven
development
We can run a mock API server to build the client

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

23. Running a mock server in the cloud
• Stoplight
• Postman
• MockLab
• microapis.io

24. Running a mock server in the cloud

25. Visualisation and interactive tools – Swagger UI

26. Visualisation and interactive tools – Redoc

27. Run a local GraphQL server
• APIs Guru’s graphql-faker
• GitHub: https://github.com/APIs-guru/graphql-faker

29. Documentation-driven development
workflow

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/

33. Documentation-driven development
workflow

34. Thanks for listening!
• Twitter: @JoseHaroPeralta
• GitHub: @abunuwas
• Medium: @joseharoperalta /@python-geek
• LinkedIn: https://www.linkedin.com/in/jose-haro-peralta/
39% discount code: ctwapi21