Hello Fellow Developers! As we trek along deeper into the computing wilderness and climb to the higher rungs of development, we become keenly aware of the unfulfilled needs of the development community. These needs tend to be sated by brave souls who endeavor to author APIs. Some quintessential examples of this courage are jQuery, D3, and OpenLayers, just to name few.
Whats an API?
Well, we all know that it stands for Application Programming Interface. Thats easy. But...
What does it do?
APIs are a contract between the user and the API provider. Developers typically use the method signatures defined by APIs to handle program functionality without concern for the how the functionality is implemented. In Computer Science jargon, this is known as abstraction, hiding implementation details from users of the API. By authoring APIs we are creating tools for developers while taking our skills to the next level.
Why use an API?
For one, they are easy to use. Just invoke a function or method with the appropriate arguments and watch the magic unfold. Another important consideration is application configuration. APIs can save us much of our most precious resource, time, by providing well-understood and commonly-used functionality as well as encapsulating lower-level application details.
In this article, I will provide an actual scenario through which an API may arise to fulfill the needs of an application. We will examine how a simple API may be created to provide a higher level of abstraction for sending emails through AWS SES service. The purpose of this article is to demonstrate processes involved in creating developer tools.
For over a year now, I've been developing a Flood Forecast and Warning System web application with the Santa Clara Valley Water District, located in San Jose. This application is still beta, but is to eventually allow site registrants to receive email alerts in the case of a forecasted flood event.
To implement this email alert functionality, I decided to leverage the Simple Email Service(SES) infrastructure provided by Amazon Web Services(AWS). SES offers developers several powerful solutions for sending emails.
My application simply needs to send an email that has been dynamically templated. For my purposes and from a developer standpoint, a simple sendEmail() function with arguments for recipients, sender, subject, and body is desirable, yet I couldn't find such a thing! All the available options provided by AWS require SES credentials, lower level SMTP configurations, and/or long query string formations to dispatch to the AWS SMTP endpoint. The closest thing to this ideal scenario that I could find was the Sending an Email Through Amazon SES Using an AWS SDK. The SDK does a swell job of encapsulating the lower-level details of email sending through the AmazonSimpleEmailServiceClient and SendEmailRequest objects, BUT all I want is a method with the signature:
boolean sendEmail(String toAddresses, String fromAddress, String subject, String body);
As you guessed, this method would send an email to the addresses in the toAddresses array and return true if successful an false if not so.
This is an ample opportunity to create an API that is a higher level abstraction of the services already available through AWS SES. By doing so, It will allow users of the API to send emails using a sendEmail() function and they need not be concerned with the other low-level (but never dull) facets of SMTP and AWS SES. However, as the author of the API, these details must be known and understood!
Now, Amazon SES provides a simple, cost-effective way to deliver outbound-only email. There are two primary options available to developers for dispatching email messages through SES. The SES SMPT interface and the SES API. The SES SMTP interface is used with an SMTP-enabled software package, application, or programming language or to integrate SES with an existing mail server. The SES API is used to send email using raw HTTP(S) requests. The AWS SDK provides a higher level of abstraction for these raw HTTP requests, but the level of abstraction is not as high as we please.
Before we dive into hacking an API, its useful to follow some software engineering best practices. First, we should clearly understand the problem at hand. The problem is AWS SES doesn't provide us with a high enough level of abstraction for dispatching email messages. Next, we chew our pencil tips and stare blankly into space for some time to determine the best way to solve the problem. BOOM! All of a sudden, the solution is clear: we will author an API that leverages the already existing infrastructure of SES. Since we are only concerned with one thing, the API will provide just that: a single function for sending emails. Now if this API is realized, my dev team can be provided with the API and begin sending emails to their hearts content with minimal effort (most of the effort is undertaken by the API author/s)! In this context, the API author must have a working knowledge of the solutions provided by SES. Only with this knowledge (and coding experience) would an author be able to deliver an API providing a higher level of abstraction of SES.
Sorry, I will not implement the API in this article (maybe a future article! Or even better: you can do it as an exercise!), I simply wish to demonstrate how the birth of an API may occur and how APIs make the lives of developers even more pleasant. By taking the next step from API consumer to API producer, developers further their skills in the field and provide assistance for fellow developers. As an author of a popular API, various opportunities to capitalize on your skills will present themselves! Happy Coding!