Make an API Call (HTTP)
Important
Make sure you have gotten your API keys and configured your environment before trying to submit an API request.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","identify-phi","redact-phi"]}
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. Your API keys will be pulled from your variables.
Important
If calling thestructure
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 that is in progress.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 JSON Schema: 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."
}
Feedback
Was this page helpful?
Great! If you ever have questions or want to provide feedback, send us an email.
Bummer. We hate when we miss the mark. If you have suggestions for improvements or other general comments, send us an email.