API Specification

Introduction

AIM - API gives you access to information in a format suitable for processing in particular in JSON format.

Services are split into five entities:

  • Substances - /api/substances
  • References - /api/references
  • Substance reference relations - /api/substance-reference-relations
  • Clinical trials - /api/clinical-trials
  • Clinical trials substances relations - /api/clinical-tirals-substances

Method of providing data

  • All dates are text strings formatted in compliance with ISO 8601 as YYYY-MM-DD
  • If the syntax request is incorrect (missing or incorrectly formatted parameters) an HTTP 400 Bad Request response will be returned. The body of the response may include an explanation.
  • Data updated_at (used for querying changed-from) refers only to a particular entity and not its logical relations. Example: If a new substance reference relation is added, but the substance detail has not changed, this is reflected in the substance reference relation endpoint where a new entity with id and current dates in created_at and updated_at fields will be added, but in substances or references endpoint nothing has changed.

The recommended way of sequential download

  • During the first download, it is possible to obtain all data by entering an old enough date in the parameter value changed-from, for example: changed-from=2020-01-01 It is important to write down the date on which the receiving the data was initiated let’s say 2020-10-20
  • For repeated data downloads, it is sufficient to receive only the records in which something has changed. It can therefore be requested with the parameter changed-from=2020-10-20 (example from the previous bullet). Again, it is important to write down the date when the updates were downloaded (eg. 2020-10-20). This date will be used in the next update (refresh) of the data.

Services for entities

List of endpoint URLs:

Format of the request

All endpoints have these parameters in common:

  • changed-from - a parameter to return only the entities that have been modified on a given date or later.
  • continue-after-id - a parameter to return only the entities that have a larger ID than specified in the parameter.
  • limit - a parameter to return only the number of records specified (up to 1000). The preset number is 100.
Request example:
/api/references?changed-from=2020-01-01&continue-after-id=1&limit=100

Format of the response

The response format is the same for all endpoints.

  • number_of_remaining_ids - the number of remaining entities that meet the specified criteria but are not displayed on the page. An integer of virtually unlimited size.
  • entities - an array of entity details in JSON format.
Response example:
{
    "number_of_remaining_ids" : 100,
    "entities" : [
        {
            "id": 3,
            "url": "https://www.ncbi.nlm.nih.gov/pubmed/32147628",
            "title": "Discovering drugs to treat coronavirus disease 2019 (COVID-19).",
            "impact_factor": "Discovering drugs to treat coronavirus disease 2019 (COVID-19).",
            "tested_on_species": "in silico",
            "publication_date": "2020-22-02",
            "created_at": "2020-30-03",
            "updated_at": "2020-31-03",
            "deleted_at": null
        },
        {
            "id": 4,
            "url": "https://www.ncbi.nlm.nih.gov/pubmed/32157862",
            "title": "CT Manifestations of Novel Coronavirus Pneumonia: A Case Report",
            "impact_factor": "CT Manifestations of Novel Coronavirus Pneumonia: A Case Report",
            "tested_on_species": "Patient",
            "publication_date": "2020-06-03",
                "created_at": "2020-30-03",
            "updated_at": "2020-30-03",
            "deleted_at": null
        },
    ]
}

Endpoint details

Substances

URL: /api/substances

Substances endpoint returns data in the format specified in Response example as an array of entities in JSON format specified in the entity format section.

Entity format:

  • id - Unique identifier in our database (unsigned integer)
  • name - Name of the Substance (string)
  • description - Description (HTML code)
  • phase_of_research - Phase of research (string)
  • how_it_helps - How it helps (string)
  • drug_status - Drug status (string)
  • general_information - General information (HTML code)
  • synonyms - Synonyms (string)
  • marketed_as - "Marketed as" (string)
  • dietary_sources - Dietary sources name (string)
  • dietary_sources_url - Dietary sources URL (string)
  • prescribing_information - Prescribing information as an array of JSON objects with description and URL attributes as strings
  • formula - Formula (HTML code)
  • created_at - Date when the entity was added to our database (Date in ISO 8601 format)
  • updated_at - Date when the entity was last updated in our database (Date in ISO 8601 format)
  • deleted_at - Date when the entity was deleted in our database (Date in ISO 8601 format)
References
URL: /api/references

References endpoint returns data in the format specified in Response example as an array of entities in JSON format specified in the entity format section.

Entity format:
  • id - Unique identifier in our database (unsigned integer)
  • url - URL link of the scientific article (string)
  • title - Title of the scientific article (string)
  • impact_factor - Impact factor of the scientific article (string)
  • tested_on_species - What testing model was used for the study (string)
  • publication_date - Date of publication of the scientific article (Date in ISO 8601 format)
  • created_at - Date when the entity was added to our database (Date in ISO 8601 format)
  • updated_at - Date when the entity was last updated in our database (Date in ISO 8601 format)
  • deleted_at - Date when the entity was deleted in our database (Date in ISO 8601 format)
Reference substance relation
URL: /api/substance-reference-relations

Reference substance relation endpoint returns data in the format specified in Response example as an array of entities in JSON format specified in the entity format section.

Entity format:
  • id - Unique identifier in our database (unsigned integer)
  • reference_id - Id of a reference in our DB (unsigned integer)
  • substance_id - Id of a substance in our DB (unsigned integer)
  • note - Specific note for this relation (string)
  • supporting - Is evidence supporting or contradictory (Boolean, true if supporting)
  • created_at - Date when the entity was added to our database (Date in ISO 8601 format)
  • updated_at - Date when the entity was last updated in our database (Date in ISO 8601 format)
  • deleted_at - Date when the entity was deleted in our database (Date in ISO 8601 format)
Clinical trials
URL: /api/clinical-trials

Reference substance relation endpoint returns data in the format specified in Response example as an array of entities in JSON format specified in the entity format section.

Entity format:
  • id - Unique identifier in our database (unsigned integer)
  • title - Title of clinical trial study
  • acronym_title - Id of a substance in our DB (unsigned integer)
  • source_id - Id of reference in original database (string)
  • source_id_optional - Optional Id in original database (multiple strings delimited by ",")
  • interventions - Description of intervention in study
  • study_type - Type of clinical trial
  • study_results - Current results of clinical trial
  • phase - Phase in which the study currently the clinical trial is
  • url - Url to clinical trial page
  • status - Status of progress in clinical trial
  • start_date - Start date of clinical trial
  • completion_date - Completion date of clinical trial
  • created_at - Date when the entity was created in our database (Date in ISO 8601 format)
  • updated_at - Date when the entity was last updated in our database (Date in ISO 8601 format)
  • deleted_at - Date when the entity was deleted in our database (Date in ISO 8601 format)
Clinical trial substances
URL: /api/clinical-trials-substances

Reference substance relation endpoint returns data in the format specified in Response example as an array of entities in JSON format specified in the entity format section.

This entity doesn't have Unique identifier (ID) and for that reason filtration parameter "continue after ID" was replaced with "offset" filter

  • offset - Number of entities to skip and from beginig to get next chunk of data
Entity format:
  • clinical_trial_id - Id of a clinical trial in our DB (unsigned integer)
  • substance_id - Id of a substance in our DB (unsigned integer)
  • created_at - Date when the entity was added to our database (Date in ISO 8601 format)
  • updated_at - Date when the entity was last updated in our database (Date in ISO 8601 format)
  • deleted_at - Date when the entity was deleted in our database (Date in ISO 8601 format)