Describe REST OAuth authentication.

administration.rst

@@ -1712,5 +1712,55 @@ scheme_fields) are displayed in a format suitable for copy and pasting.
    scheme_id   field type  primary_key description field_order url   isolate_display   main_display   query_field dropdown curator  datestamp
    1  ST integer  1     1  /cgi-bin/bigsdb/bigsdb.pl?page=profileInfo&db=pubmlst_neisseria_seqdef&scheme_id=1&profile_id=[?]  1  1  1  0  2  2010-01-20
    1  clonal_complex text  0     2     1  1  1  1  2  2009-11-16
+   
+.. _create_client_credentials:
 
-
+.. index::
+   pair: RESTful interface; client authorization
+
+*************************************************************************
+Authorizing third-party client software to access authenticated resources
+*************************************************************************
+If you are running the :ref:`RESTful API <restful_api>`, you will need to
+specifically authorize client software to connect to authenticated resources.
+This involves creating a client key and a client secret that is used to sign
+requests coming from the application.  The client key and secret should be 
+provided to the application developer.
+
+There is a script to do this in the scripts/maintenace directory of the 
+download archive.  The script is called create_client_credentials and should
+be run by the postgres user.  A full list of options can be found by typing: ::
+
+   create_client_credentials.pl --help
+   
+   NAME
+       create_client_credentials.pl - Generate and populate 
+       authentication database with third party application (API client) 
+       credentials.
+   
+   SYNOPSIS
+       create_client_credentials.pl --application NAME [options]
+   
+   OPTIONS
+   -a, --application NAME  
+       Name of application.
+       
+   -d, --deny
+       Set default permission to 'deny'.  Permissions for access to specific 
+       database configurations will have to be set.  If not included, the default
+       permission will allow access to all resources by the client.
+       
+   -h, --help
+       This help page.
+       
+   -i, --insert
+       Add credentials to authentication database.  This will fail if a matching
+       application version already exists (use --update in this case to overwrite
+       existing credentials).
+       
+   -u, --update
+       Update exisitng credentials in the authentication database.
+       
+   -v, --version VERSION  
+       Version of application (optional).
+    

conf.py

@@ -54,9 +54,9 @@
 # built documents.
 #
 # The short X.Y version.
-version = '1.10.2'
+version = '1.11.0'
 # The full version, including alpha/beta/rc tags.
-release = '1.10.2'
+release = '1.11.0'
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.

dbase_setup.rst

@@ -41,7 +41,7 @@ then ::
  createdb bigsdb_test_seqdef
  psql -f seqdef.sql bigsdb_test_seqdef
 
-Create an isolate database the same way:::
+Create an isolate database the same way: ::
  
  createdb bigsdb_test_isolates
  psql -f isolatedb.sql bigsdb_test_isolates

index.rst

@@ -24,6 +24,7 @@ The software has been released under the GNU General Public Licence version 3.
    data_query
    data_analysis
    data_export
+   rest
    faqs
    appendix
    database_schema

installation.rst

@@ -262,3 +262,131 @@ possibly to the contents of the Javascript directory, images directory and CSS
 files.  The version number is stored with the bigsdb.pl script, so this should
 also be updated so that BIGSdb correctly reports its version.  
 
+.. _restful_api:
+
+************************************
+Running the BIGSdb RESTful interface
+************************************
+BIGSdb has an Application Programming Interface (API) that allows third-party
+applications to access the data within the databases.  The script that runs
+this is called bigsrest.pl.  This is a Dancer2 application that can be run 
+using a wide range of options, e.g. as a stand-alone script, using Perl 
+webservers with plackup, or from apache.  Full documentation for 
+`deploying Dancer2 applications <https://metacpan.org/pod/Dancer::Deployment>`_
+can be found online.
+
+The script requires a new database that describes the resources to make
+available.  This is specified in the bigsdb.conf file as the value of the
+'rest_db' attribute.  By default, the database is named bigsdb_rest.
+
+A SQL file to create this database can be found in the sql directory of the
+download archive.  It is called rest.sql.  To create the database, as the
+postgres user, navigate to the sql directory and type ::
+
+  createdb bigsdb_rest
+  psql -f rest.sql bigsdb_rest
+ 
+This database will need to be populated using psql or any tool that can be used
+to edit PostgreSQL databases.  The database contains three tables that together
+describe and group the databases resources that will be made available through
+the API. The tables are:
+
+* resources
+   * this contains two fields (both compulsory):
+      * **dbase_config** - the name of the database configuration used with
+        the database.  This is the same as the name of the directory that 
+        contains the config.xml file in the /etc/bigsdb/dbases directory.
+      * **description** - short description of the database.
+
+* groups (used to group related resources together)
+   * this contains two fields (compulsory fields shown in bold):
+      * **name** - short name of group.  This is usually a single word and is also
+        the key that links resources to groups.
+      * **description** - short description of group.
+      * long_description - fuller description of group.
+
+* group_resources (used to add resources to groups)
+   * this contains two fields (both compulsory)
+      * **group_name** - name of group.  This must already exist in the groups
+        table.
+      * **dbase_config** - the name of database resource.  This must already
+        exist in the resources table.
+
+For example, to describe the PubMLST resources for Neisseria, connect to the
+bigsdb_rest database using psql, ::
+
+   psql bigsdb_rest
+   
+Then enter the following SQL commands.  First add the database resources: ::
+
+   INSERT INTO resources (dbase_config,description) VALUES
+   ('pubmlst_neisseria_seqdef','Neisseria sequence/profile definitions');
+   INSERT INTO resources (dbase_config,description) VALUES
+   ('pubmlst_neisseria_isolates','Neisseria isolates');
+   
+Then create a 'neisseria' group that will contain these resources: ::
+
+   INSERT INTO groups (name,description) VALUES 
+   ('neisseria','Neisseria spp.');
+   
+Finally, add the database resources to the group: ::
+
+   INSERT INTO group_resources (group_name,dbase_config) VALUES 
+   ('neisseria','pubmlst_neisseria_seqdef');
+   INSERT INTO group_resources (group_name,dbase_config) VALUES 
+   ('neisseria','pubmlst_neisseria_isolates');
+      
+The REST API will need to run on its own network port.  By default this is port 
+3000.  To run as a stand-alone script, from the script directory, as the bigsdb 
+user, simply type: ::
+
+   ./bigsrest.pl
+   
+This will start the API on port 3000.  You will be able to check 
+that this is running using a web browser by navigating to http://localhost:3000
+on the local machine, or using the server IP address from a remote machine.
+You may need to modify your server firewall rules to allow connection to this
+port.
+
+Running as a stand-alone script is useful for testing, but you can achieve much
+better performance using a Perl webserver with plackup.  There are various
+options to choose.  PubMLST uses 
+`Starman <http://search.cpan.org/dist/Starman/>`_.
+
+To run the API using Starman, type the following as the bigsdb user: ::
+
+   plackup -a /var/rest/bigsrest.pl -s Starman -E deployment
+   
+where the value of -a refers to the location of the bigsrest.pl script.  
+Starman defaults to using port 5000.  
+
+Proxying the API to use a standard web port
+===========================================
+Usually you will want your API to be available on the standard web port 80.
+To do this you will need to set up a virtual host using a different domain
+name from your web site to proxy the API port.  For example, PubMLST has a
+separate domain 'http://rest.pubmlst.org' for its API.  This is set up as a
+virtual host directive in apache with the following configuration file: ::
+
+   <VirtualHost *>
+     ServerName rest.pubmlst.org
+     DocumentRoot /var/rest
+     ServerAdmin keith.jolley@zoo.ox.ac.uk
+      <Directory /var/rest>
+       AllowOverride None
+       Require all granted
+     </Directory>
+   
+     ProxyPass / http://rest.pubmlst.org:5000/
+     ProxyPassReverse / http://rest.pubmlst.org:5000/
+   
+     <Proxy *>
+         Order allow,deny
+         Allow from all
+     </Proxy>
+   
+     ErrorLog  /var/log/apache2/rest.pubmlst.org-error.log
+     CustomLog /var/log/apache2/rest.pubmlst.org-access.log common
+   
+   </VirtualHost>
+