Discovery and Twitter API v2

#twitter #badges #sdks #api

I've been working on a couple of side-projects that relate to my day job (I'm on the Twitter Developer Relations team), but which are in the realms of personal learning, discovery, and also, community.

I've been thinking about how to help developers to find resources to get started with the current version of the API, so I came up with two small tools for making things easier, particularly focused on discovery. Read on to learn about:

Twbadges, version badges for your README files
Awesome Modern Twitter API, an Awesome List of resources for the latest version

Also, I briefly mention Chirp, an exciting event coming later in the year.

Sign up to build what's next with a Twitter Developer account

Version badges

We've all seen those nice little badges or shields that show up in Open Source project README files, to signal everything from whether the build is passing, to what license the code is under, or what operating systems the code targets. Many of these are provided by services such as Shields.io or Badgen which generate similar styles of image that can serve as quick visual guides to what features the project supports.

There are a few versions of the Twitter API now, taking into account the Ads API and the older premium and enterprise features from v1.1, so I thought it would be cool to have a way to add tags to your projects on GitHub, GitLab, Bitbucket etc to act as eye-catchers to help other developers know how up-to-date the code is!

I went with Shields.io as the starting point, because it provides the ability to call a JSON API endpoint to get the configuration of the badge. This way, I can do things like specify a brand colour for the badge, or change the specific text shown, and add additional versions as new ones come along (the Ads API typically gets an update every 6 months or so, for example).

The basic requirement here is for an HTTPS endpoint that responds with JSON data matching Shields.io expectations, defining the look and content of the badge. Here's an example of the output for the v2 badge, specifying the colours, text and logo to use.

{
  "schemaVersion": 1,
  "label": "Twitter API",
  "message": "v2",
  "labelColor": "182430",
  "color": "1DA1F2",
  "namedLogo": "Twitter",
  "cacheSeconds": 600
}

In order to plug this in to the Shields.io service, all we really need is a simple way to serve up these JSON stanzas when the URL is used. There's a very nice Node.js module to do something like this: json-server, with a tagline:

Get a full fake REST API with zero coding in less than 30 seconds (seriously)

Well, that's convenient! I spun up a Twbadges, a quick app on Glitch which acts as a REST API - the data is served from a simple JSON file, and I used a couple of options to json-server to switch off the write functionality (it can support full CRUD operations if required). After that, I created a simple web page to showcase the badges using the Bulma CSS framework, and the app is ready to go! I've continued to quietly tinker with the code as a learning exercise (I haven't used Bulma before, also, I added twemoji to the web page, and messed with the layout), but it's simple and it does the job - pick from one of the available badges, and use them in your README files to show off your support of the latest Twitter developer features! You can also apply Shields.io style parameters if you want to use a different look-and-feel.

Here is how you could add a badge to a Markdown file, linking to the Twitter Developer website:

[![v2](https://img.shields.io/endpoint?url=https%3A%2F%2Ftwbadges.glitch.me%2Fbadges%2Fv2)](https://developer.twitter.com/en/docs/twitter-api)

Resources:

Twitter API version badges on Glitch
Code on GitHub (if you'd like to learn how I made this)

There's no reason why I couldn't pivot this to work with Badgen or another similar service in the future (or, you could build your own).

Code libraries and SDKs

I have found that one of the most interesting parts of working in Developer Relations on a platform like Twitter is the sheer variety of ways in which the API is used, and the numbers of folks who want to use it. It is also a really fascinating historical way to look at APIs - Twitter's very first v1.0 API was made available all the way back in 2006, just 6 months after the first Tweet was posted. Back then it was very basic, partly because the service itself was small and had far fewer features than today - there were a small number of endpoints serving XML over HTTP. Over time of course, it adopted JSON and OAuth but it grew a little haphazardly. One thing I'm excited about in version 2, is that the API is defined using a modern API specification standard: Open API - there were really no similar standards or definitions all the way back in 2006, but this time, we're starting from a well-understood foundation.

Historically, the platform never shipped code libraries for any specific languages - the developer community created them. This is ideal in many ways, because engineers at Twitter are never going to have in depth knowledge of every single new programming language that emerges, so community support was, and always has been, wonderful. I did a discovery exercise back in 2020, and identified over 100 different implementations of the (v1.1) API across 37 different programming languages! Mind-blowing. Fun fact for data science fans, the most common that I found were PHP (15), Python (11), Node.js (9), Ruby (7), dotNet (6), R (4) - but this also needs to be read in the context of the API across the period 2010-2020, where some of those languages were more common or popular, and others that are now used, such as Go, Kotlin, Rust and Swift, were not initially around or as mature as they are now, right back at the start. It was also difficult to keep up with what was out there in the community and keep our documentation updated, unless developers told us about what they had built (note: we now have a developer forum category for libraries and SDKs, where you can announce your code!)

As we shifted over to the v2 API, I made it my mission to talk to authors of many of the more popular existing libraries to encourage them to update their code where possible, as well as to start to look for new code that was emerging on the twitter-api-v2 topic on GitHub. We've curated some of these - particularly the ones we've tried for ourselves, or the developers have announced - into the Tools and Libraries page in our documentation, but we can't always keep that as up-to-date as we might like.

This is where my second side project comes in: Awesome Modern Twitter API. This is aiming to be an Awesome List that the community can contribute to in order to build a list of libraries, SDKs, tools, tutorials and projects that can help other developers to start to use the new API as quickly as possible, and to discover resources that we might not have listed directly in the main documentation. Why "Modern"? Well, that's a metaphorical "line in the sand" - v1.1 is at the end of its life and no new features will be added there, the future is the new foundation from v2 (and onwards), so the list will only include resources for the new platform.

I encourage you to take a look at the list and the project, and feel free to contribute. Maybe you're using a library I've not seen yet, or you have more knowledge of a particular coding language than me, or you've found an excellent tutorial or tool outside of Twitter that can help developers get started. As I wrote in the README:

This list is community-contributed, and it is not owned by Twitter. The list can only be even more awesome, with your help!

Resources

Awesome Modern Twitter API on GitHub

Finally...

If you've read this far, thank you! I hope you've found this interesting - let me know what you're working on, either as a side project, or what you've built using Twitter API v2!

A last note on some exciting times! We recently announced that our original Chirp Developer Conference is coming back, and will be happening in San Francisco and online in November 2022. You should also take a look at the Chirp Developer Challenge, with the chance to win prizes.

I'll be sharing more about several Twitter API-related projects and topics over the coming weeks. Thanks for reading!