This guide is for application developers wanting to understand how to set up a development environment for PEDASI and develop PEDASI applications.
Deploying PEDASI for Development
--------------------------------
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.
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.
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
^^^^^^^^^^^^^^^^^^^^^^^^^^^^
...
...
@@ -96,8 +32,12 @@ Firstly, you'll need to ensure that the data sources your application aims to us
- 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
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
...
...
@@ -114,13 +54,56 @@ If you now have these privileges and wish to add the application yourself, follo
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:
Then we should see something like the following (although without the formatting):
An `example`_ hosted on GitHub is a lightweight exemplar PEDASI web application that uses the PEDASI Applications API - see the GitHub repository README for more details.
.. 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 like this:
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.
