Calendar management
Embedded contextual email
Scheduling automation
Automated outreach
Telehealth
Marketplaces
Recruiting
Document management
Real estate
Communications software
Docs
SDKs
Tutorials
API status
Changelog
Support
Blog
Events
Guides
Newsroom
Partners
Build vs. buy
Customer stories
Trust & security
Why NylasSecrets to Great API Design
Learn how to make your API stand out from the rest with these tried and tested tips.
Learn how to make your API stand out from the rest with these tried and tested tips.
The way we build software is changing.
Now, companies are going to market faster and building features at unprecedented rates all thanks to the surge in API platforms.
The API economy has exploded in recent years with thousands of new APIs coming to market and reinventing the way developers build software. There’s an API solution for virtually every need: payment APIs (Stripe, Plaid), communications APIs (Twilio, Nylas), shipping APIs (Shippo), and thousands more. So how do you build an API that stands out from the competition?
Whether your goal is to build an open-source API, an API platform, or an API to help other developers integrate with your products, there’s one thing that makes successful APIs stand out from the rest: You must build an API that’s optimized for developer experience (DX).
Whether you’re a product manager, technical co-founder, or a developer yourself, you need to keep your end users at the forefront of every API design decision. By adopting this mindset, you are equipping your own users to use your service to innovate. Facebook is a prime example of this. In the early days of Facebook, developers were building games on their platform, but Facebook was profiting from their effort — all because they grew a robust community of developers from within their social media gaming platform.
Putting your API users in the driver’s seat by empowering them to build customized app experiences (or even experiences you didn’t know your platform could deliver) distinguishes you among the sea of ever growing and changing SaaS solutions.
In this white paper, we’ll discuss the following facets of API design:
But before we dive in, it’s worth mentioning these table-stakes functionalities of every API. Since these are fairly straightforward, we won’t dive into them in this white paper:
Got those down? Great, let’s dive in!
A great API will shorten the time to value (TtV) (i.e., the amount of time it takes them to see value from the API) for developers. Shortening TtV takes place even before a developer starts integrating with your API. You can prove your API’s worth in the docs themselves by allowing users to test a cURL response in the docs.
At Nylas, we’ve built a REST API that abstracts away the complexity of integrating bidirectional sync between a user’s inbox (email, calendar, and contacts) and software applications. In the Nylas Docs, we offer users a test token so they don’t need to authorize a real inbox before testing a cURL command. In a matter of seconds, developers can use the authorized access token to copy a single cURL line and see what the API returns.
Even when you’re providing test tokens, it’s critical to use the first-time-every-time framework. With the test token example, most developers expect the test token process to work exactly as prescribed, while others aren’t as familiar with how cURL commands operate. This is where excellent documentation comes into play.
Match users’ expectations
When building an API, keep one question top of mind: Does it do exactly what your users expect it to do on the first try?
In most cases, this involves taking a “do the right thing right the first time” approach to your API’s usability. You can shorten your time to value (TtV) by delivering an API that solves a challenging technical problem quickly and efficiently from the first interaction onward. For example, in the Nylas API, we make it easy to sync and send email minutes after creating an account with the API. Check in periodically to test your API and ensure that first interaction is smooth and has a big “wow” factor.
Increase efficiency with SDKs
SDKs are one of the best ways to reduce friction in the integration process. It’s critical to ensure developers can figure out the parameters of your API’s SDK integration as quickly as possible. Efficiency is both meant to save coding time, and eliminate any mental roadblocks while learning how your API functions within their framework of choice. With a simple Ruby, NodeJS, or Python SDK, developers can build a full-featured integration in a fraction of the time.
While SDKs take time to create and maintain, they dramatically improve the developer experience and reduce TtV.
Think of your API docs as the front page of your website. It’s the central place users will bookmark and start using; it should be user-friendly, intuitive, and follow a logical flow.
Your API docs need to be inherently discoverable and easy to use — just like the API itself. Stripe is an excellent example. Its docs are easy to navigate, with a clear table of contents on the left-hand sidebar, and a simple 6-step process for successfully charging a payment via the Stripe API:
While it’s important for you to do the valuable groundwork of ensuring API usability and the TtV is quick, your interface is only as usable as your documentation. And your documentation is only helpful when it’s easily discoverable.
Your documentation library should be organized in a consistent way with built-in search functionality — especially if there are a lot of complex elements to your API that require thorough documentation. This means that your docs must be logically organized, scannable, and provide contextual coverage across your entire API integration process.
Not only should your documentation be discoverable, it should also be contextual. In other words, they should show up in each developer’s programming language of choice. Listing all the technical guidelines for how to use your API is not enough, you need to provide signposts that can help provide context for specific developer scenarios. In other words, you will need to use a wide range of affordances when creating your documentation. This may even mean adapting your technology to meet the technology needs (SDKs, custom code languages) of each user.
Odds are developers are using your technology to solve a unique problem, so they will need to look to a wide range of guides, examples, and quick-starts to show them proof that they can use your API in a very specific, scalable way.
A developer-friendly API needs consistency. To optimize for usability, you should create workflows that consistently abstract ideas within your API.
With Nylas, for example, once developers have the API up and running, the core of the product’s execution is seamless. When using the Nylas API, you can update email messages, calendar events, and contact profiles in the same way – by making a POST request with the updated attributes.
You can also get full CRUD on Google and Exchange events with the same POST request. There are no exceptions in the code that would require developers to work in a different way, despite the data model being vastly different for Google and Exchange events.
On the flip side of this equation, it’s easy to have a too-fine focus on consistency so that you can miss opportunities to innovate. For instance, it’s possible to delay rolling out exceptions to your API that could evolve your product in the name of abstraction consistency, so be sure to find a reasonable balance.
Today, the world tends to move data in and out through JSON. Depending on your audience, that might be different, and in a couple of years that might look different. It may be better to add GraphQL APIs.
Developers will look to your API to remove friction from their workflows. If your API doesn’t follow the latest frictionless trends in the development world, you’ll lose a lot of interest. While trends in software engineering are constantly evolving, you want to at least be aware of the developing trends and consider which ones to incorporate into your API. For example, most developers expect a JSON response from a cURL command. JSON may seem like the obvious response, but this wasn’t always the case.
For example, a huge value-add within the Nylas API is that it removes the added layer of complexity from integrating with cross-provider email applications with XML and SOAP. By sending simple JSON responses in lieu of binary XML and SOAP, we’re able to minimize friction and create a better developer experience.
When building an API, change is inevitable. SOAP APIs lead the way to REST APIs, and REST APIs are the precursor to GRAPH APIs. JSON is the industry-standard file format for modern APIs, but this will likely change as technology develops. Since change is inevitable, the only thing you can do is embrace it and try to prepare for change by:
Build in versioning from day 1
Innovative digital payment provider Stripe takes a fairly strict approach to change where it creates new versions of the API each time a change is necessary (effectively changing nothing about old versions of the API). This requires it to support every version of the Stripe API from its initial conception to the latest rollout. Making significant changes to an API can have a severe business impact if done hastily or incorrectly, which is why some companies choose the same method of versioning as Stripe.
Communicate changes early and often
On the other side of this spectrum, Facebook makes changes to its API quickly and frequently — much to the delight and/or chagrin of web and mobile app developers around the world. It’s very good at communicating these changes in advance (or at least better than average) so developers can prepare, so few to no changes disrupt in their end users’ services. If you don’t have the resources to build versioned systems like Stripe, being able to communicate well about the changes is a lower-budget, smaller-scale way to deal with that.
At Nylas, for example, our contacts API (which syncs contact profiles from email address books into software applications) started syncing just a few fields when we launched: first name, last name, and email address. The new version of the contacts API expanded the number of data fields available to include address, job title, profile photo, and more. When building out Contacts V2, we made sure the new version was compatible with the old one so as not to introduce breaking changes.
API versioning can come in varying levels of complexity. Simple version numbering systems (V1, 1.1, 1.2, and onward) scale well and fairly effectively.
At Nylas, we’re currently in version 2 of the API. We store the current version and the old version in an application so users can decide which version to use based on their needs.
Summary
Successful developer experiences are built on trust and reliability. You can build trust with developers by ensuring your API works as expected from the first try onward. It sounds simple, but anyone who has done it knows it’s quite challenging. The good news is that by following the best practices of API detailed above, you’re on track to build a great experience, an exemplary API, and an excellent developer relations foundation.
Please enter your email address and receive the latest updates.
