Being an API service provider, we’re constantly on the lookout for how developers are building better APIs. As an API consumer—we rely on dozens of APIs internally and externally to power our business operations—we appreciate well designed APIs that are easily discoverable with a clean interface and quick ways to get started. This year, 7 APIs stood out to us that met all of these considerations.
We chatted with the people who have their hands and hearts in 7 leading APIs to get a peek behind the interface at the challenges they face and the solutions they use. These APIs have some of the best overall developer experience out there, which includes:
- Immediate utility, like quick shipping integration tools from EasyPost or producing an audio or video transcript with Clarify.
- Intuitive documentation, like the responsive navigation in multiple languages from Stripe and Clearbit.
- Top-notch support, like custom integration guides from Chain and SendGrid’s practice of understanding multiple use cases.
- Reliability, like Plaid publishing uptime stats.
Let's take a look inside these 7 standout APIs to see some of the ways they maintain an excellent developer experience:
1. Chain: Invest in Customer Onboarding
Chain provides modern database technology for the financial services industry with a platform that allows developers to design, deploy and operate blockchain networks. We asked Ryan Smith what elements go into creating a great developer experience:
“We believe that if financial services are built on top of excellent database infrastructure, the excellence will permeate all the way to the end user. To that end, we try are hardest to make the developer/customer experience as great as it could possibly be. We do this in a number of ways.
Instead of having generic API tutorials or guides, we tailor an integration guide specifically for our customer. This is basically a markdown file with a precise plan of what methods to call and when to call them. We also go to great extremes to provide good errors. Every error has a unique code (e.g. CH123) so that we can quickly debug issues when customers hit the error.
Additionally, we invest a lot in our SDKs. The SDKs will always include a request ID in the description of the exception. This way, when our customers get an exception, they just past the details to us and we can quickly go to Splunk to trace the path of the request. We write canaries using our SDKs that exercise the complete set of functionality offered by our API. We then use Runscope to automatically run the canaries and alert us if the canary should fail."
—Ryan Smith, Co-founder and CTO at Chain
2. EasyPost: Maintain Simplicity
The Simple Shipping API, EasyPost allows developers to integrate shipping and tracking info into their apps. We spoke with Saywer Bateman about how EasyPost overcame a familiar challenge with its API:
“This year we've grappled frequently with a common challenge for APIs—maintaining simplicity despite the frequent addition of capabilities. Specifically, we've recently added a lot of capabilities to our address verification product and wanted to avoid naively introducing a handful of new endpoints that would increase the complexity of our API. Instead, we spoke with customers and analyzed our logs to identify a new workflow that better matches how this API is being utilized.
For instance, rather than having distinct endpoints for verifying U.S. addresses, global addresses, or whether an address is residential or not, you can now send EasyPost an enumerated list of verification types to perform when you create an address. This workflow fits our best practices perfectly, is extensible, and reduces the number of requests to our API that customers need to perform.”
—Sawyer Bateman, Lead Project Designer at EasyPost
3. Plaid: Know Your Audience
Plaid is disrupting the financial industry with an API that powers two products, Plaid Connect that collects transaction data and Plaid ACH Auth to help developers set up ACH payments. We asked William Hockey about the company’s API learnings from 2015:
“I think a big learning experience and insight is you can't make everyone happy. It’s a hard combination to make an API both easy to use and simple for someone just trying to hack together a side project—but also full featured and powerful enough for your power users. Also, the Silicon Valley developer standard isn't always the best choice. We've had to deploy in enterprise settings where their gateways won't allow standard HTTP verbs like PATCH and DELETE, so every route has to be aliased to a POST request.”
—William Hockey, Co-founder at Plaid
4. Clearbit: Manage Change for a Seamless Customer Experience
For Clearbit, which provides business intelligence, its business relies on a robust set of six customer APIs, plus multiple pre-built integrations like one with Google Sheets. We spoke to Harlow Ward to learn more about how his team manages its unique API versioning process for a seamless customer experience:
“When introducing breaking changes to an API, you want your customers to keep the version they already have and update when they are ready—so they can test the changes in their own systems before releasing any changes downstream to their users. We use point-in-time versioning, which is a little complex, but it has advantages. For instance, it allows us to make adjustments within our codebase without having to create new endpoints within our system. It also allows us to easily see which API versions our customers are using. Since we’re anticipating quite a few changes to our APIs in the future as we improve them, this approach works well for us.
The key to all this of course is managing change on the backend so that API versioning is seamless for our customers. Basically, we need assurance that our versioning doesn’t break and that we can maintain this style without a lot of complexity. By running a schedule of regression tests against our API endpoints, we’re able to support tons of API versions transparently. It’s easy for us to build and update tests and add custom headers and versioning so that there are no unknowns.”
—Harlow Ward, Developer and Co-founder at Clearbit
5. Stripe: Keep the Learning Curve in Mind when Introducing API Changes
Payment infrastructure provider Stripe has been focused on developers since day 1, and its API is constantly cited as an example of how to do developer experience right. We chatted with Ray Morgan about how Stripe updated its API this year:
“One thing that I am super excited that Stripe has been able to do over this last year has been to start introducing new payment types into our API. This has been particularly tricky since we don't want force our users to upgrade their API version in order to get a new feature; and at the same time, we don't want to just bolt on new features.
For example, when fetching a list of Stripe charges from our API, your code may be expecting them all to contain a 'card' property that looks like a card. By making old API versions explicitly declare that they want non-card charges in that list (via a GET param), we are able to provide a solution that doesn't break current code. Additionally, this means that upgrading is as simple as first adding that flag to your call sites and testing, then once that change is live, you can upgrade your API version which will basically be a no-op (since you are already getting all the objects). Later, you can choose to remove the (now) extra query param.
Overall, the changes to the API ended up be fairly minimal and completely non-breaking. This is awesome because it means a much lower learning curve for the new features. They also just feel much more a part of the Stripe API.”
—Ray Morgan, Software Engineer at Stripe
6. SendGrid: Anticipate Different API Use Cases
At the core of SendGrid, the world’s largest email infrastructure provider, is an internal and customer-facing API with hundreds of endpoints. We spoke with Matt Bernier about how SendGrid provides support for its API from all angles:
“In my role, I have my hands in all the documentation, development of API libraries and API testing, which means I have three different entry points into our API. This allows me to see the larger picture from the top down and make sure that the API is actually consistent in how it’s presented. It also lets me think about what people are actually going to do with our API.
Working on testing means I can test the inputs and outputs, but also think about how people are using the API differently than what we planned for or built a particular feature for. Using the API in different ways lets me make sure the API works for different customers with different use cases.”
—Matt Bernier, Developer Experience Product Manager at SendGrid
7. Clarify: Approach Hypermedia Wisely
Clarify takes a new approach to transcription with an API for processing audio and video files, the results of which are then easily searchable and can produce reports. Hypermedia is a key approach at Clarify, and we chatted with Keith Casey to learn more:
“As we were expanding the API this year, we went deeper on our hypermedia approach. We choose to go all in on Hypermedia because we don’t know what’s next. Literally.
Our systems are machine learning-based and we analyze and learn things about our customers and their data constantly. Some are specifically things we set out to learn and others are accidental, but valuable, discoveries that help us detect and solve their problems better. For example, in analyzing sales calls to determine which calls resulted in a sale, we’ve discovered a number of patterns that go along with successful and failed sales attempts which then informs our customers’ sales training.
It’s important to remember that part of the underlying goal of REST is to have shared language to promote understanding. Therefore, the most important aspect of hypermedia is making sure your language is as consistent and explicit as possible. Don’t make up terms because they seem cute or applicable within your team. If there’s an industry-common word, use that instead.”
—Keith Casey, Director of Product at Clarify
These tips cover several different aspects of developer experience and maintaining high quality APIs. One of our best tips is to use API monitoring to ensure that if and when anything does go wrong—an endpoint goes down, there's latency or the API is returning the wrong data—you're the first to know and can fix the problem before customers notice. You can sign up for Runscope for free and get started in minutes monitoring the APIs you and your customers depend on most.
Are there any APIs not on this list that stand out to you? What are some of your best tips for maintaining healthy APIs and a solid developer experience? Let us know in the comments or shoot us an email, we'd love to hear from you!