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 queryingchanged-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 withid
and current dates increated_at
andupdated_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 say2020-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 stringsformula
- 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/referencesReferences 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-relationsReference 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)