Make an API Call (HTTP)

Let's make an API call in your preferred programming language. Python users may wish to use the Python SDK.

πŸ“˜

You can make an API call in any language you wish.

Make sure you gotten your API keys and configured your environment before trying to call the API.

Step 1: Get Models Request (Optional)

ScienceIO offers a number of models (these are also our endpoints) that can be called when you query the API. To get a list of available endpoints, use the following query:

curl https://api.aws.science.io/v2/models

The result looks like this:

{"models":["structure","structure-ontologies","identify-phi","redact-phi"]}

❗️

Note that structure-ontologies is currently a beta endpoint released in January 2023. We cannot guarantee backward compatibility for any beta endpoint; API signatures and response schemas are subject to change in upcoming releases.

Step 2: Configure Environment Variables

You must configure environment variables to hold your API keys. Remember that environment variables are used per session and must be reconfigured for each new session. To avoid this, consider adding these variables to your ~/.bashrc or ~/.zshrc depending on your shell.

export SCIENCEIO_KEY_ID={YOUR_API_KEY_ID}
export SCIENCEIO_KEY_SECRET={YOUR_API_SECRET_KEY}

It should look like this:

export SCIENCEIO_KEY_ID=ABCDEFGHIJK123456789
export SCIENCEIO_KEY_SECRET=2a384c12-df4c-4ee4-a14c-7762e8e9dcf3

Step 3: Submit the Inference Request (POST)

Create an inference request using POST with the endpoint of your choosing. Do this by updating the curl URL to the desired endpoint; in this example, we are posting to the structure endpoint. Note: Your API keys will be pulled from your variables.

πŸ“˜

  • If calling the structure or structure-ontologies endpoints, leave the keyword as text
  • If calling the identify-phi or redact-phi endpoints, change the keyword to query_text

The change to input_text is part of a larger standardization of underlying schemas. It will be rolled out to other endpoints in future releases.

curl https://api.aws.science.io/v2/structure \
  --request POST \
  --header "Content-type: application/json" \
  --header "x-api-id: $SCIENCEIO_KEY_ID" \
  --header "x-api-secret: $SCIENCEIO_KEY_SECRET" \
  --data '{ "text": "ALS is often called Lou Gehrigs disease, after the baseball player who was diagnosed with it. Doctors usually do not know why ALS occurs."}'

An initial JSON response will be returned to you. Note the request_id (which you will need for Step 4) and the inference status:

{
  "request_id": "12345ab6-c78d-9101-e11f-213141ghijkl",
  "text": "ALS is often called Lou Gehrigs disease, after the baseball player who was diagnosed with it. Doctors usually do not know why ALS occurs.",
  "model_type": "structure",
  "inference_status": "SUBMITTED",
  "message": "Created a new inference request for Structure."
}

Step 4: Retrieve the API Response (GET)

Retrieve the completed JSON response using GET. Use the request_id from the initial response (Step 3) to complete the URL in the first line of code:

curl https://api.aws.science.io/v2/structure/<REQUEST_ID> \
  --request GET \
  --header "x-api-id: $SCIENCEIO_KEY_ID" \
  --header "x-api-secret: $SCIENCEIO_KEY_SECRET"

It should look like this:

curl https://api.aws.science.io/v2/structure/12345ab6-c78d-9101-e11f-213141ghijkl \
  --request GET \
  --header "x-api-id: $SCIENCEIO_KEY_ID" \
  --header "x-api-secret: $SCIENCEIO_KEY_SECRET"

Note that the JSON response includes a new inference status of COMPLETED and an array of dictionaries. For more information about each key:value pair, see Structure.

{
  "request_id": "12345ab6-c78d-9101-e11f-213141ghijkl",
  "inference_result": {
    "text": "ALS is often called Lou Gehrigs disease, after the baseball player who was diagnosed with it. Doctors usually do not know why ALS occurs.",
    "spans": [
      {
        "concept_id": "UMLS:C0002736",
        "concept_name": "Amyotrophic Lateral Sclerosis",
        "concept_type": "Medical Conditions",
        "pos_end": 3,
        "pos_start": 0,
        "score_id": 0.9996367692947388,
        "score_type": 0.9998749494552612,
        "text": "ALS"
      },
      {
        "concept_id": "UMLS:C0012634",
        "concept_name": "Disease",
        "concept_type": "Medical Conditions",
        "pos_end": 40,
        "pos_start": 33,
        "score_id": 0.99982750415802,
        "score_type": 0.9999518394470215,
        "text": "disease"
      },
      {
        "concept_id": "UMLS:C0004795",
        "concept_name": "Baseball Game",
        "concept_type": "Context",
        "pos_end": 60,
        "pos_start": 52,
        "score_id": 0.9998605251312256,
        "score_type": 0.9998250603675842,
        "text": "baseball"
      },
      {
        "concept_id": "UMLS:C0031831",
        "concept_name": "Physicians",
        "concept_type": "Context",
        "pos_end": 102,
        "pos_start": 95,
        "score_id": 0.9998593330383301,
        "score_type": 0.9999227523803711,
        "text": "Doctors"
      },
      {
        "concept_id": "UMLS:C0002736",
        "concept_name": "Amyotrophic Lateral Sclerosis",
        "concept_type": "Medical Conditions",
        "pos_end": 130,
        "pos_start": 127,
        "score_id": 0.9995817542076111,
        "score_type": 0.9998552799224854,
        "text": "ALS"
      }
    ]
  },
  "model_type": "structure",
  "inference_status": "COMPLETED",
  "message": "Your inference results are ready."
}