How to Design an API

An @Pay developer summarized our office in the past month as “a tizzed frenzy of rapid experimentation, intense discussion and passionate development.” That developer is me. Hi. I’m James, and I’m lead on the team behind @Pay’s upcoming API—a suite of documentation, libraries and interfaces that will make adding @Pay’s Email Checkout and web payment services to your system downright simple.

So, how do we design an API at @Pay? If you’re new to API’s, here’s an API whitepaper that defines what they are and the purpose they serve in the business world.

API design has received a tremendous amount of attention in recent years due to a combination of the quickly expanding SaaS industry, better documentation tools, and a more introspective and demanding developer community. The Internet now hosts a huge number of easy-to-integrate, specialized services for functions normally developed in-house. At @Pay we deliver email, receive email, authenticate users, track analytics, write logs, and store and deliver content with a plethora of third-party application interfaces. By modularizing the web in this way we’ve indirectly mandated that these “hosted libraries” integrate into our already complex systems with minimal friction. The idea, after all, is to reduce the complexity we manage individually and maximize specialization.

Here are a few tips we’ve learned along the way:


Find your specialty and define your scope.

Outside of Email Checkout, @Pay’s products help customers reach their audience and subsequently analyze that audience’s reaction to their message. Our API focuses on the core of our business: Payments. Our API is not designed to make your emails easier to send, or your transaction history easier to analyze.

Because we absolutely excel in our understanding of payment technology—but have no intention of competing with companies outside of this arena—we settled immediately on the scope of the API we were building. This allowed us to narrow our development goals and produce a much more focused product that we are certain delivers on our core competency.

Talk to Customers

After establishing our specialty, we worked out what we thought was a beautiful system. We spent a few days prototyping it and played around with a number of use cases that had been thrown around internally. Everything was going splendidly in our imaginary development world when we decided to sit down with some folks who would actually be building their product on top of ours.

Smaller customers didn’t want to write the logic necessary to toggle Two-Click technology off and on for emails depending on various member statuses and states. They also wanted our API to handle more of the details for receipts and error conditions. Bigger clients had automated systems in place for almost everything, and needed guarantees that our system would not go down when they needed to send billions of messages to their customers.

We bounced ideas back and forth with a variety of organizations, both large and small, and our use case folder began to grow. After several months of discussion we trimmed this folder down to the common denominator and crafted a system that integrated in multiple ways and satisfied all of our users:

  • Offline key generation: We provide a native solution that runs locally on our customer’s system and handles difficult-to-scale requests without touching our servers. Despite our assurances and work behind the scenes to provide a tremendously scalable application architecture, our clients now have the option to scale our technology on their end.
  • JavaScript SDK: Clients want a simple drop-in integration, and developers are generally familiar with including Javascript plugins and scripts on their sites.

Eat the Right Dog Food

No matter how much unit testing you’ve established, and no matter how many use cases you’ve been through, you’re still only integrated with your own expectations of how your software should behave.

We sat down and thought of a few random application possibilities—ideas we didn’t design for or think of, but which still fell within the general scope of our specialty. What would it take to build out the full example? What would an integration with MailChimp look like? Could we build a general purpose e-commerce site for selling car batteries?

By building out these sample applications we went through a full stack application development cycle, and were able to diagnose workflow issues, documentation problems and general API capability concerns. How should a user be informed that they’re signing up for an @Pay account on a white-labeled site utilizing the JavaScript SDK when they’ve already signed up for an account via an OAuth prompt earlier? How do I pass reference information for my own application through the API so the hooks return the same data that the OAuth returns present?

Not only were we able to make our API more flexible, but now we’ve got two great sample applications we can release with our API! What better way for our clients to quickly learn how to integrate?

Other members of the @Pay technology team will be contributing their own observations over the coming weeks—these were simply my major takeaways. In a nutshell, build what you’re good at and what your clients want.

Leave A Comment

You must be logged in to post a comment.

Translate »