RESTful web services 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. 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 a programming part and some reflective questions. 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 name 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.1/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
Gender
Last name
Location
Premium
Website
You can choose whether you use XML to communicate with the service or JSON.
Avoid the use of simple string concatenation (Percent encoding of parameters is handled automatically in many libraries )
Try your implementation with weird passwords like I am ~" extra" #carefüll with my p@ssw0rds世界
When using other programming languages as Java, add used external libraries to the repository (Java, see below).

Returning the task###

Put the parts you created yourself to your git repository and add the teacher (username miselico as a collaborator to your repository) Yousource ( https://yousource.it.jyu.fi/) is the universities git server. Include a class with a ‘main function’ or equivalent to test your class.

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 downloaded from http://hc.apache.org/downloads.cgi (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.

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) 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).

6) 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://www.ibm.com/developerworks/library/x-javaxpathapi/index.html.

7) It is not obligated to use the XML representation. Also JSON is possible, remember to put the response_format to json. You can use http://json-lib.sourceforge.net/ as a JSON library in this exercise. This library simplifies the use of Java bean classes like the provided UserInfo class. For more information see http://json-lib.sourceforge.net/usage.html#objects. Remember to also put the dependencies of the JSON library on the build path! This library requires (search google for download. Mind the version numbers):

jakarta commons-lang 2.5
jakarta commons-beanutils 1.8.0
jakarta commons-collections 3.2.1
jakarta commons-logging 1.1.1
ezmorph 1.0.6

Alternatively, one can use the reference implementation from https://github.com/douglascrockford/JSON-java which does not depend on external libraries, but does not provide automatical tools for interaction with java bean classes.

Michael Cochez