node.js client library

Developing our Node.js Client Library

On Feb 6, 2015, my first pull request (PR) to the Node.js Client Library for SparkPost was accepted. The library was in its infancy and only included support for sending an email using the Transmissions Resource. My contribution expanded its capabilities to add support for the Sending Domains Resource. You might be thinking, “No big deal! You work at SparkPost, and are on the team that works on these libraries.” But this particular PR occurred a full month before I joined the SparkPost team as a Developer Advocate. Little did I know, I would soon become the maintainer of this codebase.

We’ve come a long way since that PR. Last month, we released the next major version of the node.js client library, node-sparkpost 2.0.0. This was our opportunity to step back and look at how the library was being used, remove what didn’t work or was holding us back, and improve the overall user experience. So we broke it down and built it back on top of a stronger foundation. We hope you like it.

Remember, this release has breaking changes, so you’ll need to consult our new Keep A Changelog inspired changelog, but I’ll highlight some of the changes and features below.

It’s so hard to say goodbye to yesterday

Sometimes in order to move forward, you have to let some things go. Starting with the 2.0.0 release, we will be following the Node.js Long Term Support Schedule and removing support for v0.10 and v0.12. This will allow us to take advantage of new features without having to worry about supporting versions of Node.js that are no longer maintained.

For those of you still on versions < v4, you can continue using the latest 1.x version of our client library using  `npm install sparkpost@1`.

Half the fat, just as filling

SparkPost is constantly growing and releasing new functionality. In order to keep up with the progress, we’ve switched the client library to be a thin wrapper. This ensures that new functionality will be exposed without the need for a new release and it helps simplify documentation. Everything you see in the API Documentation is now available in the client library. You can access every resource via the base object. Many resource wrapper objects have been included to provide syntactic sugar to improve the user experience.

For those of you moving from 1.x to 2.0, check to make sure all properties are passed in snake case (e.g. `campaign_id`). We have removed support for camel case (e.g. `campaignId`). If you are using any of the resource wrappers, be sure to consult the documentation because the method names and signatures could have changed.

Keep it simple

The data being returned has been simplified. In previous versions, we returned the full response. Now we are just returning the body of the response parsed as a JSON object. This cuts out the extra unneeded data and quickly gets you the results you need. We’ve added a debug option on initialization that will deliver the full response in a debug property should you still need it.

If you are migrating from v1.x to v2.0, `data.body` is now simply `data`.

Promises, Promises

We now support both of your favorite async strategies. All methods now return a promise, but we’ve also provided you the ability to continue passing callbacks. Want to know more about how we handle callbacks and promises? Check out the documentation.

So how do you send an email now?

Since the majority of developers use the sending functionality of the client library, let’s see what it looks like using node-sparkpost 2.0.0:

For those of you migrating from 1.x to 2.0, you’ll notice that the transmissionBody property has been promoted to the first argument and it aligns with the Transmissions Attributes. We have also moved any query string parameters to an optional second argument. For this example, we are using promises, but you can still opt to pass a function as the last argument to continue using the callback async strategy.

Additionally, as mentioned above, we’ve worked hard to make this version of the library get out of your way as much as possible. If you’d like to do the same transmissions call using our generic base object, this is what that would look like:

We’re very excited about this release and hope you all are as well. Thanks to our user-agent reporting, we are already starting to see adoption of our node.js client library.

graph: adoption of node.js client library

Are you currently using our node.js client library? Then pop over to our community slack and let us know what you think in our #node channel. You can also create an issue if you’ve found a bug or have a great idea for an enhancement. You can even submit a pull request and fix or add a feature yourself to our node.js client library. I welcome your feedback. Let’s improve the SparkPost experience for Node.js developers together.