Everything you ever wanted to know about APIs

Recently our VP of Engineering Jerry Chen gave a talk at the office after hours for the latest #TapIntoTwitter, covering different aspects of working with APIs.

We thought some of our readers might be interested in understanding how APIs work better, so we asked Jerry to recap his talk with a few questions.

You can also access the full deck from his talk here, or ask Jerry anything (within reason) on Twitter here.

What is the most misunderstood thing about APIs?

To get past the technical jargon, an Application Programming Interface is an agreement or contract between your program and something else.

It might be how you read or write to your hard drive, download the Google homepage to your browser, or even control your thermostat. It’s often conflated with how these programs actually communicate with the API. Is the protocol JSON or XML? Is it over HTTP or Thrift? These are just means and ways of talking, but not the actual patterns of conversation.

Ultimately, an API specification might be something like “If you want to adjust the thermostat, please provide the location of the thermostat, the temperature you want, whether you’re specifying Celsius or Fahrenheit, and indicate whether you’re pressing that HOLD button so the thermostat doesn’t just change its mind in like 10 minutes.” Then anyone writing a program, be it a page on a website, or an app on your phone, or some sort of remote control in your hand, can follow the API specification, talk to the API and get things done.

In Twitter’s case, they have a plethora of APIs to answer questions about the myriad number of conversations that happen on Twitter every day, such as “What are my last fifty tweets and the number of retweets, replies, and likes?” and “How many tweets have #thanksgiving are geotagged in Cuero, Texas, the ‘turkey capital of the world’?”

What do you wish more people knew about APIs and how they work?

It’s difficult building APIs. You may have an idea of how people might use an API, but as a provider of them, you do your best, and fit most use cases. People find ways of using an API to get data and do things that they need to do, which may not fall in this vision. Therefore, as a consumer of APIs, it’s a good idea to study available documentation. Get to know the ins-and-outs, the limitations, and the caveats. If there’s an opportunity of dialog, talk about your use case, and see how that might help future versions of the API.

Twitter has more than one API. Can you give a layman’s rundown of them and the differences between them?

One good way of breaking the APIs down is talking about two large main categories: REST (Representational state transfer) and Streaming. No one says “Representational state transfer”—I had to google it just now. REST APIs are the ones you call in a traditional request & response fashion. You have a request, perhaps a question such as “who are all of my followers?” The API will return a response, a first page of followers, and let you know how to get the second page, and so forth.

With Streaming APIs, you connect and are sent events as they happen. Perhaps you tell a streaming API, tell me all about my new followers as they follow me.

Either category has its own set of advantages and disadvantages. With Streaming, you can get a very large volume of traffic as it happens. However, with REST, features such as automatic removal of deleted tweets are built-in. You’re guaranteed accuracy in the response at the time of the request, whereas if you’re collecting data via Streaming APIs, it’s up to you to also use the Compliance stream to filter out which tweets have been deleted, or who’s deleted their account. These things happen. Some people DO see “delete your account” and do so.

Can you cover some of the challenges of weaving data from multiple APIs together into a real-world application?

Generally, APIs over the network have rate limits, meaning you get an allocation of requests per hour, or per minute. You have to be wise about your calls, and know the various rate limits allotted to your access. There’s some exciting stuff coming from Twitter in their quest to unify APIs. This will mean you can build your program once, talking to the same APIs, whether you’re on the free tier or the higher tiers, and scale up as needed. That’s fantastic.

Finally, what are the greatest challenges and rewards of being Chief GIF Architect for Union Metrics?

GIFs have to be timely. No one cares about a response to something from two hours ago. You don’t want to show up in 2017 sharing something about Left Shark. Left Shark is retired somewhere in Florida, probably meeting up with Mark Cuban’s friends to play poker Sunday nights. You have to be ready, to execute, and to bring joy/laughter/eye-rolling to the workplace.

When you upload that GIF to Slack, and half the office cackles (the rest are “working” or whatever you call it, but more importantly, missing out) — that’s a Good Day at the Office.

Photo by Erik Odiin on Unsplash