Server API Docs

This page will contain a description on how to use the web API in the GeoChats application.
The server is now located at http://abettadapur.dynathome.net:3000

Background

The server that hosts the API is written in nodeJS, a serverside javascript library. It also uses the NodeJS module Express, which allows for easy creation of websites with complex routes and methods. All data that is received through the API is stored in a MongoDB instance, which supports scale-ability in the future through possible sharding and clustering More information can be found at http://nodejs.org http://expressjs.com http://mongodb.org

Authentication

Creating a User Account

User accounts are easy to create in the database. To create a new user account, you must send a HTTP POST request to /users. In this POST request, you must include a JSON object that describes the user you are trying to create. Here is an example POST body:

{"username":"georgepburdell@gatech.edu", "password":"jackets"}

If the username does not already exist in the database, the user will be created and his information will be returned to you in another JSON object. Make sure to set the Content-Type header of your POST request to 'applcation/json'

Logging in

Sessions in GeoPhotos are managed with tokens. This allows for single sign on in mobile apps.
To request a token, send a POST request to /users/login with a JSON object that describes the login credentials. It should be identical to the create user object.
Provided your credentials are correct, the server will create a token for you and return it in a JSON object

{
"result:":"Success",
"token":"6ajqdgbn5dhd7vin0520i7u11ulq5mi"
}

You should store this token somewhere as it will be needed to authenticate future requests

Logging out

To log out, send a POST request to /users/logout with either the token of the session you wish to send or the username of the session you wish to send.

{
"username":"georgepburdell@gatech.edu",
"token":"your token here"
}
This request will end the session and make the authentication token invalid on future requests. To request a new token, you must log in again.

Dealing with Photos

Uploading a photo

Currently, a photo can be uploaded with a few metadata tags through the use of an HTTP POST Multipart request. This is the same type of request that is commonly used in web-forms and is the easiest way to send files via HTTP. All photo upload requests must be authenticated using a token. It should be added as a parameter in the multipart request. Every library has a different way of implementing multipart requests. What follows is the correct method for Android.

You must include the httpmime 4.x jar from the Apache HttpComponents http://hc.apache.org for this to work on Android.

Once you have a path to the file you want to upload, you must create a request.

HttpClient httpClient = new DefaultHttpClient();
HttpContext localContext = new BasicHttpContext();
HttpPost httpPost = new HttpPost("http://192.168.56.1:3000/photos");

Here, we have created a simple POST request to the API endpoint. Note, of course, that the ip and port may change.

We must now create a multipart entry and fill it with our data, including the File, any metadata we want to attach, and the authentication token we will be using

try
{
    MultipartEntity entity = new MultipartEntity(HttpMultipartMode.BROWSER_COMPATIBLE);
    File photo = new File("/sdcard/image.png");
    entity.addPart("userImage", new FileBody(photo));
    entity.addPart("title", new StringBody("Fireworks"));
    entity.addPart("token", new StringBody("6ajqdgbn5dhd7vin0520i7u11ulq5mi");
    httpPost.setEntity(entity);

Notice that we create a new File using the image path and add it to the entity. "userImage" is the title of this "Part" and must be called userImage for the API to recognize the file.
We also add a "StringBody" to the request and call it title. I have not yet figured out all the data we need and what it should be called, but it should all be added in this manner.
Currently, I have implemented "title", "description", "latitude", "longitude", and "bearing". These should all be added in a StringBody

Finally, we add the entity to the post request.

~~~~java

HttpResponse response = httpClient.execute(httpPost, localContext);
Log.e("response",response.getStatusLine().toString());

}
catch (IOException e)
{
Log.e("Error", e.getStackTrace().toString());
}
~~~~~~

Now that we have created a POST request, the last part is just to send the request as above. The photo then will be uploaded to the server and stored in the MongoDB with all the StringBody parameters specified. The server will then send a response in JSON format with the unique id of the photo you just stored. You will need this to later retrieve the photo

Remember of course, that this must all occur within an AsyncTask on Android

Retrieving a photo

To retrieve a photo's metadata, navigate to photos/id/:id, where :id is the unique id returned to you when you added the photo. This will return a JSON object with the metadata about the photo as well as a URL where you can retrieve the image itself. This url is located at /photos/images/:id.

Deleting a photo

To delete a photo, send a HTTP POST request to /photos/delete. The request must contain the ID of the photo and the authentication token of the user to which the photo belongs. If the ID exists in the database, the photo will be removed from the database and deleted.