Expanding The Scope Of Your API

In development, the term full stack – familiarity with multiple programming languages for both frontend and backend development – is thrown around pretty regularly. Full spectrum is one that’s used from time to time, and may be a better way to describe the techniques required for superior API practice.

First things first, what exactly is full spectrum development, especially in the context of web APIs? There’s no hard and fast definition, but some cornerstones include:

• An understanding of front and back end development in one or more languages,
• Knowledge of DevOps, marketing, UX/UI and other useful strategies,
• Deep thinking about how the product/service fits into the business as a whole.

As you can see, being full spectrum requires a larger scope than programming alone; it includes usability, business, and marketing. With this being an API blog, let’s focus on full spectrum development as it relates to APIs.

Full Spectrum API

According to Adam DuVander, who works in Developer Marketing at Zapier, the key to building a full spectrum API lies in two words:

1. How? (Is the API easy to use? What is it designed to do?)
2. Who? (Is the API private or public? What does a typical user look like?)

Now, it’s easy to argue that properly addressing these two questions results in an API that functions properly and is well-received by users. In other words, an API that’s good. But the actual process of achieving a full spectrum API requires additional thought.

If we’re talking about full spectrum APIs, it’s helpful to highlight a few areas in which an API must excel in order to be considered one. In other words, an API needs to do a lot more than just perform as intended in order to be considered full spectrum.

In DuVander’s opinion, becoming a full spectrum API is a colorful union of complementary strengths. It’s worth looking at each of these points in turn, as they each expand on the idea of what it takes to create an effective API by looking at aspects that are related, but don’t necessarily refer directly, to the technology involved.

7 Elements of a Full Spectrum API:

1: Simple

“Our experience with an API is not the way the docs look. And it’s not (always) the documentation itself,” says DuVander. He gives the example of Stripe’s documentation, presented without any of the CSS and visual elements associated with it, with the implication being that functional documentation doesn’t have to look nice as long as it’s comprehensive.

Ideally, documentation will provide real-world examples and offer gateways into using the API. If first-time users are scratching their heads wondering “but what exactly can I use this for?” then there’s probably something wrong with either your documentation or the API itself.

2: Productized

It’s all too easy to think of your API as something fun and fleeting, particularly if it’s not really your core offering. That’s a mindset you need to shake if you want to take your API to the next level, and thinking of your API as a product can be a helpful way to achieve that. Even if you’re not planning on charging for it!

Your API may not end up taking the same route as Twilio, i.e. becoming your core offering, but that doesn’t mean that it can’t become a useful tool in your business arsenal.

3: Event-Driven

Think of the best APIs that you currently use. It’s very likely that they all have at least one thing in common; the user performs a certain trigger, which results in an action. “You won’t be surprised at someone from Zapier talking about this,” jokes DuVander, “because our entire product is built around this idea of ‘events’.”

“As API people, we think about our APIs in terms of endpoints but really you want to get down to how someone is actually going to use what you have.” Using an example from his experience at work Adam talks about how developers have no problem using static webhooks but, according to Zapier data, users do.

Instead of working from pure assumption, looking at usage data is the easiest way to find out more about how and why people use your API in the real world. Which brings us to…

4: Customer-Focused

If you build an API purely for your own personal gratification then that’s exactly how it’ll come across. A possible exception here is an private API designed to improve internal operations, but still, in this case, your colleagues are your consumers and their needs must be met.

The best external APIs succeed because they either save users time or help them to accomplish something useful (or just plain cool) that they can’t accomplish alone. Whenever you’re building or making changes to your API, always keep the question of how is this going to affect users? in mind.

5: Trustworthy

Creating something interesting and experimental is fun. It’s one of those things that makes you excited to get into the office so you can get to work. However, experimental work is often the first thing to get axed when there are budget constraints, when the company pivots, or when there’s a real need to focus on your core offering.

Netflix is an example of an API that was shuttered altogether, and Twitter’s is one that – while still public – suffered changes that killed off various third party services, as well as (Twitter-owned) TweetDeck apps for iOS and Android. See Instagram API deprecations for a similar story.

DuVander uses the Tesco API as an example, which he believes to be the only API to ever announce that it would maintain their service for a minimum of two years. Not all that long in the grand scheme of things, but to demonstrate such a commitment so transparently is rare in this space.

6: Reachable

DuVander explains that setting long-term commitments for availability “seems like a really low expectation for an API, but how many of you have had experience with an API that’s gone down?” As you’d probably expect, almost every hand in the room shoots up.

100% uptime, or 99.99% uptime, is always going to be something to aim for rather than a box every single API can tick. Users won’t usually hold much of a grudge as long as you’re quick to highlight issues, offer information on how much downtime to expect and provide explanations of what went wrong.

This is something that Slack does very well, and continues to enjoy a very favourable status with users despite a few incidents in the past couple of weeks alone.

7: Usable

As DuVander points out in his talk, usable is a deceptive word because it carries more weight than just being able to access something. Usable means “that, when something’s wrong, you can get an answer or support. Make it clear where you provide support, and make it easy to be able to reach out.”

That could be through a Twitter account or exclusively via email — regardless, it’s smart to have a dedicated developer support channel. Making your API as self-descriptive as possible can also increase usability and decrease 1–1 support.

8: Maintained

We’ve all been there – you’re trying to use an API, which you think can help you accomplish something really cool, and you head to the company’s site to find more information. Their last update? January 2009.

Maybe you’ve accidentally found your way to the developer hub for a previous version of the API or maybe the API is simply no longer available — Either way, the result is a total lack of information on where to go next.

This might seem like a small point, but clarity is always appreciated by developers. Take, for example, this short post from MailChimp announcing their latest API version and where to find up-to-date documentation. You may not be able to maintain every version of your API forever, but you CAN always keep users and potential users in the loop on versionings and deprecations.

Final Thoughts

If you haven’t done so already, go back and take a look at the letters of those categories again. Yes, they spell SPECTRUM.

We’ve previously written up a talk by Adam that used the acronym PIE, so we totally should’ve guessed that he would do the same thing again. We didn’t, by the way; it took us right up until the end of his talk to see what he was doing.

SPECTRUM is a fun little backronym for sure, but it’s more than just a buzzword. A good API is more than just a piece of technology; it’s also a customer facing product that should be simple, usable, and inspire trust by being reachable, well-maintained and event-driven.

The idea of a full spectrum API prompts various ways to make a service better beyond basic functionality. It’s really something we as API developers should be aspiring to — now that’s something we can all get passionate about.