Why to Prioritize Your API Strategy Before Your API Design

The API has always been central to SendGrid even going back to the company’s original name, SMTPAPI. My career at SendGrid has always revolved around our API in some way, whether as Evangelist, or technical writer, or interim product manager. I’ve learned one major unexpected lesson during this time: API design is less important than you think it is. The low-level details matter less to the success of the business than you probably think they do when you're in the early stages of a product.

Having a comprehensive API strategy is far more important to the success of an API than the details of implementation. Sometimes engineers jump into building an API without understanding how many dependencies that's going to create within their organization. This is especially easy now that there are so many tools and frameworks that make building an API easier.

Before you deploy an API, there are a lot of questions to be answered, or at least to decide to answer later. Who's going to write the documentation for the API? Who's going to support it from Ops to make sure it's running? Who's going to scale it when you suddenly have ten times more account signups than you're used to? Who is going to provide support? Is your support staff going to be trained up enough to actually deliver value to customers who run into problems with the API? How are you going to monitor your API to make sure that your latency stays within limits that you're happy with? How are you going to create run books for your SREs to handle things when API servers are crashing? Do Sales and Marketing understand your API well enough to present it well to potential customers?

If you haven’t given enough thought to your API as a product, then you shouldn’t prematurely optimize or spend a bunch of time upfront trying to perfect your API design. Choosing the proper architecture or designing your API with security in mind are undoubtedly important decisions but if you spend time building all of that stuff upfront without actually validating if your product is useful or if there's a market for it, you're just wasting time. And you might find that your audience doesn’t care as much about those things as you hypothesized. As an example, we used to support XML as a payload format. When we looked at the logs, only 2% of our customers were using XML; we hadn’t properly validated the need for that particular format. Make sure that you have instrumented your API for analytics so that you can make these types of decisions faster.

It’s better to release a poorly designed API that delivers value to your users than to release a well designed API for a product that has a questionable value proposition. If you have an API strategy in place, then you’ll be well organized for gathering feedback, analyzing API interactions, and validating what to build next or which parts of the design are not working. If you have users or leads complaining about your API, then you have a good problem because that means you have users and leads that see the value in your API.

Brandon West is Director of Developer Relations at SendGrid.
 

Comments