REST API Reference

General

Right now, we use plain API-key authentication. It's generated by the server for the user to copy and paste into their code, and returned as the last path segment in every REST request, for example: /streams/twitter.com/followers/SCREEN_NAME/FOLLOWER_COUNT/API_KEY => /streams/twitter.com/followers/twitterapi/100/87698769876

Errors are standardized as following the format {"error": "text ..."} but were not always that way. If you find an errant error message, please submit a bug report.

Twitter also imposes rate limits, so you cannot use any of these methods to scan all the world's tweets, or to investigate all the world's friends. In fact, you only get a few thousand followers at most, and a similar number of tweets, every 15 minutes. Think about how many nodes you are expanding before you get started or else you will be quickly frustrated. That said, we cache the results, so a good plan will still yield a huge graph if you start ahead of time.

Note that it has not been decided whether users will be able to share follower caches. In the future, it may be that classes will be able to expand larger graphs as long as all the students choose the same (or closely related) Twitter users.

Follower graph

Using the follower graph, students can interact with the Twitter follower graph using proxy objects. With only a few lines, it creates a very large and rather interesting source of information useful for

Follower list for a specific user

• Parameters
• screen_name: The user's twitter screen name. It's passed along unchanged.
• count: Return at most this many names
• api_key: See above
• Format: GET /streams/twitter.com/followers/screen_name/count/api_key
• Example: GET /streams/twitter.com/followers/twitterapi/100/87698769876
• Result:

{"followers": ["fred", "joe", "bob", "suzy", "cathy"]}

Visualization

• Parameters
  • assignment: The ID associated with the assignment, specific to each student and class
  • api_key: See above
• Format: POST /assignment/assignment_id/api_key
• Example: POST /assignment/9089083731/87698769876
• Uploaded data (as POST parameter history):
  • kind[String]:
    • implemented: "node", "edge"
    • unimplemented: "highlight"
  • time[String]:
    • Implemented as nanoseconds since the epoch, but CPU time, or relative to process start would work.
    • Should be nanoseconds in order to make meaningful comparisons between programs
    • Use a String, in order to support full 64 bits. (Otherwise JSON limits range)
  • from[String]:
    • For an edge, this is the existing node (the one currently being opened)
    • For a node, this is the only screen_name
    • In the future, there could be reasons for it to be null.
  • to[String]:
    • For an edge: either the newly created node, or one that existed before, but not the same node as from.
    • For a node: null

{"history": [
    {"kind":"node",
     "time":"16595277687248",
     "from":"sean_tate",
     "to":null},
     {"kind":"edge",
     "time":"16595277689163",
     "from":"sean_tate",
     "to":"fred_jones"},
     {"kind":"edge",
     "time":"16595277691625",
     "from":"sean_tate",
     "to":"ed_krantz"}
]}

Streams

Streams are a work in progress, and will enable students to query tweets from various public sources. The purpose of streams is somewhat different, and may allow students the opportunity to do projects such as text classification, parsing, or other tasks as homework is developed.