In my last blog entry, I defined an Application Programming Interface (API) and its importance. In this blog entry, I’ll discuss what makes a great API and how to technically approach the design and development. As an API software designer, you are going to receive a lot of “noise” from the different perspectives of user interface developers, the Data Scientists team, and the business.  I hope my blog post will help you handle the “noise” with professional skepticism and navigate through the technical design points to create a great API.

Why is an API Important?

  • Poor API – You are going to be married to this thing… forever. Decisions made 15 years ago at pay-pal have to be backwards compatible, or they lose staggering amounts of money.
  • Good API – A good API satisfies all requirements and allows you to move on.
  • Great API – A great API can give you enough flexibility to grow your business, release cool new features, and unlock the creativity of the world, without any investment from you.

Core Principals When Designing API Software

  • Think Ahead – Be cognizant of the long-lasting impact of your decisions. While an API is a small and lightweight piece of software, it is effectively a contract and language for how major systems will communicate with you into the foreseeable future.
  • Agility – During the initial design phase of an API, you are going to have to be very, very flexible
  • Keep it Simple and Intuitive – Less is more when it comes to the amount of code and complexity.  Your API should require the minimal amount of information to be able to return the precise and concise information from the server-side processing.
  • Plan and Design to a Roadmap – Your API should be capable of implementing everything without implementing everything out of the gate.
  • Eat Your Own Dog Food – If you are able to develop User Interfaces, develop your own user interface that uses your API. This will help you design future APIs much more than you might think.
Note: Click on the cartoon below to see a larger version of it:

W2O Drillable API - Low Maintenance API cartoon

High-level Approach

Gather Requirements – You are going to find things are much easier if you type up a 1-page document that outlines your API’s core objectives, guidelines, and what it needs to be able to do. Solicit use cases from your customer but avoid discussing specifications.

  • Use Cases – What do people really want to do with your API? What need does it fill? What questions will it answer? All of this is much, much, much, more important than specifications, the “how” of it all.
  • Specifications – Specifications can be the most damaging thing when creating an API. It is a document that serves as an immutable anchor from which you only pivot. Any attempt at making a great API can be seriously hindered by a 250-page requirement document, least of which are the political barriers associated that arise when someone becomes really attached to a 250-page document.
  • Synthesize Input with Skepticism – Be skeptical when you listen to people. People will often give you solutions to a specific problem, rather than what they really need. Be able to discern the difference between the two. Here’s an example:
    • What was said – “Develop an API that can produce a graph of my company’s major Twitter accounts, over time. It’d also be nice if it showed the change from day to day or week to week.”
    • What you should hear – “I want a graph, the actual data should be irrelevant, and it should understand how to do basic calculations regarding those data points.”
    • Negotiate Feedback – When getting feedback on your 1-page document, negotiate the feedback to accommodate the points above.
    • Anticipate – This is good for any type of design. Try to think 3-5 steps ahead for stuff that they aren’t saying, but you think that they might need in the future.
    • Build to Interface – Create the contract between the UI developers and the system first, put some fake data in it, turn it on and get some feedback.
    • Document – The software must be documented to ensure knowledge is available to support new integrations and provide sustainable support.
    • Test – Test against your new API constantly. While you are programming your new API, test it in as many real-world situations as you can. This will prevent unwanted issues from arising when it is game time.

Technical to Tactical

In this section I’m going to briefly touch on two examples. If you are a developer and want a more technical explanation, here are some concrete examples. However, for the purposes of this blog, we’ll keep it high level and discuss a few common problems I see in APIs that directly affect the perception of an application.

Dates and Data

Dates around the world are really hard to wrangle. There are hundreds of time-zones, of which, you can be occupying a few at any given point in time. Creating an early understanding of default time zones for data to be returned in is typically a good idea.

Note: Click on the cartoon below to see a larger version of it:

W2O Drillable API - Getting the Dates Right

Collaborate Often, and Early!

When designing an API, there can be subtle nuances that aren’t immediately apparent to the developer(s) about how their software works. When you are in the early stages of developing your API, setup focus groups, have them try to develop very quick apps that call and use it. Ask them what they liked, what they didn’t like. Some things look good on paper, but look very bad in practice and vice-versa. Bringing these two parties together in the beginning will facilitate collaboration early. While it may appear to be just another meeting, this meeting could actually save hundreds of hours of development time over the course of implementation. If your API is public, it could save you thousands of hours in support calls.

In my next blog post, I’ll be discussing W2OLabs Drillable API. How we designed it, how it works, what is on the roadmap for it in the future, and give you a taste of what we have in store for future software products.