Skip to content

List of API calls

Once you have set up and installed the BACE package, your APIs will now be available for access.

Provided API calls

The BACE package comes with standard BACE API calls upon installation.

Get your URL

Throughout this Manual, <your-URL> is the URL of your application, which can be found in a number of ways:

  1. After deploying your application, the URL is provided in the BaceApi output.

  2. Use AWS CLI (see Setup) on the command line:

    aws cloudformation describe-stacks --stack-name <stack-name> --region <region-name> --query "Stacks[].Outputs[?OutputKey=='BaceApi'].OutputValue" --output text

    Replace <stack-name> with the name of your application and the <region-name> with the region of your app (both previously set with sam deploy --guided and can be found in the created /samconfig.toml).

  3. Use the provided API notebook which will call the same command in 2. We recommend using the notebook to test query your application to debug when making changes and updates.

The URL you will obtain (<your-URL>) will start with https:// and end with .amazonaws.com/Prod/.

List of standard BACE API calls

There are a few basic calls that can be made to your application. The type of request is given in brackets, and the URL that is used to make the request is provided.

  • [POST] <your-URL>/create_profile
    • This call is used to create and store a profile for a new respondent. All inputs associated with the call will be stored as in the user's profile as a dictionary and uploaded to the database and a unique profile_id will be assigned. It then calculates the first optimal design. The call returns profile_id and the optimal design.
  • [POST] <your-URL>/update_profile
    • This call takes the user's answer to the most recent design and updates the posterior distribution over possible preference parameters based on a user's answer history. Information from the body of the HTTP request is stored in request_data as a dictionary to be accessed in /app/bace/user_convert.py but not stored in the database. It then computes and returns the next optimal design that can then be shown to a user.
  • [GET, POST] <your-URL>/estimates
    • [POST] This call takes the user's answer to the most recent design and updates the posterior distribution over possible preference parameters based on a user's answer history. It then computes and returns the mean and median posterior estimates for the individual. This call should be made when an individual will be asked no more questions and will provide the final estimates based on the model specified.
    • [GET] This call returns the posterior estimates for a specific profile_id.
  • [GET] <your-URL>/random_design
    • This call retrieves a random design that can be shown to a respondent. This is mainly for testing purposes.
  • [GET, POST] <your-URL>/survey
    • This URL will provide a direct implementation of BACE created by the application with a specified number of BACE questions (specified in /app/bace/user_survey.py).
  • [GET, POST] <your-URL>/surveyCTO
    • This URL will provides you with a route to integrate your survey with SurveyCTO.

Advanced use

To modify the existing API calls or add other API calls to your application, you will need to modify the following files among others:

  1. /template.yaml to update the SAM template with new API calls
  2. /app/app.py to view and update the code to execute the API calls

If you plan to make changes to the code for individual API calls, we highly recommend reviewing how to work with Flask.