Image Image Image Image Image Image Image Image Image Image

Being Brunel |

Scroll to top

Top

No Comments

Engineering the Twitter API

Engineering the Twitter API

Last week I talked at length about the wonderful world of the Web API, but completely failed to provide any details of how you can start playing with them. Well today we’re going to do some engineering with twitter using their RESTful API.

Interacting with Web APIs is normally done programmatically, and so varies from language to language. However, once you’ve got the process down it’s just a matter of implementation. To ease the learning curve, however, we’re going to be using Twitter’s Developer Console; thus requiring you to do absolutely no coding at all:

Twitter Developer Console

OAuth

As Microsoft’s Tay learnt the hard way– if you go around trusting everybody you meet on the internet, you’re going to get shutdown. This means that most ‘open’ API’s on the internet need you to authenticate; provide an identity that you can be traced and trusted against. OAuth is one of the most common ways of authenticating yourself to a Web API. In fact, you’ve probably used OAuth without knowing it!

As a ‘good-enough’ analogy, OAuth is like your site safety card. You get yourself tested by, and give all your personal details to, the issuing authority, and then you get given a card. When you visit a site the inspector rings up the issuer and verifies the card, and then hands you a visitor pass for that day and that site. In this case the card is your login details, the issuing authority is often someone like Twiter, Google, GitHub, etc., the ‘site’ is the api and the visitor pass is called an access token.

So, before we can started you need to authenticate in the Twitter Developer Console. At the top centre is an Authentication area, initially saying No Auth. Drop this down and select OAuth 1.1, at which point you’ll be asked to login to Twitter. Congratulations, you’ve now got your access token (although this interface simplifies things and just stores it behind the scene.)

Headers

So let’s make a request. To save you learning the whole Twitter API you can expand the dark gray sidebar on the left on the console, which will then list all the actions available to you. We’re going to search tweets, and in Twitter’s RESTful API that means GET‘ing /search/tweets.json (I’ll touch on what the .json means later).

twitter-console-expand

To be helpful the console will now expand to ask you for the parameters needed to complete the query string. For this example we’ll go searching up the #EngineeringIsArt tag, so type #EngineeringIsArt into the q parameter and press Send.

The Console then shows you two (overly) technical looking outputs. On the left is the Request that you made, and on the right is the Response the Twitter server returned. We’re going to focus on the response, which is formed of two parts- the header (first bit) and the data (which starts at the {).

Headers are used by HTTP to transfer protocol level information. There’s a lot of information in the response header, with everything from the time the data was put together for you to the cookies that it wants the browser to set. Only two bits of this are all that interesting for us: the status and the content-type.

The status is a number indicating how things went. There are a good few codes, however the most useful to know are:

  • 200: OK
  • 400: Bad Request (normally because you didn’t authenticate)
  • 404: Not Found
  • 500: Server Error

The content-type tells you what ‘format’ the content you’ve be returned is in. In this case you’ve being given some json, but it could be a jpeg image or something even more exciting!

JSON

A few years back the web was a place of many languages, however these days you’ll find that most Web APIs will return data to you in something called JSON (JavaScript Object Notation). Sometimes you might also see an option for XML, but by and large we all talk JSON.

The data in the response is in JSON:

Hopefully you can make out some of the data already, but it’ll help if I tell you that JSON works like this:

  • "key": "value"
  • { collection of keys and values }
  • [ list of values/collections ]

So in the data above we have a key statuses that contains a list of Twitter statuses (tweets). The components of each status is collected in { } brackets, so the first status was created at Sun May 22 13:16:41 +0000 2016 with the text I call this 'Fenland Footbridge'. Because that's what it is... #EngineeringIsArt https://t.co/BE1qPcGBhR.

Return Post

To finish off let’s use the Twitter Developer’s Console to send me a message.

  1. Making sure that your Authentication is set to OAuth so that twitter trusts you to send a message…
  2. Expand the API selector on the left side and Direct Message > direct_messages/new.json
  3. Enter the parameters:
    1. text: Cheers for the tutorial Tom!
    2. screen_name: beingbrunel
    3. user_id: leave blank
  4. Press Send

Looking at the Request you’ll see you’ll see you POST‘ed to (twitter)/1.1/direct_messages/new.json?text=Cheers%20for%20the%20tutorial%20Tom!&screen_name=beingbrunel (the funny %‘s are to do with the way punctuation is sent in HTTP).

In the response you’ll see 200 in the header; you successfully sent me a message (Thanks!). But you’ll also see a bit lump of data, giving the ID of the message, the text, and some information about yourself in the sender` collection. This ‘echoing what you sent’ approach is fairly common in WebAPIs as it lets you verify that what you asked to happen, happened.


And that’s most of the more difficult bits of working with a Web API. In the final post of this series I’m going to hopefully get you started on some of the APIs that have some more practical use to you civil engineers out there.

Submit a Comment

Leave a Reply

This site uses Akismet to reduce spam. Learn how your comment data is processed.