Product, Technical

APIs: Perfection Vs. Reality

APIs: Perfection Vs. Reality

Product, Technical

Releasing email API endpoints at SendGrid has taught us valuable lessons about testing, validating, and communication with customers before we take new endpoints live.

Aiming for Perfection

One example I recently spoke about in early November at APIStrat in Boston was about naming our newest email endpoint. Our V2 email API has /api/mail.send.json for an endpoint. Alone, it handles nearly 50% of our email traffic (nearly 500M email requests per day), the other 50% going over SMTP.

In the new RESTful vision of our email API (V3), we wanted to combine all of the great features of our X-SMTPAPI functionality into a single intuitive endpoint, make integrating to send email over SendGrid much easier, and include some special gems for future email use.

picture1

We spent quite a bit of time debating the details of email/name-object formats, parameter naming, JSON structure, validation, and the newly added sandbox_mode. One of the biggest discussions that we had was around whether or not we can name the endpoint with a verb. GASP!

Our Customers’ Reality

In reality, when we looked at how our customers view this endpoint, they’re not really sending the email. They’re asking us to send the email for them. Our customers are creating a mail-send resource, which we consume, and then use to create and send email. Even though all of these verb things happen on our end, it doesn’t change what the customer sees. Also, since releasing the endpoint earlier this year, we haven’t heard anyone mention the verb in the URI to us.

The process of designing and launching v3/mail/send led the Developer Experience team to start looking at our libraries in a deeper way to determine what, if anything, we could do to improve the experience for customers who use these tools.

We quickly realized that our libraries were an administrative nightmare. We had features in one language and not another. We called methods one thing here and another thing there. It was difficult for a team to coordinate managing these libraries, as well as understand the requests that were coming in about the code.

Our Best Solution

The answer was to do the thing that so many people never want you to do: start over. We decided that for our own sanity and to increase the possibility of a better experience, we needed to have a new look at the interfaces we were providing as well as standardize against the API feature set.

In the investigation phase, we posted requests for feedback in our READMEs and in our GitHub issues. We got basically no response. Bueller…Bueller…

The last resort was to release a new minimum viable product (MVP) version in each library. This allowed us to update each library, while still creating a usable interface for our customers. The response from some of our language communities was great, because we released all the endpoints and v3/mail/send support all at once. The response from other communities was not so great.

What We Learned

Our C# Library – One of the biggest takeaways was that we completely missed the mark with our C# library, and our customers were looking at our libraries as the API itself. This was a revelation, because while it is an interface (the “I” in API), we hadn’t been looking at the libraries in the same way we looked at our API. We started taking a different approach to how we engaged our users and discussed the libraries as a result.

Our MVP Library – What we’ve seen from our move to release an MVP library is that we’ve enabled our community to feel ownership and some control over the direction of the code we produce for them. This engaged community of developers answers questions, provides support to other members, plucks items from our GitHub projects, and even approves pull requests for us! In return for their help, we reward them in the form of a sweet SendGrid t-shirt, but they always have our eternal gratitude.

By validating what our customers need and want, we’ve been able to build smaller for a bigger impact, get feedback, and then move forward knowing that we’re building APIs that our customers will love, value, and use.


More Posts by Matt
As a Developer Experience Product Manager for SendGrid, Matt works to constantly improve the SendGrid experience for developers who are building integrations by focusing on the entire API ecosystem of new products and features, API design, documentation, and API libraries.
Follow Matt