Andrea Szollossi & Karl Salisbury - Open sourcing Adyen’s API explorer

API the Docs Virtual Event Series 2021 Recap

This talk was presented at API The Docs Virtual 2021 event series on 13 July. We are glad to present the video recording, slide deck and talk summary below. Enjoy!

Visit our talk recaps ToC page for an overview of all presentations!

Andrea Szollossi

Technical Writer at Adyen

Karl Salisbury

Senior Product Designer at Adyen

Andrea and Karl's presentation (video recording)



Andrea and Karl's slides



Adyen

  • Is an international payments platform built for growth, they connect businesses to Visa, Mastercard and popular global payment methods in a single system.
  • The payments landscape is vast and complex, the way businesses take payments is very diverse, so Adyen’s APIs need to be flexible.

API Explorer 1.0

  • Makes it easier for their merchants to understand how their APIs work.
  • Was the first place developers go when they start integrating with Adyen.
  • Improved over the years: from not having an API explorer at all to having completely bespoke solutions that will be also open sourced.
  • In the early days: PDFs to document their APIs moved on to Confluence.
  • Now: markdown files that generate docs pages. But static documentation has some obvious problems with version control, also not intuitive to navigate.
  • Then: started generating Swagger files, straight from the code, which made some things easier but there were some problems:
    • Most doc sites will take only one Swagger file and display it. But they had 15 different ones, and a single endpoint could have up to 20 different use cases.
    • Swagger files don’t give much context about what you’re looking at and still need some form of documentation.
  • Wanted to merge both of these references, Swagger files, and docs PDFs that built the very first API explorer, an in-house tooling specifically optimized for APIs.
  • Problems over time: legacy code becoming difficult and time consuming to update and maintain; some usability problems with the user interface. Needed to move towards more modern tech stacks.
  • APIs grew in size and complexity, moved from RPC to REST, and they also got a lot of requests to open source the API explorer.
  • Built a new API explorer 2.0 a little differently.

Why will they open source it?

  • To give back to the community. But: you need to think about how different audiences will use your software, and you also need to think about APIs that are different from your own and how they might work with your tools.
  • You also need to think about flexibility and extensibility. Someone external to the company might need to do something different with it than from what you originally intended. And they also might need to add your code or edit it in some way.
  • Creating an OS version benefits your own business too: challenges you to actually make your code more approachable, flexible, extendable and maintainable.

API Explorer 2.0, improvements

  • Compatible with the OpenAPI standard 3.1.
  • Improved usability: more like a development environment than a static website.
  • Window is more resizable**: much like how a development environment would allow you to do.
  • See requests and responses by stacking them on top of each other rather than side by side.
  • Supports dark mode: opens up a lot of opportunities in the OS community to theme API explorer, but it also allows API explorer to use in low light conditions
  • Mobile friendly.

Demo of the new API explorer starts at 14:23.

Takeaways

  1. Product development is iterative
  2. Open sourcing gives back to the community and leads to better software
  3. Consider creating OS projects or contributing to others

Sign up to our Developer Portal Newsletter so that you never miss out on the latest API The Docs recaps and our devportal, API documentation and Developer Experience research publications.