First Time User Guide

An overview of interacting with a REST API

Contents

• Inputs to our REST API

• Run Through API Example

• Interacting with a REST API on Your Own

• (Optional) Full Request Steps: cURL

Inputs to our REST API

There are 3 types of input to our API.

• Headers

• URL Endpoint

• Data (or body)

URL Endpoint

The base URL is the starting point of the API you’re requesting from. The path specifies which model you are querying.

• Base URL for our API: https://api.corsali.com/predict

• Path for a specific model: {model_id}

• Full url endpoint: https://api.corsali.com/predict/{model_id}

Headers

Headers provide authentication information as well as information on what kind of data will be passed in. Our API requires 3 headers:

• Authorization: Carries credentials containing the authentication information for the model being queried
• Content-Type: Indicates the media type (text/html or text/JSON) of the request
• x-corsali-organization-id: Specifies the organization to ensure you have permission to access the requested model

Click on the link for each header type in order to understand the specifics about each header.

Data (or body)

The data contains the information that you will be sending to the API. The formatting of the input data will be different for different models. For formatting of the data:

• Look under "Your Models" to see a list of models associated with your organization

• Under each model is a "Request Input Data" page that explains the parameters and format of the input data

For most models the input format will be a JSON with a number of parameters passed in.

Run Through API Example

Now you are ready to go through the API Walkthrough.

Interacting with a REST API on Your Own

There are many different ways to interact with a REST API. The demo uses python code but we provide an example using cURL as well as python. Read through one or both of these examples to see how the inputs we defined above are passed into an API request. If you are feeling ambitious and want to run through a cURL request as well continue reading!

Full Request Steps: cURL

Open Terminal

user ~ % 

If you do not have an authentication key (or lost yours), follow this guide to generate one. Remember to save it to a secure location as it can only be viewed once

It is also useful (although not necessary) to save your organization id and model ids somewhere they are easily accessible

Under "Your Models" > "Example Model" > "Request Input Data" find the "Example Input". Copy and pasted into a file and save it in your current path.

user ~ % ls
example.json 

Go to this page and copy and paste the example command into your terminal. Note it refers to input data as example.json if you named your json something else you must change this.

• This command has already filled in for you the Content-Type, Organization Id and URL with the first model id associated with your account

• You will need to paste in your authentication key

user ~ % curl -H "Content-Type: application/json" \
-H "x-corsali-organization-id: Xxx...." \
-H "Authorization: Bearer eyJxxx.eyJxxx.1ANxxx" \
https://api.corsali.com/predict/Xxx....

Fill in your input data with the name of the file you created

user ~ % curl -H "Content-Type: application/json" \
-H "x-corsali-organization-id: Xxx...." \
-H "Authorization: Bearer eyJxxx.eyJxxx.1ANxxx" \
-d @example_json https://api.corsali.com/predict/Xxx....

Hit "enter" and send your first API Request!