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 three entities:

  • Substances - /api/substances
  • References - /api/references
  • Substance reference relations - /api/substance-reference-relations

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)