Programming with the Twitter API

This course will become read-only in the near future. Tell us at community.p2pu.org if that is a problem.

Task Navigation 

Channel Your Vision


With your query in mind, learn about the Twitter API

This task is about getting familiar with the Twitter Application Programming Interface, or API. Load up the Twitter API docs

If you have never used an API before, never fear. You'll notice that there's a lot of information that you need to sift through!  An API call is like a way to execute a function call on someone else's computer, in this case a server hosted by a large company. Reading the API docs is basically your ticket to understanding what function calls are allowed, how you need to format them, and what information they will return. 
 
Browse through the different "resources." Click through to the full descriptions of different resource calls. You'll notice that some require authentication, which is a topic we are not covering in this challenge. But several of the available API calls do not require authentication, including search!
 
A very cool thing about restful APIs (hint) is that they make use of the same protocol that your browser uses to display web pages: HTTP. As a result, what we described as a "function call" above is just a regular old URL. The upshot is that if you construct your API call and paste it into your URL bar, it will display the results right there in your browser! What better way to take the API for a casual test run?
 
Try out the unauthenticated user_timeline API call. Start out with this basic construct for the API call:
 
 

 

If you click on this link you should a JSON-formatted response in your browser. (You may want to stop and marvel at how cool it is that this is literally just a bunch of plain old text that Twitter's servers just sent you, and that you can use this important plumbing to build fantastic and wonderful web applications of untold complexity). Try adding different arguments to the url, as outlined in the docs. That's not too hard, eh? 

Answer these questions as you go. 

  1. What are some of the fields returned in the user_timeline API call? What are some of the different data types (eg. string, date, integer...) 

  2. What happens when you try to submit an API call that is broken? 

  3. A "path style" API call looks like example.com/api/username/search/search-term. An argument-style query uses argument strings such as example.com/api?person=username&search=search_term. How are Twitter's queries constructed? Can these formats be combined? Why might you use one versus the other in different circumstances? (Note that these questions are the subject of endless discussions amongst web developers. There is some well-known wisdom here but not necessarily a "right" answer, so treat these questions as fodder for discussion and raising new questions-- and don't spend TOO much time on it).  

  4. You will often hear people describe the Twitter (and other) APIs as "rest-ful." What makes something a "restful" API?  

Once you're done with these, you should feel comfortable formatting query parameters, submitting queries in your browser, and visually parsing long ugly blurbs of JSON text. Hooray! On to the next task. 

Task Discussion


  • Jos said:

    The API returns all types of JSON fields, nulls, booleans, dates, and so on but if you are just consuming the object I'd say they are all strings, so you will have to parse the JSON object on the client side if you want to make use of the types.

    Regarding broken calls, for what I've seen it actually depends on how broken the call is. If you have a typo in one of the arguments for instance, say you type trimuser instead of trim-user, the call will work anyway as if the parameter was not there, which I guess it can be good and bad. A more broken call such as forgetting the value of screen_name produces a not very helpful error:

    {

        error: "This method requires authentication.",

        request: "/1/statuses/user_timeline.json?screen_name"

    }

    Not very helpful to tell you that you need to authenticate when your error is actually having forgotten a value!

    I really like the count parameter to restrcit the number of results you get back, and also the trim_user parameter cause it seems that for every result it sends back a full user object within in, so you can trim that object to grab just the id of the user.

    Regarding the last two questions, my view on construction of URLs is that it should be path-style for resources and argument-style to pass parameters for instance for search. REST is about representation of resources so those resources should be (in my view) well defined through paths. When you want to pass in parameters then arguments are good. But it's just my view on it!

    on March 14, 2012, 6:28 a.m.

    Jessy Kate Schingler said:

    +1 :)

    on March 14, 2012, 3:44 p.m. in reply to Jos

    dpino said:

    Good explanation about path-style vs argument-style. The way I see it is like in a restful architecture a path means a resource or a set of resources, so if different paths should return different types of resources it makes sense to codify their URIs using different paths. Argument-style modifies the way a resource or a set of resources is retrieved. For instance,

    http://p2pu/courses/twitter/students.json (all students in the twitter course in p2pu) (path-style only)

    http://p2pu/courses/twitter/students.json?sort=alpha&count=20 (the first 20 students in the twitter course in p2pu sorted in alphabetical order). (path-style with arguments)

    My point is that path-style URIs and argument-style URIs are not something exclusive, but sometimes it's possible and makes sense to combine them.

    on March 27, 2012, 6:34 p.m. in reply to Jos

    Newman5 said:

    This makes sense to me.  You've made a clear case for how they are used in conjunction.  Is there ever a need for either style exclusively?

    It seems to me you will always need a resource (path style) and parameter communication (argument style)

    Anyway, happy to learn this 'cause it might help me sound cool at a cocktail party celebrating my awesome job promotion or app release or ... someplace I've just crashed ... or over thanksgiving dinner trying to make my aunts think I'm a real, live internet whiz.

    :)

    on April 1, 2012, 4:13 p.m. in reply to dpino

    Eenvincible said:

    Yeah, it is fun having something new to talk about during dull dinner parties! You sit there and then shoot something like : RESTful APIs are so cool etc. I can envision myself doing just that!

    Please check out my blog at:

    http://simpledeveloper.wordpress.com/2012/12/31/channel-your-vision-call-me-maybe-api/

    Thanks

    on Dec. 31, 2012, 6:12 p.m. in reply to Newman5