A simple REST client exercise

Goal

Learn to use a RESTful API. The API used here is an example, the goal is that the student can use the experience from implementing against this RESTful API in another context as well.

Prerequisites

Learn what a RESTful webservice is. A first source could be the following IBM article https://www.ibm.com/developerworks/webservices/library/ws-restful/ also interesting is the wikipedia article http://en.wikipedia.org/wiki/Representational_state_transfer. Interested readers can also read the original doctoral dissertation in which Roy Fielding introduced representational state transfer (REST) http://www.ics.uci.edu/~fielding/pubs/dissertation/top.htm mainly chapter 5 is of interest. It is however not required to read it. The student is supposed to have basic knowledge about xml and/or json. Also basic knowledge of the HTTP protocol is useful (see also the wikipedia article about it at http://en.wikipedia.org/wiki/Hypertext_Transfer_Protocol).

Task

This assignment contains only a programming part. The service used is http://www.mediafire.com/. Before starting, the student has to create an account at the service, do this using password authentication. Once logged in, click on your user logo and select Account settings then select Developers and create a new application. You will need the App ID and API Key for in the code which you will write for this exercise. The RESTful API of mediafire is described on this webpage http://www.mediafire.com/developers/core_api/1.4/getting_started/ , read trough the description of the interface. (You can also find an SDK from other parts of the developer documentation, but you cannot use it for this exercise since it hides all HTTP communication, which is exactly what this exercise is about.)

You are expected to create a method/function/… with four string parameters (APP_id, API_key, email, password) this method/function/… should return an object/struct/type/… from which the following information can be obtained:

Birth date
Display name
Email
First name
Last name
Gender

You need to make two API calls. The first one will log you in to the mediafire service. See user documentation
Information returned by that call will be used in the next call to get user info
You can choose whether you use XML to communicate with the service or JSON.
Do not use simple string concatenation to create URLs (Percent encoding of parameters is handled automatically in many libraries )
You have to test your implementation with weird passwords like a ~'goöd\" #p@ssw0rd世界 (remember to escape this properly if you hard code your password in your program "a ~'goöd\\\" #p@ssw0rd世界")
You must use the library management tools which are available for the language you choose (Java: maven, Python: pip/easy_install, etc.) if you are using external libraries. If you are using a rare programming language (ask the teacher), add used external libraries to the repository.

Returning the task###

Clone the teacher’s repository in yousource git@yousource.it.jyu.fi:ties456-2015/week37.git and add the teacher as a collaborator. Put the parts you created yourself to your git repository and add the teacher (username miselico as a collaborator to your repository) Include a class with a ‘main function’ or equivalent to test your class. Use of dependency injection and writing proper unit tests is encouraged, but not obligated.

Hints (General)

1) It is not necessary to check the e-mail address for validity.

2) The class does not need to be thread-safe.

3) The Mediafire API advises to use Session token 2 instead of type 1. For this exercise, version 1 might be simpler, though.

4) You need to make two HTTP GET calls in order to retreive the information. First, you need to log in to the service. Then, with the information obtained you can retreive the required data.

5) You are allowed to use the programming language which you want. If you are not using one of C, C#, C++, Coffeescript, Go, Haskell, Java, Javascript, Lua, Perl, PHP, Python, Ruby, Scala, or Qt verify with the teacher whether this is a reasonable choice.

Hints (Java specific) compiled from previous years when only Java was allowed.

1) It is advised to use the HttpClient from the apache software foundation which is documented on http://hc.apache.org/httpcomponents-client-ga/ and can be configured using dependency information from http://hc.apache.org/httpcomponents-client-ga/httpclient/dependency-info.html (Only the binary versions of HttpClient and HttpCore are needed - do not use the OSGI bundles.) Look trough the quickstart guide at http://hc.apache.org/httpcomponents-client-ga/quickstart.html to get started.

2) You can use, for instance, org.apache.http.client.utils.URIBuilder, for building URIs in a safe manner

3) In Java, you are encouraged to use Maven to manage all your dependencies (There are some other dependency managers as well).

4) For the sha-1 algorithm, you can use the org.apache.commons.codec.digest.DigestUtils class (which is included in the above mentioned libraries) and do

    digest = DigestUtils.shaHex(original);

5) To extract, for instance, the token from the received XML, one can use code similar to the following:

    XPathFactory factory = XPathFactory.newInstance();
    XPath path = factory.newXPath();
    String token = path.evaluate("/response/session_token", new InputSource(xmlstream));

This snippet uses XPath to extract the token from the XML document. For the interested student familiar with XML, there is an article on XPath to be found at http://docs.oracle.com/javase/tutorial/jaxp/xslt/xpath.html. An older article : http://www.ibm.com/developerworks/library/x-javaxpathapi/index.html.

6) Also for extracting data from JSOn there are multiple options. For example : http://code.google.com/p/json-simple/ and https://github.com/google/gson

6) Some might get a stacktrace which starts as follows :

    Exception in thread "main" javax.net.ssl.SSLPeerUnverifiedException: peer not authenticated
    at sun.security.ssl.SSLSessionImpl.getPeerCertificates(SSLSessionImpl.java:371)
    at org.apache.http.conn.ssl.AbstractVerifier.verify(AbstractVerifier.java:128)
    ... This means that you have problems with certificates when calling the server. Make sure you have java jdk installed and then follow the steps as per [this website](http://web.archive.org/web/20130528113939/http://my.opera.com/karmazilla/blog/how-to-grab-the-certificate-from-a-website-and-import-it-with-java-keytool). (The website assumes you are using linux. For windows see [https://forum.startcom.org/viewtopic.php?f=15&t=1678](https://forum.startcom.org/viewtopic.php?f=15&t=1678).)  You can download the certificate from the course website [here](mediafire.crt).

Michael Cochez