Using the RESTful API

RESTful API

The Emcien JSON RESTful API uses authorized web requests to create or fetch data from the application.

  • A Swagger (https://swagger.io/) user interface describing the API endpoints and more additional API-specific documentation can be found here:

  • The API documentation/landing page groups all endpoints according to their type, and is followed by example-driven documentation on how to use the additional features of the API (such as sorting, paging, filtering, etc.).

  • The available request endpoints are designed to help limit the number of requests necessary to retrieve related data. Often this is done by “including” data with the same request to fire off an additional query that is represented in a single response. Please consider application and server load when running a large number of requests.

 

RESTful API > Making Requests

Making requests to the API is done through standard HTTP methods. The Emcien RESTful API follows traditional guidelines, using GET to request data, POST to submit data, etc. There are plenty of options available to query data from a RESTful API, but a few are outlined below using the example of finding all Reports:

  1. Use the API UI

  2. Navigate to the API UI (LINK “RESTful API”)

  3. Find Reports in the list of available endpoint types

  1. Click Reports or Show/Hide to show the available Report endpoints

  1. Expand /reports to show information about this particular endpoint

  1. Select “Try it out!” to query the server

       

2. By logging in to the application, a browser session is created.  This session allows the user to query the API in the same browser as long as the session is valid.

  1. Login to the application with a user who is set up with an API Authentication token (LINK: “Authentication”)

  2. Navigate to https://example.com/api/v1/reports in the same browser, but in a different tab (use your actual server name).

    • This will display a JSON response of Reports.  Note that an authorization token was not required because the logged in user’s session was used to authenticate the request.

3. Use curl or another command line tool

  • Curl is a command line tool used to transfer data. Using method (1) above, an example curl request is automatically generated in the UI.

    • Ex: “curl -X GET --header 'Accept: application/json' --header …”

 

4. Use an external application such as Postman (https://www.getpostman.com/) or Paw (https://paw.cloud/).

  • Making POST requests is often simplified in applications like these.

5. Request data through the programming language of your choice, most likely as part of a factory (LINK: “Automated Prediction Factory”).

 

RESTful API > Authentication

API Authorization Tokens are required for any user to interact with the API. Users who have authenticated via the browser may also use the session cookie to access the API within that same browser session (such as another tab).

  • Generating the Token

    • API Authorization Tokens are user-specific and can be generated through the UI by an Admin. Generating a token for a user grants them full API access.

    • NOTE: Providing an API Token to a user grants them the ability to create, destroy, and request data at a very high rate. Admins should carefully consider who they grant API access to so that application and system resources are properly respected. Please secure and protect tokens accordingly.

    • Although API Tokens do not expire, it is recommended that you regenerate tokens regularly.

 
  • Navigate to the Admin menu

  • Select the user for whom you want to generate an API Token

  • Generate the token by selecting “Generate”

  • Save the generated token by selecting “Update User”

  • Using the Token

    • All requests made to the API must include an Authorization header. Requests made via the accompanying API user interface will automatically include the header with all requests.

 

RESTful API > Creating Rules and Predictions

The following examples will be shown using the “curl” command, though most any technique in (LINK: “Making Requests”) will behave similarly.

  1. Creating Rules

    1. Rules are one element of a Report.  So we’ll be sending a POST request to the /reports endpoint.

    2. The /reports endpoint accepts a JSON body with all of the Report parameters. These parameters are documented in the API user interface. For our example, we’ll use the following JSON:

{

 "delimiter": "comma",

 "encoding": "UTF-8",

 "file_format": "wide",

 "max_cluster_size": 7,

 "name": "Diabetes Report",

 "original_file_name": "Diabetes.wide.csv",

 "outcome": "Diabetes",

 "pattern_threshold": 3,

 "projects": [

   1

 ]

}

  1. Note that the file “Diabetes.wide.csv” exists on our SFTP server (LINK: “SFTP Import”), the file is “wide” (LINK: “Wide”), encoded in “UTF-8” (LINK: “Encoding”), and the outcome is set to “Diabetes” so that we may predict using this Report in Step 2.

  2. The request endpoint will be similar to http://example.com/api/v1/reports

  3. The resulting curl command will be similar to:

curl -X POST --header 'Content-Type: application/json' --header 'Accept: application/json' --header 'Authorization: tq0gkffdqgzasxqa2tx7mf12' -d '{  "delimiter": "comma",  "encoding": "UTF-8",  "file_format": "wide",  "max_cluster_size": 7,  "name": "Diabetes Report",  "original_file_name": "Diabetes.wide.csv",  "outcome": "Diabetes",  "pattern_threshold": 3,  "period_scale": "flexible",  "projects": [1]}' 'http://example.com/api/v1/reports'

  1. A successful POST request to this endpoint will queue a new Analysis, returning a 202 Accepted response.  The response will have an id that can be used to track the state of the Report as it runs, as well as access various Report elements.

  2. Once a Report has been generated, we can now view our Rules by using the Rules endpoint for a Report.  Again, we’ll use curl:

curl -X GET --header 'Accept: application/json' --header 'Authorization: tq0gaba2caaysxqa2tf7m3a2' 'http://example.com/api/v1/reports/81296106/rules?page=1&size=15'

  1. Notice that the request endpoint is now /api/v1/reports/{id}/rules which will return all Rules for the Report generated in step 1.2

  2. Creating Predictions (Batch)

    1. Batch Predictions are useful when you have a collection of records you would like to test on. Test/Prediction files can either contain an entry for the outcome (in our case, “Diabetes”), or not. The former will make a prediction and compare it with the actual outcome specified in the file, whereas the latter will make a new prediction against data without the ability to check it’s accuracy.

    2. Create a new set of predictions using the using the Report created in 1.2 (id 81296106) by submitting a POST request to /predict/shards. For our example, we’ll use the following JSON:

{
   "delimiter": "comma",
       "encoding": "UTF-8",
   "filename": "Diabetes-test.wide.csv",
   "format": "wide",
   "name": "My Diabetes Predictions",
   "projects": [
         1
     ],
   "rules_report_id": 81296106
}

  1. Note that the file “Diabetes-test.wide.csv” exists on our SFTP server (LINK: “SFTP Import”), the file is “wide” (LINK: “Wide”), encoded in “UTF-8” (LINK: “Encoding”), and the rules_report_id is set to the Report ID created in step 1.2.

  2. The request endpoint will be similar to  http://example.com/api/v1/predict/shards

  3. The resulting curl command will be similar to:

curl -X POST --header 'Content-Type: application/json' --header 'Accept: application/json' --header 'Authorization: af0fa70af0hbrn1n1' -d '{  "delimiter": "comma",  "encoding": "UTF-8",  "filename": "Diabetes.wide.csv",  "format": "wide",  "name": "My Diabetes Predictions",  "projects": [1],  "rules_report_id": 81296106}' 'http://example.com/api/v1/predict/shards'

  1. A successful POST request to this endpoint will queue a new Prediction, returning a 202 Accepted response.  The response will have an id that can be used to track the state of the Prediction as it runs, as well as access various Prediction Shard elements.

  2. Predictions (Real-time)

    1. Real-time predictions are useful for getting a quick prediction on a single record with an unknown outcome.

    2. Create a new real-time prediction using the using the Report created in step 1.2 (id 81296106) by submitting a POST request to /real_time_predictions. For our example, we’ll use the following JSON:

{
   "report_id": 81296106,
   "entries": [
       {
           "item_name": "21",
           "category_name": "Age (years)"
         },
         {
           "item_name": "144",
           "category_name": "Plasma glucose concentration"
         }
       ]
}

  1. Note that we are using the Report created in step 1.2. The entries array reflects the elements of our new record - a 21 year old person with a Plasma glucose concentration of 144.  Given only that information, Emcien Patterns will make a prediction on whether or not this person has Diabetes.

  2. The request endpoint will be similar to http://example.com/api/v1/real_time_predictions

  3. The resulting curl command will be similar to:

curl -X POST --header 'Content-Type: application/json' --header 'Accept: application/json' --header 'Authorization: 3a4jklfl24jlh1nln5lj2j' -d '{  "report_id": 81296106,  "entries": [    {      "item_name": "21",      "category_name": "Age (years)"    },    {      "item_name": "144",      "category_name": "Plasma glucose concentration"    }  ]}' 'http://example.com/api/v1/real_time_predictions'

  1. A successful request to this endpoint will return a 200 OK response, and contain the prediction along with the reasons that the person did or did not have diabetes.