API Design at Hootsuite

Jon Slow sees that his favorite social media platform is missing a feature that would make it great: the ability to directly add pictures from his Google Drive account. He asks the company support if they’re going to add this feature, and gets a negative response, so Jon decides to do it himself. With his new programming boot camp certificate in hand, he gets to work, feverishly coding day and night. Without any official support from the platform, he has to get creative, hacking a solution together, spoofing HTTP calls, spending hours on Stack Overflow, until finally, it works. His third-party add-on, with no support from the platform creators, successfully connects to his Google Drive (sometimes). Suddenly, the platform creators push a minor, unrelated bug fix, and all of Jon’s work comes crashing down. His integration crashes immediately and permanently. Months of work, gone. If only there had been an API he could use.

An API (Application Programming Interface) is a well-documented set of functions that allow one program to interact with another. Essentially, an API is a contract between the API provider and the client program: the client knows that it can call a predefined function with certain types of parameters, and the provider promises to return a specifically formatted response for the client to use.

While we’re pleased with our final API, it’s still not perfect, and its flaws come from places where our goals conflicted with each other. One example is the “cursor”. When an app has more than one page’s worth of media that fits a specific query, it returns a cursor in addition to the rest of the payload. The cursor is a unique key that Hootsuite can send to the app to get the next page of results.

During our internal planning discussions, we thought about providing the app developer a guarantee that our software would return all the search parameters from the first page in addition to the cursor when asking for the second page. We eventually decided against it, as we thought it would add too much complexity in designing and implementing our internal services that interface with media apps.

As part of this project, we developed our own app that implemented the API as a proof of concept. During the development process, we realized that only sending a cursor, without the related search params, made it a lot harder for the app to generate said cursor. We had to encode all the search parameters in the cursor, send it to Hootsuite, and then decode the cursor that Hootsuite sends back when it asks for the next page of results. Not impossible, but a great deal more complicated than the alternative when search params are sent: “page2”.

This problem is typical of API design. Two of our major goals (“make it easy to use for external devs”, “make it easy to use for internal devs”) conflicted, and we had to make a decision about what was most important to the team. Maybe it was the wrong decision! We won’t really know until we show the API to more external developers and get some feedback. At that point, maybe we could change it.

Changing an API isn’t as easy as it might seem at first. As I said earlier, an API is a contract between two pieces of software, promising each other that they will both act a certain way. Changing the rules of that contract can cause a lot of problems. If the API implementation changes, every program that uses the API will probably have to change as well, and given that the API provider and consumer are usually developed by different teams or companies, it might be a long time before everything is back in sync. In the meantime, software will break and customers will be unhappy.

In order to avoid that, there are a few steps to take when updating your API. The most important is to make non-breaking changes. These are changes that will allow all apps currently using your API to continue using it in exactly the same way without malfunctioning. Generally, this restricts your changes to adding optional features: either new methods that API users can call, or optional parameters to existing methods that will add functionality.

Breaking changes, then, are basically anything else: removing functions, changing the required parameters that they accept, or the type or form of the data they return. If you really need to make a breaking change, then you’ll need to make a new version of the API, release it, try to convince developers to do the work to switch to the new version, and continue to support the old version for as long as possible (some might say forever) while developers are switching. The easiest way to do this is to version your endpoints (e.g. currently our media endpoint is called “v1/media”, and if we made breaking changes, we would create a new “v2/media” endpoint while leaving the old one alone). Even so, it’s a major headache, and the main reason why it’s important to be thoughtful with your initial design.

Jon Slow has been ruined. His integration is broken beyond repair. Every time he tries to use it, his computer gives off a little puff of smoke in despair. His programming career is at death’s door. Suddenly, an update arrives: the platform creators have released an API for media integrations! Reinvigorated, Jon sits at his computer. An hour later, his Google Drive has successfully connected to the platform. He can quickly and easily attach images to his posts. It’s everything he dreamed of and more. Jon Slow’s life is complete.

About the Author

Related posts:

Documentaries are broken into different modalities, that identify different traits and attributes that are within the film. These modalities are expository, Observatory, poetic, reflexive…

Oftentimes life appears to transition into a meaningless loop of hollowness; the mundanity and ennui is a vicious cycle that grabs a hold on our life without us realizing it. Man cannot stand a…

Today we are going to take a look at how to connect to a public Github repository using Visual Studio Code. This can be done by using an extension made by Github, called GitHub Repositories. It’s not…