Merge branch 'docs' into dev

README.md

-# PEDASI
+# PEDASI v0.1.0
 
-PEDASI is an Internet of Things (IoT) Observatory demonstrator platform.
+Developed as a platform and a service to explore research challenges in data security, privacy, and ethics, PEDASI enables providers of data - particularly [Internet of Things](https://en.wikipedia.org/wiki/Internet_of_things) data - to share their data securely within a common catalogue for use by application developers and researchers. Data can either be hosted and made accessible directly within PEDASI as an internal data source, or hosted elsewhere and accessible as an external data source through PEDASI.
 
-It functions as middleware between data sources and applications to provide a testbed for investigation of
-research questions in the domain of IoT.
+An initial deployment of the platform is available at https://dev.iotobservatory.io.
 
+## Key Features
 
-## Running / Deploying PEDASI
+PEDASI’s key features are:
 
-### In Development
-To run PEDASI locally during development you will need to install and run:
+ - Searchable catalogue of supported data sources registered by data owners
+ - Extensible connector interface that currently supports HyperCat and IoTUK Nation Database data sources
+ - Dataset discovery and access via a web interface or via an Applications API
+ - Queryable and extensible metadata associated with datasets
+ - Adoption of W3C PROV-DM specification to track and record dataset creation, update, and access within internal datastore
+ - Internally hosted support for read/write NoSQL datastores
+ - Functions as a reverse proxy to data sources, returning data from requests exactly as supplied by the data source
 
-* MySQL server
-  * Create a schema to hold the PEDASI core database tables
-* MongoDB server
-  * Create a database to hold the PEDASI PROV collections
+## Release Notes
 
-It is recommended that you then create a Python virtual environment in which to run PEDASI.
-The Python requirements are described in the `requirements.txt` file.
+This is a public alpha release, and therefore features and functionality may change and the software and documentation may contain technical bugs or other issues. If you discover any issues please consider registering a [GitHub issue](https://github.com/PEDASI/PEDASI/issues).
 
-PEDASI can be run using the Django development server by `python manage.py runserver`.
+## Documentation
 
-### In Production
+Documentation is available on [readthedocs](https://pedasi.readthedocs.io/en/master/) for users, system administrators, data and application providers, and application developers, and is also installed within a PEDASI deployment (e.g. at https://dev.iotobservatory.io/static/html).
 
-This repository contains an Ansible `playbook.yml` file which will perform a full install of PEDASI onto a
-clean host running Ubuntu 18.04 LTS, or update an existing PEDASI instance if it was previously deployed with the same script.
+## Contact Information
 
-To deploy using production settings you must:
-* Create an Ansible inventory file and set `production=True` for the machine you wish to deploy to
-* Create an SSH key and register it as a deployment key on the PEDASI GitHub project
-  * Move the SSH private key file to `deploy/.deployment-key`
-* Create a configuration file (see below) `deploy/.env.prod`
-* Run the Ansible deployment script `ansible-playbook -v -i inventory.yml playbook.yml -u <remote_username>`
+ - Project team: Adrian Cox (a.j.cox@soton.ac.uk), Mark Schueler (m.schueler@soton.ac.uk)
+ - Development team: James Graham (j.graham@soton.ac.uk), Steve Crouch (s.crouch@ecs.soton.ac.uk)
 
+## Licence
 
-## Configuring PEDASI
-Both PEDASI and Django are able to be configured via a `.env` file in the project root.
+PEDASI is provided under the MIT licence - see the [LICENCE.md](LICENCE.md) file for details.
 
-The only required configuration property is the Django SECRET_KEY which should be a randomly generated
-character sequence.
-
-Other configuration properties are described at the top of `pedasi/settings.py`.

docs/source/conf.py

@@ -24,7 +24,7 @@ django.setup()
 # -- Project information -----------------------------------------------------
 
 project = 'PEDASI'
-copyright = '2018, James Graham, Steve Crouch'
+copyright = '2019 University of Southampton'
 author = 'James Graham, Steve Crouch'
 
 # The short X.Y version
@@ -121,6 +121,13 @@ html_static_path = ['_static']
 #
 # html_sidebars = {}
 
+# Add following as a header for each rst file
+rst_prolog = """
+.. note:: This is a public alpha release, and therefore features and functionality may change and the software and documentation may contain technical bugs or other issues. If you discover any issues please consider registering a `GitHub issue`_.
+
+.. _`GitHub issue`: https://github.com/PEDASI/PEDASI/issues
+"""
+
 
 # -- Options for HTMLHelp output ---------------------------------------------
 

docs/source/guide_administrator.rst

+.. _guide_administrator:
+
+PEDASI System Administrator Guide
+=================================
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Contents:
+
+
+.. note:: Please read the :doc:`User Guide<guide_user>` first to give you an overview of the PEDASI platform and how to use its features before reading this guide.
+
+
+Purpose
+-------
+
+This guide is for system administrators wishing to deploy a PEDASI instance, either for production or locally for development.
+
+
+Production Deployment
+---------------------
+
+Overview
+^^^^^^^^
+
+A deployment of PEDASI is done automatically to a remote Ubuntu server via a preconfigured Ansible script, which performs the following tasks:
+
+ 1. Install prerequisites
+ 2. Configure databases
+ 3. Install PEDASI
+ 4. Configure and start webserver
+
+See the *playbook.yml* Ansible file in the PEDASI repository's root directory for more details.
+
+
+Prerequisites
+^^^^^^^^^^^^^
+
+Ensure you have the following prerequisites before you begin:
+
+ - Ubuntu 18.04 LTS server with:
+
+   - The latest security updates
+   - A static IP address
+   - A user account with external SSH access enabled and with sudo access privileges (e.g. 'ubuntu' - ubuntu will be used throughout this documentation) 
+
+ - A Linux or Mac OS X local machine with the following installed:
+
+   - Ansible v2.7.1 or above
+   - Git command line client v2 or above
+
+
+Cloning the PEDASI Repository
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+On your local machine, first clone the PEDASI repository:
+
+.. code-block:: console
+
+   $ git clone https://github.com/PEDASI/PEDASI.git
+
+
+Configuration
+^^^^^^^^^^^^^
+
+It it necessary to provide some configuration before deploying PEDASI.
+
+ 1. Tell Ansible to which machine PEDASI should be deployed:
+
+   .. code-block:: none
+      :caption: inventory.yml
+
+      [default]
+      hostname.domain
+
+ 2. Provide required configuration for Django - the required and optional settings are described in :mod:`pedasi.settings`.
+    The required settings are:
+
+   .. code-block:: none
+      :caption: deploy/.env
+
+      SECRET_KEY=<random string>
+
+      SOCIAL_AUTH_GOOGLE_OAUTH2_KEY=<Google OAuth2 key>
+      SOCIAL_AUTH_GOOGLE_OAUTH2_SECRET=<Google OAuth2 secret>
+
+
+Deployment
+^^^^^^^^^^
+
+You may now deploy PEDASI using the Ansible provisioning script. If you have set up your Ubuntu instance to use SSH passwordless access, do the following:
+
+.. code-block:: console
+
+   $ ansible-playbook -v -i inventory.yml playbook.yml -u <your username on the remote host>
+
+Otherwise, you will need Ansible to prompt for passwords for the remote user and superuser accounts:
+
+.. code-block:: console
+
+   $ ansible-playbook -v -i inventory.yml playbook.yml -u <your username on the remote host> -k -K
+
+
+Create Administrator Account
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+After deploying PEDASI you must create and activate an initial PEDASI Central Administrator account:
+
+.. code-block:: console
+
+   $ sudo -s
+   $ cd /var/www/pedasi
+   $ source env/bin/activate
+   $ python manage.py createsuperuser --username <username> --email <email address>
+
+Once created, you can access your deployment at https://<server_address>.
+
+
+Assigning Data or Application Provider Roles to Accounts
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+To add Data and/or Application Provider roles to an existing PEDASI User account:
+
+ 1. Ensure you are logged in as the PEDASI Central Administrator account
+ 2. Go to the administrator pages at https://<server_address>/admin
+ 3. Select *Users* from the *PROFILES* subsection to display a list of all system users
+ 4. Select the user account you wish to change, to edit that user's profile
+ 5. Under the *Groups* section under *Permissions*, select *Data Provider* or *Application Provider* and select the right arrow to add this role to the user's profile
+ 6. Select *SAVE* at the bottom of the page
+
+
+Development Deployment
+----------------------
+
+Overview
+^^^^^^^^
+
+A development instance of PEDASI can be automatically and rapidly deployed using Vagrant. It uses VirtualBox as a virtual machine (VM) management tool to provision a Vagrant-style VM and provisions a PEDASI instance within that VM.
+
+
+Prerequisites
+^^^^^^^^^^^^^
+
+Ensure you have the following prerequisites before you begin:
+
+ - A Linux or Mac OS X local machine with the following installed:
+
+   - Vagrant v2.2.0 or above
+   - VirtualBox v5.2.0 or above
+   - Git command line client v2.0 or above
+
+
+Cloning the PEDASI Repository
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+On your local machine, from a shell first clone the PEDASI repository:
+
+.. code-block:: console
+
+   $ git clone https://github.com/PEDASI/PEDASI.git
+
+
+Configuring Deployment
+^^^^^^^^^^^^^^^^^^^^^^
+
+First, check the settings in the *Vagrantfile* in the repository's root directory to ensure any provisioned VM will not conflict with any other resources running on the default ports.
+
+Then create a new *.env* file in the repository's *deploy/* directory with the following contents (replacing *some_test_key* with a string of your choice):
+
+::
+
+   SECRET_KEY=some_test_key
+   DEBUG=true
+
+
+Managing Deployment
+^^^^^^^^^^^^^^^^^^^
+
+To deploy the Vagrant instance, provision the instance, and deploy PEDASI within it, within the PEDASI repository root directory:
+
+.. code-block:: console
+
+   $ vagrant up
+
+The Vagrant instance will now be visible within VirtualBox, and the PEDASI service visible from a browser at http://localhost:8888/.
+
+To access the Vagrant instance from the command line:
+
+.. code-block:: console
+
+   $ vagrant ssh
+
+Please see the `Vagrant documentation`_ for more details on how to use Vagrant, including shutting down and destroying Vagrant instances.
+
+.. _`Vagrant documentation`: https://www.vagrantup.com/docs/
+
+
+Creating Administrator and Provider Accounts
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Follow the instructions in the *Create Administrator Account* subsection of the *Production Deployment* section above to set up an administrator user, as well as the *Assigning Data or Application Provider Roles to Accounts* subsection if required for other non-administrator users.
+
+
+References
+----------
+
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`

docs/source/guide_developer.rst

+.. _guide_developer:
+
+PEDASI Developer Guide
+======================
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Contents:
+
+
+.. note:: Please read the :doc:`User Guide<guide_user>` first to give you an overview of the PEDASI platform before reading this guide.
+
+
+Purpose
+-------
+
+This guide is for application developers wanting to understand how to set up a development environment for PEDASI and develop PEDASI applications.
+
+
+Developing an Application
+-------------------------
+
+The following sections will walk you through using the PEDASI Applications API in your own applications. We will use the JavaScript IoTUK Nation Map Demo application (see https://github.com/Southampton-RSG/app-iotorgs-map) as a basic example. These instructions assume you are aiming to develop against a production deployment of PEDASI managed buy a Central Administrator, but you can also use a local development deployment if you wish. This section assumes you already have a registered PEDASI account,
+
+
+Adding Required Data Sources
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Firstly, you'll need to ensure that the data sources your application aims to use are added to PEDASI, which require Data Provider account privileges. If you do not already have these privileges on your PEDASI account, either:
+
+ - Contact your local PEDASI Data Provider to register the data sources
+ - Contact the PEDASI Central Administrator to register the data sources
+ - Contact the PEDASI Central Administrator to request Data Provider privileges for your account
+
+For simplicity, this guide assumes that the data source is being added with a public level of access (i.e. at the DATA level), so that the application will not need to have its access level approved via a request.
+
+If you now have these privileges and wish to add the data sources yourself, follow the *Adding a Data Source* section in the :doc:`Data and Application Provider Guide<guide_provider>` (which also contains details for adding the IoTUK Nation Data as a data source).
+
+Once these data source(s) have been registered, note the API query URL for each of them that you intend to use in your application. For each data source, this can be obtained by visiting the *Detail* page for a data source from the data sources list, which you can find via the *Data Sources* link in the PEDASI top navigation bar.
+
+
+Obtaining an Application API Key
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+You will first need to register some basic application details to obtain an API key for your application to authenticate with PEDASI, which requires Application Provider account privileges. If you do not have these privileges on your PEDASI account, either:
+
+ - Contact your local PEDASI Application Provider to register the application and obtain an API key
+ - Contact the PEDASI Central Administrator to register the new application and obtain an API key
+ - Contact the PEDASI Central Administrator to request Application Provider privileges for your account
+
+If you now have these privileges and wish to add the application yourself, follow the *Adding an Application* section in the :doc:`Data and Application Provider Guide<guide_provider>` (which also contains details for adding the IoTUK Nation Map Demo application).
+
+
+Code Examples
+^^^^^^^^^^^^^
+
+Once you have the required data sources and application set up in PEDASI, you can begin using the API. For example, with the IoTUK Nations Database, assuming the API query URL for it is https://dev.iotobservatory.io/api/datasources/2/data.
+
+
+Using cURL
+~~~~~~~~~~
+
+An easy way to first test and see the output is using the command line tool *cURL* available under Linux (and installable on Mac OS X), which allows you to make requests from a RESTful API and see the results. Strictly speaking, since we're assuming it is using a publicly accessible data source, we do not need to supply any application API key. However, for completeness and for best practice, we can include it in the request:
+
+.. code-block:: console
+
+   $ curl -H "Authorization: Token <api_key>" "https://dev.iotobservatory.io/api/datasources/2/data/?town=Southampton"
+
+Then we should see something like the following (although without the formatting):
+
+.. code-block:: none
+
+   {
+     "results": 9,
+     "data": {
+         "1": {
+             "organisation_id": "2018_590",
+             "organisation_name": "2IC LIMITED",
+             "organisation_type": "ltd",
+   ...
+
+
+Using Python
+~~~~~~~~~~~~
+
+We can duplicate the cURL request above in Python 3. Creating a new Python file (e.g. *api-test.py*) with the following contents:
+
+.. code-block:: python
+
+   import sys
+   import requests
+
+   url = "https://dev.iotobservatory.io/api/datasources/2/data/?town=Southampton"
+   headers = {
+       'Authorization': 'Token <api_key>'
+   }
+   response = requests.get(url, headers=headers)
+   print(response)
+
+We can run this example using:
+
+.. code-block:: console
+
+   $ python api-test.py
+
+Which should display the same output as we saw with cURL.
+
+
+Using JavaScript - a Basic Example Application
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+An `example`_ hosted on GitHub is a lightweight JavaScript PEDASI web application that uses the PEDASI Applications API - see the GitHub repository and its README for more details on how to deploy and use it.
+
+.. _`example`: https://github.com/PEDASI/app-iotorgs-map
+
+
+Application API Documentation
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The :doc:`Applications API Reference<ref_applications_api>` documentation covers the API and its endpoints, and how to use it.
+
+
+References
+----------
+
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`

docs/source/guide_provider.rst

+.. _guide_provider:
+
+PEDASI Data And Application Provider Guide
+==========================================
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Contents:
+
+
+.. note:: Please read the :doc:`User Guide<guide_user>` first to give you an overview of the PEDASI platform and how to use its features before reading this guide.
+
+
+Purpose
+-------
+
+This guide is for Data or Application Providers wanting to add, update, or remove data sources or applications within a PEDASI instance.
+
+
+Data Providers: Managing Data Sources
+-------------------------------------
+
+In order for users to begin using PEDASI, you should provide access to a range of data sources. The following sections will walk you through adding and managing your first data source. We will use the IoTUK Nation Database API (see https://iotuk.org.uk/iotuk-nation-database-api/) as a basic example.
+
+If you are not a Central Administrator or don't have Data Provider privileges associated with your account, you'll need to obtain these first. Contact the Central Administrator to grant these privileges for your account.
+
+
+Adding a Data Source
+^^^^^^^^^^^^^^^^^^^^
+
+Before adding a new data source, first check if the licence type for that data source already exists. Select *Licences* from the navigation bar to display all current licences, and if the licence you need to use isn't already in the list, you'll need to add it as a new licence type. See *Adding a New Data Source Licence* below.
+
+To add a new data source:
+
+ 1. Select *Data Sources* from the PEDASI navigation bar to see a list of all data sources to which you have access
+ 2. Select *New Data Source* from the Data Sources page, and add in details for each of the following fields:
+
+    - *Name*: add in a unique name for this data source, such as 'UKIoT Nations'
+    - *Description*: optionally add in some specific details concerning this data source, such as its owner any links or references to any specifications or other documentation regarding the data source and format of the data that is delivered on request, e.g. some of the overview text at https://iotuk.org.uk/projects/iotuk-nation-database%E2%80%8B/ and a link to the page, and perhaps a link to the API details at https://github.com/TheDataCity/IoT-UK-Nation-Database-APIs. If the data source provides partially or fully encrypted data, also specify links to contact information and/or any reference material for obtaining a means to encrypt the data (not required for IoTUK Nations)
+    - *Url*: specify the base API URL for this data source, e.g. https://api.iotuk.org.uk/iotOrganisation.
+    - *Api key*: optionally specify an API key if one is required for PEDASI to access this resource
+    - *Plugin name*: select an appropriate data connector to interface with this API, e.g. DataSetConnector
+    - *Licence*: select an appropriate licence from those available in the dropdown list, e.g. Open Database Licence.
+    - *Is encrypted*: select this if the data supplied from the data source is partially or fully encrypted, e.g. leave unselected
+    - *Public permission level*: see the *Requesting Access to a Data Source* section in the :doc:`User Guide<guide_user>` for a breakdown of the different levels of access you can specify for a data source. e.g. DATA (which is the default)
+    - *Prov exempt*: select this if user activity tracking should be enabled for this data source, e.g. leave unselected
+
+ 3. Then select 'Create' to create this data source, and you'll be presented with an overview page for that data source.
+
+The next stage is to add in metadata for each of the parameters that can be used within the API. This step isn't mandatory, since arbitrary parameters can be specified via the Applications API or from within the Data Explorer, but is recommended. From the data source overview page, for each API query parameter (e.g. town, year, postcode for the IoTUK Nation Database data source):
+
+ 1. In the *Metadata* section, select *data_query_param* from the first dropdown
+ 2. Add the name of the API query field to the *Value* textbox, e.g. 'town'
+ 3. Select *Add* to add this query parameter
+
+Once complete, your data source is ready to use.
+
+
+Updating a Data Source
+^^^^^^^^^^^^^^^^^^^^^^
+
+To edit details for an existing data source:
+
+ 1. Select *Data Sources* from the navigation bar to see a list of all data sources to which you have access
+ 2. Select *Detail* for the data source you wish to edit
+ 3. Select *Edit* to edit the data source's details
+ 4. Edit the fields as instructed in the *Adding a Data Source* section
+ 5. Select *Update* to update the data source's details
+
+
+Removing a Data Source
+^^^^^^^^^^^^^^^^^^^^^^
+
+To remove an existing data source:
+
+ 1. Select *Data Sources* from the navigation bar to see a list of all data sources to which you have access
+ 2. Select *Detail* for the data source you wish to remove
+ 3. Select *Delete* to indicate you wish to remove the data source
+ 4. Select *Delete* to confirm you wish to remove this data source
+
+
+Adding a New Data Source Licence
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+If you need to add a new type of licence for a data source:
+
+ 1. Select *Licences* from the navigation bar to display all current licences
+ 2. Select *New License* to create a new licence
+ 3. Add detail for the following fields:
+
+    - *Name*: add a full name for a new licence, e.g. Open Database Licence
+    - *Short name*: add a short name for the licence, typically an acronym, e.g. ODbL
+    - *Version*: add the version number for the licence to use
+    - *URL*: add a link to an online resource describing the full terms of the licence
+
+ 4. Select 'Create' to create the licence, and you'll be presented with an overview page for that licence.
+
+
+Approving Data Access Requests
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+To approve user or application requests for amended access rights to data sources:
+
+ 1. Select *Data Sources* from the navigation bar to see a list of all data sources to which you have access
+ 2. Select *Detail* for the data source you wish to manage access on
+ 3. Select *Manage Access* to list access requests and manage those requests. You'll see the level of access requested for each user, their current access level, and the reason for the request
+ 4. Select either:
+
+    - *Approve*: to approve the request
+    - *Edit*: to amend the request's access privileges and data push rights (if data push is supported for this data source)
+    - *Reject*: to reject the request
+
+
+Application Providers: Managing Applications
+--------------------------------------------
+
+In order for a developer to access PEDASI's capabilities within their application, their application needs to be first registered within PEDASI in order to obtain an API key they can use to authenticate with PEDASI. The following sections will walk you through adding and managing your first application. We will use the IoTUK Nation Map Demo application (see https://github.com/Southampton-RSG/app-iotorgs-map) as a basic example.
+
+If you are not a Central Administrator or don't have Application Provider privileges associated with your account, you'll need to obtain these first. Contact the Central Administrator to grant these privileges for your account.
+
+
+Adding an Application
+^^^^^^^^^^^^^^^^^^^^^
+
+To add a new application:
+
+ 1. Select *Applications* from the PEDASI navigation bar to see a list of all applications to which you have access
+ 2. Select *New Application* from the Applications page, and add in details for each of the following fields:
+
+    - *Name*: add a full name for the application, e.g. IoTUK Nation Map Demo
+    - *Description*: add a brief description of the application, including what it aims to achieve using PEDASI
+    - *Url*: specify a public URL for the deployed application itself if it's web-based, or alternatively a source code repository URL if one exists, e.g. https://github.com/Southampton-RSG/app-iotorgs-map
+    - *Access control*: TODO: add in text here, e.g. leave unselected
+
+ 3. Select *Create* to register the new application within PEDASI, and you'll be presented with an overview page for that application, with a new API key
+
+The API key is what will be used by the developer to authenticate with PEDASI from their application, with the application acting as a user within the system.
+
+
+Updating an Application
+^^^^^^^^^^^^^^^^^^^^^^^
+
+ 1. Select *Applications* from the PEDASI navigation bar to see a list of all applications to which you have access
+ 2. Select *Detail* for the application you wish to edit. From here, you can also:
+
+    - Select *Revoke API Token*: to revoke the current API token which will prohibit its further use within PEDASI
+    - *If an API token has been revoked*, select *Generate API Token* to generate a new API token for this application
+
+ 3. Select *Edit* to edit the application's details
+ 4. Edit the fields as instructed in the *Adding an Application* section
+ 5. Select *Update* to update the data source's details
+
+
+Obtaining Access to Data Sources for Applications
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+As with users, applications also require access rights to data sources that are not public. By default, data sources are created with DATA access permissions and are considered public (awarding access to both data source metadata and data for all users, but not provenance records).
+
+If a data source has a lower level of access than required by the application, a request should be made from the Application Provider on behalf of their application for an appropriate level of access (typically DATA, the default). See *Requesting Access to a Data Source* in the :doc:`User Guide<guide_user>`.
+
+
+Removing an Application
+^^^^^^^^^^^^^^^^^^^^^^^
+
+To remove an application:
+
+ 1. Select *Applications* from the PEDASI navigation bar to see a list of all applications to which you have access
+ 2. Select *Detail* for the application you wish to remove
+ 3. Select *Delete* to indicate you wish to remove this application
+ 4. Select *Delete* to confirm you wish to remove this application
+
+
+References
+----------
+
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`

docs/source/guide_user.rst

@@ -8,6 +8,15 @@ PEDASI User Guide
    :caption: Contents:
 
 
+.. include:: release_note.rst
+
+
+Purpose
+-------
+
+This guide is for PEDASI users who want to understand the PEDASI platform and how to use its features.
+
+
 User Model
 ----------
 
@@ -77,22 +86,23 @@ Selecting *Details* for a data source from the Data Sources page shows the follo
  - *Metadata*: additional fields, listed by metadata type, for this data (e.g. data query parameters, etc.)
 
 
-Requesting Access to a Datasource
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Requesting Access to a Data Source
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-If you're logged in as a PEDASI User (and not anonymously), you may request access to a data source by selecting *Manage Access* from a data source overview page. From here you can supply the following details for an access request via a form:
+If you're logged in as a PEDASI User (and not anonymously), you may request access to a data source by selecting *Manage Access* from a data source overview page. Note that if you are also an Application Provider, you can also request access to data sources for your applications using this mechanism. From here you can supply the following details for an access request via a form:
 
- - The level of access, where a given level also provides access to previous levels:
+ - *User*: the identity of the user or application that is making this request (if making this request on behalf of an application, remember to set this to the identity of the application)
+ - *Requested*: The level of access, where a given level also provides access to previous levels:
 
    - *NONE*: to revoke access to a data source
    - *VIEW*: to view a data source's high-level details
    - *META*: to view a data source's metadata
    - *PROV*: to view a data source's PROV records
 
- - Push requested: to allow the data source to receive updates and/or new data from the user, where the data source supports it (currently only internal PEDASI data sources)
- - Reason: the reason for the request
+ - *Push requested*: to allow the data source to receive updates and/or new data from the user or application, where the data source supports it (currently only internal PEDASI data sources)
+ - *Reason*: the reason for the request
 
-The data source's Data Provider will then consider and optionally approve the request. Subsequent requests can be made by the user to either escalate or de-escalate their access level, each requiring approval.
+The data source's Data Provider will then consider and optionally approve the request. Subsequent requests can be made by the user or Application Provider to either escalate or de-escalate a user's or application's access level, each requiring approval.
 
 
 Using the Data Explorer
@@ -111,6 +121,12 @@ Selecting *Data Explorer* from the data source overview page shows an interface
 Results are presented in the Query Results panel precisely as returned by the data source.
 
 
+Upgrading an Account to Data and/or Application Provider
+--------------------------------------------------------
+
+If you already have a PEDASI User account and would like to add your own data sources or applications to a PEDASI instance, contact the PEDASI site's Central Administrator to obtain these privileges for your account.
+
+
 References
 ----------
 

docs/source/index.rst

 .. _doc-index:
 
-PEDASI
-======
+PEDASI v0.1.0
+=============
 
 .. toctree::
    :maxdepth: 2
@@ -37,16 +37,17 @@ Resources
 
 Documentation is available for the following stakeholders:
 
- - :ref:`Researchers and other end-users<guide_user>`: for users wishing to discover, explore, and make use of datasets using the web interface
- - :ref:`Administrators<guide_administrator>`: for those aiming to deploy PEDASI, or provide data or use applications through PEDASI
- - :ref:`Application developers<guide_developer>`: for developers wanting to create applications that access data available through PEDASI
+ - :doc:`Researchers and other end-users<guide_user>`: for users wishing to discover, explore, and make use of datasets using the web interface
+ - :doc:`Data or Application Providers<guide_provider>`: for those aiming to provide data or use applications through PEDASI
+ - :doc:`System Administrators<guide_administrator>`: for those aiming to deploy and manage PEDASI either for development or production
+ - :doc:`Application developers<guide_developer>`: for developers wanting to create applications that access data available through PEDASI
 
 This documentation is also available on `Read the Docs`_.
 
 .. _`Read the Docs`: https://pedasi.readthedocs.io/en/dev
 
 
-License
+Licence
 -------
 
 PEDASI is provided under the MIT licence.

docs/source/ref_applications_api.rst

+.. _ref_applications_api:
+
+Applications API Reference
+==========================
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Contents:
+
+
+.. note:: Please read the :doc:`Developer Guide<guide_developer>` first before reading this reference.
+
+
+Overview
+--------
+
+This document provides a schema reference to the PEDASI Applications API which is used by third-party applications to request data, metadata, or provenance records from a PEDASI instance and its data sources.
+
+
+Using the API
+-------------
+
+
+API Endpoints
+^^^^^^^^^^^^^
+
+
+GET /api/datasources/
+^^^^^^^^^^^^^^^^^^^^^
+
+Params:
+ TODO
+Retrieves the list of all data sources known to PEDASI, that the authenticated user has the ability to see. This will include some sources which they are unable to use, but have not had their details hidden.
+
+
+GET /api/datasources/<int>/
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Retrieves the PEDASI metadata for a given data source, if the authenticated user has the ability to see it.
+
+
+GET /api/datasources/<int>/metadata/
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Params:
+Any supported by data source API
+Retrieves metadata via an API query to a data source. The authenticated user must have permission to use the given data source.
+
+E.g. A HyperCat catalogue
+
+
+GET /api/datasources/<int>/metadata/<int>/
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+GET /api/datasources/<int>/metadata/<URI>/		(maybe)
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Retrieves metadata for a single dataset contained within the source via an API query to the data source. The authenticated user must have permission to use the given data source.
+
+E.g. An entry within a HyperCat catalogue
+
+
+GET /api/datasources/<int>/data/
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Params:
+Any supported by data source API
+In the case where a data source represents a single dataset, retrieve the dataset via an API query to the data source. The authenticated user must have permission to use the given data source.
+
+If the data source does not represent a single dataset, error.
+
+
+GET /api/datasources/<int>/data/<int>/
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+GET /api/datasources/<int>/data/<URI>/			(maybe)
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Params:
+In the case where a data source represents multiple datasets, retrieve a single dataset via an API query to the data source. The authenticated user must have permission to use the given data source.
+
+If the data source represents a single dataset, error.
+
+
+GET /api/datasources/<int>/prov/
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Params:
+TODO
+Retrieve all PROV records related to a single data source.
+
+
+GET /api/datasources/<int>/prov/<int>/
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Retrieve a single PROV record related to a the data source.
+
+
+References
+----------
+
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`

pedasi/settings.py

+# TODO describe all required / optional settings
 """
 Django settings for the PEDASI project.