inveniosoftware/invenio — pull request #2171 by Fodaro (2014-08-29 12:37:06+00:00)
Title: WIP: Add a mobile API module

While I've been working on the mobile app (see the [pull request on the Invenio Mobile repository](https://github.com/inveniosoftware/invenio-mobile/pull/1)) I've been testing it using a simple Flask application which implements the mobile app REST API using sample data. This pull request contains that Flask application as an Invenio module. A full API specification is available in my openlab report, which will be available [on the openlab website](http://openlab.web.cern.ch/publications/technical-documents?field_document_type_value=student_report) soon.

Setting up for testing
======================

To use this module for testing without OAuth, you can simply run Invenio as normal, add your local Invenio server as a source (an example URL is `myhostname.cern.ch:4000`). The app will request the API info file and work the rest out from there. If you don't want to test using OAuth, touch 'No' on the next screen.

Testing with OAuth
------------------

To test with OAuth, Invenio Mobile must be added as an application on the server. On the Application settings page of your Invenio server, add a new application. The values of the fields do not particularly matter at this point.

### A note on redirect URIs ###

As the app is not a typical Web application, the redirect URI doesn't really matter. During the authentication process, the app will check every URL that the in-app browser tries to load, looking for one with an authentication token or an error. The URL doesn't even have to be one that exists, as the page does not need to load for the app to check the URL. The important thing is that the redirect URI points to a trustworthy location, as any page at that location can acquire the access token.

For testing (where the Invenio server does not support HTTPS) I've been using `http://localhost:4000/`. This should not be done on production servers, as a malicious app on the user's phone could open port 4000 and acquire the access token. Instead, the redirect could be to the server's home page, or to a blank page hosted by the server.

### Setting the authentication URL ###

Once the application has been added, the `authentication_url` field of the `/api/info` response must be changed accordingly. For now, this is done by manually changing the `info.json` file. Copy the URL of the 'example request' link on the Application settings page, and change the following parameters:
* `state` (originally `CHANGEME`) to `{STATE}`
* `response_type` to `token`.

Finally, put the modified URL into the `authentication_url` field in `info.json`.

### Signing in from the app ###

You should now be able to log in to your Invenio server from the app. When prompted by the Add Source screen, touch 'Yes'. A web browser will appear, which should let you log in and authorise the application. Once you are logged in, do a search and maybe open a record. Each request will appear in the server log, preceded by the access token.