What Hosting Hackathons Taught Us About Our APIs

During our 2017 hackathon series, the Capital One DevExchange team reaffirmed one of our most important tenets — co-creating with our community helps everyone build better products. At seven events in seven great cities, we invited developers, designers, and product leaders to join us for a day-long exercise in building customer experiences with our APIs. And, not surprisingly, we learned quite a bit about the APIs and how to better support the developers using them.

Documentation, Documentation, Documentation

It’s commonly accepted that proper documentation is an essential component of any API. Whether we’re talking about a finished API that has already been released, or an in-progress experimental API, documentation should be at a minimum easy to access and all in one place. Over the course of introducing attendees to both types of APIs, we learned a few things about our API documentation:

• Don’t make it too hard to get to the meat. Some of our documentation needed trimming and re-organization to make them more readable. While this is a universally applicable issue, the condensed timeframe of a hackathon really brought it to the forefront.
• OAuth can be harder than we thought. Hackathons attract devs with varying levels of experience. When junior and mid-level devs both struggle with something, you pay attention. For some of our APIs, we needed to provide better help with OAuth, including some documentation updates, code samples, etc. For example, the Rewards API documentation now includes code samples for the steps involved in both obtaining and refreshing an access token.
• Web-based documentation > PDF-based documentation. Our hackathons often feature a mix of our official publicly available APIs and our pre-release experimental APIs. The documentation for these types of APIs live in different formats — on our portal site and in PDF files respectively. Several of our APIs, including Merchant Insights and the Digital Identity APIs, have been featured at hackathons in both stages of their development cycle. While the content of their documentation remained relatively the same across formats, users struggled to navigate and cut+paste code samples from the PDF format. This affirmed our belief in the superior readability of well-formatted web-based documentation.
• Specific use cases lead to specific documentation issues. When users have issues with the documentation, they’re often very specific to a certain need such as how to connect to or implement our API in the context of their existing infrastructure. This is equally true for both our hackathon users and our integration partners. To address this for our integration partners, our Professional Services team has started creating client-specific integration guides to address specific use cases. For certain APIs and uses, this is a much-needed addition to the more generally-applicable online documentation.

Previewing APIs — the Good, the Bad, and the Integration Problems

This year, we gave our hackathon attendees a sneak peek into several experimental APIs prior to their official release. This allowed us to collect invaluable feedback earlier in the API release cycle; creating a better final product.

However, we learned through the course of this process that testing APIs at hackathons can be tricky. Over the course of three hackathons in 2017, we previewed six pre-release APIs. This included:

• Boston hackathon — we previewed our suite of Digital Identity APIs.
• Philly hackathon — we previewed the Merchant Insights API and a second experimental data-based API.
• Santa Monica hackathon — we previewed a document storage and handling API.

Boston was our first hackathon featuring both released and pre-released APIs and our attendees hit some stumbling blocks attempting to use both types in a single project. The root of this problem was a conflict in the API environments — released APIs were accessed on our platform, whereas pre-released APIs were accessed on GitHub. After Boston, we learned that if we gave attendees a separate easy-to-use environment with mock services for all our APIs, it was a lot easier for them to dive right into using them.

Debuting at our Denver hackathon, this mock environment made integrating the preview APIs easier, helping increase the number of teams that included them in their projects. This has improved the quality and quantity of feedback we’ve received since more attendees are now working these APIs into their hackathon projects.

“We designed a lightweight hackathon environment which allows us to enable private and experimental APIs to developers alongside our DevExchange public offerings. We have seen this lead to innovative new app ideas where teams can spend less time configuring and more time coding.” — David Benko, Professional Services

Thinking of Our Offerings Holistically

When the DevExchange platform was launched in March of 2016, our original APIs were all stand-alone offerings. With the debut of the Digital Identity APIs at our Boston Hackathon, that changed. This suite of three identity management APIs — Sign Up, Sign In, and Verify — were designed to work together to provide an elegant and secure user experience.

From previewing these APIs at our hackathons, we identified a need for more in-depth explanations of the differences and relationships between these three APIs. Attendees with less experience in identity management were confused about the use cases and how the APIs interrelated. This meant many of the first projects defaulted to the simplest use cases for Sign In; ignoring Verify and Sign Up entirely. While it’s likely that potential integration partners would have a greater literacy in this area, it pointed out a need for a more holistic approach to our API offerings.

At our Santa Monica Hackathon, these learnings were amplified when we previewed an experimental document storage and handling API. Many devs had questions about how this experimental API would work with the Digital Identity APIs. We realized that these APIs don’t necessarily work together in ways that are obvious to all devs, requiring us to rethink how we present them individually and in aggregate.

Our Commitment to Hackathons

“Participating in a Hackathon is part of the “test and learn” process. Having feedback early in the development cycle is vital. It helps prove (or disprove) assumptions. Sitting in my Product Manager bubble and only iterating on my ideas is a fast way to make a bad product.” — Brandee Shin, Product Manager

2017 saw a renewed commitment to engaging with the dev community through hackathons. As we move into 2018 and towards the release of additional APIs, we will continue to work with this community to help us preview and test our products.

For more information on upcoming DevExchange hackathons, please keep tabs on our events page for updates.

DISCLOSURE STATEMENT: These opinions are those of the author. Unless noted otherwise in this post, Capital One is not affiliated with, nor is it endorsed by, any of the companies mentioned. All trademarks and other intellectual property used or displayed are the ownership of their respective owners. This article is © 2018