API

For a rundown of API endpoints, see this page

Purpose

The purpose of the API is to provide an interface between the database and the outside world in a controlled fashion.

Deploying on Apache

Requires Python 3.7 or above

1. Run sudo apt-get install libapache2-mod-wsgi python-dev

2. Create a directory in /var/www for the API, and name it something like nexusapi

3. Put api.py and auth.csv in that folder, and add API keys to that file.

4. Create a file called api.wsgi and put the following into it

   import sys
   sys.path.insert(0, '/var/www/yourdir')
   
   from api import app as application

5. Add the following to your Apache config

   WSGIDaemonProcess api user=www-data group=www-data threads=5
   WSGIScriptAlias "/api" "/var/www/yourdir/api.wsgi"
   <Directory /var/www/yourdir>
       WSGIProcessGroup progpilot
       WSGIApplicationGroup %{GLOBAL}
       Require all granted
   </Directory>
   

6. Restart Apache, and your API should be present at http://www.example.com/api

   1. If you'd like to have the API accessible from another path, change WSGIScriptAlias "/api" to WSGIScriptAlias "/yourpath", meaning you should be able to access the API from http://www.example.com/yourpath

Script rundown

The main API has its own error logging in combination with what Apache will log for you. Any failures or breakages will be logged in a file in the same directory as api.py (herein referred to as the script) called error.log.

There are numerous helper functions in the script with are used in a lot of functions used for requests. Each of these has a fairly self explanatory name, or is fairly explanatory. There are a couple of notable functions:

• error_frame

  • error_frame will generate JSON for a response based on an error message and a HTTP code. The format returned is an instance of app.response_class from Flask, and that can be returned from a request function with the right MIME types and a couple of other bits and pieces.

• success_frame

  • success_frame will do the same as error_frame, with the exception that it's for successes. If you There is an option for returning a dictionary or list as part of the response JSON, which can be passed to the function through content.

• all the check_x functions

  • These functions are used for input validation in request functions. They will return true if the validation is successful, and the relevant error if they fail. As a result they should be used as follows:

    # check integers are valid
    ci = check_integer(["file_id", "size_kb", "uploaded_time"], inputs)
    if ci is not True:
        return ci

    The first argument should be a list of fields that should match the conditions set out in the function, and the second argument is a dictionary of all POST arguments that have been sent, generated with the organise_inputs function which deals with raw POST data. The exception to this rule is check_required, which should be passed the raw POST data specifically.