Skip to content

API

Jump to bottom
Scott Sievert edited this page Feb 17, 2017 · 1 revision

The NEXT API

Once you have a machine running with NEXT, then its functions are exposed through a web API, available on port 8000 of that machine. For example, if the machine running NEXT has IP 1.2.3.4, then a GET request to 1.2.3.4:8000/dashboard/experiment_list will return all the currently running experiments.

Here, we explain all the functions available in this API and how to call them. They are divided into four basic types:

  • /api/ is the root path of the NEXT REST API can be accessed, which is used for starting and interacting with experiments.

  • /dashboard/... is the root path for the dashboard API, by which you can access information about currently running experiments.

  • /query/... is the root path for the query page API, which is how you can access HTML pages that show you queries for the various currently running experiments.

  • /assistant/... is the root path for the assistant which provides easy access to documentation on how to call the various applications.

Some of the API endpoints require POST requests. The arguments for these (unless otherwise specified) should be given as JSON strings. Endpoints that require GET requests take their arguments (where applicable) as part of the URL. These arguments will always be denoted with angle brackets as part of the path, as in GET /api/experiment/<exp_uid>.

The REST API

  • POST /api/experiment: Initializes an experiment with the supplied parameters.

    Arguments:

    • app_id: The name of an application in NEXT (e.g. PoolBasedBinaryClassification)

    • args: The arguments for the specified application's initExp function. The particular application will specify the format of this argument.

  • POST /api/experiment/getQuery: Gets a query from a currently running experiment.

    Arguments:

    • exp_uid: The UID of the experiment for which you wish to get a query.

    • args: The arguments for the getQuery function of the application that is being used for the experiment. The application will specify the format of this argument.

  • POST /api/experiment/processAnswer: Returns an answer to a query that was asked as part of a currently running experiment.

    Arguments:

    • exp_uid: The UID of the experiment for which you are answering a query.

    • args: The arguments for the processAnswer function of the application that is being used for the experiment. The application will specify the format of this argument.

  • POST /api/experiment/getModel: Gets the current model generated from the already-answered queries in a particular experiment.

    Arguments:

    • exp_uid: The UID of the experiment for which you wish to get the model.

    • args: The arguments for the getModel function of the application that is being used for the experiment. The application will specify the format of this argument.

  • GET /api/experiment/<exp_uid>: Returns (in JSON format) the arguments with which the experiment whose UID is exp_uid was initialized.

  • GET /api/experiment/<exp_uid>/logs: Returns (in JSON format) all the logged data associated with the experiment whose UID is exp_uid.

  • GET /api/experiment/<exp_uid>/logs/<log_type>: Returns (in JSON format) all the logged data of type log_type associated with the experiment whose UID is exp_uid.

  • GET /api/experiment/<exp_uid>/participants: Returns (in JSON format) data about all the participants in the experiment with UID exp_uid.

  • GET /api/database/databasebackup: Download a zip file of the entire database for the instance of NEXT.

  • POST /api/database/databaserestore: This POST request requires a file upload, with the file named primary_file being a zip file. It will restore the entire database for the instance of NEXT to the state in the supplied zip file.

The dashboard API

  • GET /dashboard/experiment_list: Returns a webpage with the list of all currently running experiments.

  • GET /dashboard/get_stats:

  • GET /dashboard/system_monitor: Returns a webpage with links to monitoring information for the various systems NEXT uses interally (MongoDB, RabbitMQ, and Docker).

  • GET /dashboard/experiment_dashboard/<exp_uid>/<app_id>: Returns a webpage displaying stats about the experiment with UID exp_uid in graphical format, as defined by the application's dashboard code.

The query page API

  • GET /query/query_page/<page>/<exp_uid>: Returns a webpage which allows you to answer queries for the experiment with UID exp_uid. The page argument allows you to choose the wrapper HTML page around the queries that are being displayed (which, for example, may display the instructions in different ways). By default, NEXT supports two values for this argument:

    • query_page: A simple page with just the instructions and the query.

    • query_page_popup: A page without the instructions, but with a button to open a modal dialog displaying the instructions.

The assistant

  • GET /assistant/doc/<app_id>/<format>: Returns the documentation for what arguments are required by the five basic application functions, initExp, getQuery, processAnswer, getModel, and getStats. How this is displayed depends on the value of format:

    • pretty will cause this to return an HTML page with the documentation rendered in a human-readable way.

    • raw will cause this to return a JSON string that defines the interface.

Clone this wiki locally