API Endpoints

The API endpoints facilitate interactions between the Aidbox Forms application and the Aidbox server

The following API endpoints are utilized by the Aidbox Forms application to interact with Aidbox. These endpoints are activated by specific actions within the application, such as saving a questionnaire, generating a questionnaire response, or assembling a questionnaire. Each endpoint has a descriptive name reflecting the action it performs and the timing of its execution.

assemble-questionnaire

Triggered after saving the current questionnaire, if it includes sub-questionnaires, to assemble the full questionnaire.

Request

POST /fhir/Questionnaire/$assemble HTTP/1.1 
Content-Type: application/json

{
    "resourceType": "Parameters",
    "parameter": [{
        "name": "questionnaire",
        "resource": <questionnaire>
    }]
}

Where <questionnaire> is the questionnaire being assembled.

Response

<questionnaire>

Where <questionnaire> is the assembled questionnaire.

assemble-sub-questionnaire-usages

Triggered after saving a sub-questionnaire to update all parent questionnaires that include it.

Request

POST /Questionnaire/$assemble-all HTTP/1.1 
Content-Type: application/json

{
    "questionnaires": [
        {
            "id": <questionnaire-1-id>,
            "resourceType": "Questionnaire"
        },
        {
            "id": <questionnaire-2-id>,
            "resourceType": "Questionnaire"
        },
        ...
    ]
}

Where <questionnaire-1-id>, <questionnaire-2-id>, etc., are the IDs of the parent questionnaires that include the sub-questionnaire.

Response

[
  <questionnaire-1>, 
  <questionnaire-2>, 
  ...
]

Where <questionnaire-1>, <questionnaire-2>, etc., are the updated questionnaires.

check-sub-questionnaire-usage

Triggered after saving a sub-questionnaire to verify if it is currently used in any parent questionnaires.

Request

GET /Questionnaire/<sub-questionnaire-id>/$usage HTTP/1.1 

Where <sub-questionnaire-id> is the ID of the sub-questionnaire.

Response

{
    "questionnaires": [
        {
            "id": <questionnaire-1-id>,
            "resourceType": "Questionnaire"
        },
        {
            "id": <questionnaire-2-id>,
            "resourceType": "Questionnaire"
        },
        ...
    ]
}

Where <questionnaire-1-id>, <questionnaire-2-id>, etc., are the IDs of the parent questionnaires that include the sub-questionnaire.

delete-assembled-questionnaire

Triggered after saving the current questionnaire, when the saved questionnaire no longer references sub-questionnaires.

Request

DELETE /sdc/Questionnaire?url=<questionnaire-url>&version=<questionnaire-version>-assembled HTTP/1.1

Where <questionnaire-url> is the canonical URL and <questionnaire-version> is the version of the questionnaire being deleted.

Response

<questionnaire>

Where <questionnaire> is the questionnaire that was deleted.

delete-attachment

Triggered when the attachment input field is cleared.

Request

DELETE /$sdc-file/<filepath> HTTP/1.1

Where <filepath> is the path of the attachment being deleted.

Response

Response shape is specific to the storage type and is not processed by the frontend.

extract

Triggered when the "Extract" button in the debug panel is clicked.

Request

POST /fhir/QuestionnaireResponse/$extract HTTP/1.1
Content-Type: application/json

{
    "resourceType": "Parameters",
    "parameter": [{
        "name": "questionnaireResponse",
        "resource": <questionnaire-response>
    }, {
        "name": "questionnaire",
        "resource": <questionnaire>
    }]
}

Where <questionnaire-response> is the questionnaire response being extracted and <questionnaire> is the questionnaire it is based on.

Response

<bundle>

Where <bundle> is the bundle of resources extracted from the questionnaire response.

get-assembled-questionnaire

Triggered after retrieving the current questionnaire to obtain its fully assembled version, if it includes sub-questionnaires.

Request

GET /sdc/Questionnaire?url=<questionnaire-url>&version=<questionnaire-version>-assembled HTTP/1.1

Where <questionnaire-url> represents the canonical URL, and <questionnaire-version> specifies the version of the assembled questionnaire being requested.

Response

<bundle>

Where <bundle> is the bundle containing zero or one questionnaire resource.

get-config

Triggered during the initialization of the builder or renderer to fetch configuration details.

Request

POST /$sdc-config HTTP/1.1
Content-Type: application/json

{
    "resourceType": "Parameters",
    "parameter": [{
        "name": "id",
        "valueString": "<config-id>"
    }]
}

Where <config-id> refers to the ID of the SDCConfig resource included in the JWT token payload of the current authentication session. This parameter is omitted if no configuration is specified.

Response

<config>

Where <config> is the SDCConfig resource containing the configuration details.

get-questionnaire

Triggered during the initialization of the builder or renderer to fetch the current questionnaire.

Request

GET /sdc/Questionnaire/<questionnaire-id> HTTP/1.1

Where <questionnaire-id> is the ID of the questionnaire being requested.

Response

<questionnaire>

Where <questionnaire> is the questionnaire being requested.

get-questionnaire-response

Triggered during the initialization of the renderer to fetch the current user response.

Request

GET /sdc/QuestionnaireResponse/<questionnaire-response-id> HTTP/1.1

Where <questionnaire-response-id> is the ID of the questionnaire response being requested.

Response

<questionnaire-response>

Where <questionnaire-response> is the questionnaire response being requested.

get-fhir-metadata

Triggered during the initialization of the builder to fetch metadata for FHIR resources, which aids in autocompletion.

Request

GET /fhir/metadata HTTP/1.1

Response

<fhir-metadata>

Where <fhir-metadata> is the metadata for the FHIR server.

get-fhir-schemas

Triggered during the initialization of the builder to fetch schemas for FHIR resource elements, aiding in autocompletion.

Request

GET /static/fhir_schemas.json HTTP/1.1

Response

<fhir-schemas>

Where <fhir-schemas> is the JSON object containing the schemas for the FHIR resource elements.

get-questionnaire-by-id

Triggered before saving the current questionnaire to check for conflicts with existing questionnaires.

Request

GET /sdc/Questionnaire/<questionnaire-id> HTTP/1.1

Where <questionnaire-id> is the ID of the questionnaire being checked.

Response

<questionnaire>

Where <questionnaire> is the questionnaire being checked.

get-theme

Triggered during the initialization of the web component if a theme is referenced in the configuration.

Request

GET /QuestionnaireTheme/<theme-id> HTTP/1.1

Where <theme-id> is the ID of the theme being requested.

Response

<theme>

Where <theme> is the theme being requested.

get-themes

Triggered during the initialization of the builder web component and after saving a theme to list available themes in the theme selector.

Request

GET /QuestionnaireTheme?_sort=.theme-name HTTP/1.1

Response

<bundle>

Where <bundle> is the bundle of themes.

import-questionnaire

Triggered when the "Import" button is clicked in the questionnaire importer.

Request

POST /sdc/Questionnaire HTTP/1.1
Content-Type: application/json

<questionnaire>

Where <questionnaire> is the questionnaire being imported.

Response

<questionnaire>

Where <questionnaire> is the questionnaire that was imported.

populate

Triggered when the "Populate" button is clicked in the debug panel.

Request

POST /fhir/Questionnaire/$populate HTTP/1.1
Content-Type: application/json

{
    "resourceType": "Parameters",
    "parameter": [{
        "name": "questionnaire",
        "resource": <questionnaire>
    }, {
        "name": "subject",
        "valueReference": <patient-id>
    }, {
        "name": "local",
        "valueBoolean": true
    }, {
        "name": "context",
        "part": [{
            "name": "name",
            "valueString": "encounter"
        }, {
            "name": "content",
            "valueReference": <encounter-id>
        }, {
            "name": "name",
            "valueString": "author"
        }, {
            "name": "content",
            "valueReference": <patient-id>
        }]
    }]
}

Where <questionnaire> is the questionnaire being populated, <patient-id> is the ID of the patient, and <encounter-id> is the ID of the encounter selected in the debug panel. (todo: add explanation)

Response

<parameters>

Where <parameters> is the parameters resource containing the populated questionnaire response under the response name.

process-response

Triggered when the user submits a response or when auto-save of the response is activated.

Request

POST /fhir/Questionnaire/$process-response HTTP/1.1
Content-Type: appliation/json

{
    "resourceType": "Parameters",
    "parameter": [{
        "name": "questionnaireResponse",
        "resource": <questionnaire-response>
    }, {
        "name": "extract",
        "valueBoolean": true
    }]
}

Where <questionnaire-response> is the response being processed. If the questionnaire response has a status of in-progress, the extract parameter is omitted.

Response

<parameters>

Where <parameters> is the parameters resource containing the processed questionnaire response under the response name.

repopulate

Triggered when the "Repopulate" button is clicked by the user.

Request

POST /fhir/Questionnaire/$populate HTTP/1.1
Content-Type: application/json

{
    "resourceType": "Parameters",
    "parameter": [{
        "name": "questionnaire",
        "resource": <questionnaire>
    }, {
        "name": "response",
        "resource": <questionnaire-response>
    }, {
        "name": "subject",
        "valueReference": <patient-id>
    }, {
        "name": "local",
        "valueBoolean": true
    }, {
        "name": "context",
        "part": [{
            "name": "name",
            "valueString": "encounter"
        }, {
            "name": "content",
            "valueReference": <encounter-id>
        }]
    }]
}

Where <questionnaire>, <questionnaire-response>, <patient-id>, and <encounter-id> are as described in the populate request.

Response

<parameters>

Where <parameters> is the parameters resource containing the repopulated questionnaire response under the response name.

save-assembled-questionnaire

Triggered after saving the current questionnaire, if it includes sub-questionnaires, to save the assembled version.

Request

PUT /sdc/Questionnaire?url=<questionnaire-url>&version=<questionnaire-version>-assembled HTTP/1.1
Content-Type: application/json

<assembled-questionnaire>

Where <questionnaire-url> and <questionnaire-version> are as described in the get-assembled-questionnaire request, and <assembled-questionnaire> is the assembled questionnaire being saved.

Response

<questionnaire>

Where <questionnaire> is the questionnaire that was saved.

validated-extracted-bundle

Triggered upon completion of an extract operation initiated by the "Extract" button in the debug panel.

Request

POST / HTTP/1.1
Content-Type: application/json

<bundle>

Where <bundle> is the bundle containing resources obtained from extract.

Response

<bundle>

Where <bundle> is the bundle of saved resources.

create-questionnaire

Triggered when the "Save" button is clicked in the builder for a new questionnaire.

Request

POST /sdc/Questionnaire HTTP/1.1
Content-Type: application/json

<questionnaire>

Where <questionnaire> is the new questionnaire being created.

Response

<questionnaire>

Where <questionnaire> is the questionnaire that was created.

save-questionnaire

Triggered when the "Save" button is clicked in the builder.

Request

PUT /sdc/Questionnaire/<questionnaire-id> HTTP/1.1
Content-Type: application/json

<questionnaire>

Where <questionnaire> is the questionnaire being saved.

Response

<questionnaire>

Where <questionnaire> is the questionnaire that was saved.

create-sub-questionnaire

Triggered when an outline item is saved as a sub-questionnaire.

Request

POST /sdc/Questionnaire?url=<sub-questionnaire-url>&version=1 HTTP/1.1
Content-Type: application/json

<sub-questionnaire>

Where <sub-questionnaire-url> is the canonical URL of the sub-questionnaire and <sub-questionnaire> is the sub-questionnaire being saved.

Response

<sub-questionnaire>

Where <sub-questionnaire> is the questionnaire that was created.

create-theme

Triggered when the "Save" button is clicked in the theme editor for a new theme.

Request

POST /QuestionnaireTheme HTTP/1.1
Content-Type: application/json

<theme>

Where <theme> is the new theme being created.

Response

<theme>

Where <theme> is the theme being created.

save-theme

Triggered when the "Save" button is clicked in the theme editor.

Request

PUT /QuestionnaireTheme/<theme-id> HTTP/1.1
Content-Type: application/json

<theme>

Where <theme> is the theme being saved.

Response

<theme>

Where <theme> is the theme being saved.

search-choice-options

Triggered when dropdown options are requested for a choice item.

Request

GET <url> HTTP/1.1

Where <url> is the URL of the value set or resources associated with the choice item.

Response

Response be a plain list or bundle of resources (e.g. ValueSet) depending on the source of the options.

search-questionnaires-by-url

Triggered before saving the current questionnaire to check for conflicts with existing questionnaires based on their URL.

Request

GET /sdc/Questionnaire?url=<questionnaire-url> HTTP/1.1

Where <questionnaire-url> is the canonical URL of the questionnaire being checked.

Response

<bundle>

Where <bundle> is the bundle of questionnaires with the same URL.

search-sub-questionnaires

Triggered when the user searches for sub-questionnaires in the builder.

Request

GET /sdc/Questionnaire?.extension$contains=%-child&.title$contains=<search-term> HTTP/1.1

Where <search-term> is the term being searched for.

Response

<bundle>

Where <bundle> is the bundle of sub-questionnaires.

get-sub-questionnaire

Triggered to retrieve a sub-questionnaire when it is referenced in a parent questionnaire.

Request

GET /sdc/Questionnaire?url=<sub-questionnaire-url>&version=<sub-questionnaire-version> HTTP/1.1

Where <sub-questionnaire-url> is the canonical URL of the sub-questionnaire being requested. Parameter version is omitted if no version is specified in the reference.

Response

<bundle>

Where <bundle> is the bundle containing zero or one questionnaire resource.

upload-attachment

Triggered when a file is selected in the attachment input field.

Request

POST /$sdc-file HTTP/1.1 
Content-Type: multipart/form-data; boundary=------------------------boundary12345

--------------------------boundary12345
Content-Disposition: form-data; name="file"; filename="example.txt"
Content-Type: text/plain

<file-content>
--------------------------boundary12345
Content-Disposition: form-data; name="filename"

<file-name>
--------------------------boundary12345--

Where <file-content> is the content of the file being uploaded and <file-name> is the path and name of the file.

Response

{
  "url": "<file-url>"
}

Where <file-url> is the URL of the uploaded file which will further be used to either download or delete the file.

validate-questionnaire

Triggered when the "Validate Questionnaire" button is clicked in the debug panel.

Request

POST /Questionnaire/$validate HTTP/1.1
Content-Type: application/json

<questionnaire>

Where <questionnaire> is the questionnaire being validated.

Response

<operation-outcome>

Where <operation-outcome> is the operation outcome of the validation.

validate-response

Triggered when the "Validate Questionnaire Response" button is clicked in the debug panel.

Request

POST /QuestionnaireResponse/$validate HTTP/1.1
Content-Type: application/json

<questionnaire-response>

Where <questionnaire-response> is the response being validated.

Response

<operation-outcome>

Where <operation-outcome> is the operation outcome of the validation.