The API
Everything this website shows is also available as JSON, under /api/v1. It is free, and needs
no key. Each disease group, human gene and human disease has an address of its own, the same as its page with
/api/v1 in front.
Every endpoint is described in the OpenAPI file, and shown on the Swagger page, where each one can be tried.
The endpoints
One disease group, with its whole chain.
curl https://comparative.janook.org/api/v1/disease-groups/1081Every disease group, in pages. Only those whose chain reached the drugs, by best score:
curl https://comparative.janook.org/api/v1/disease-groups?reach=DRUG&sort=scoreOne human gene, and every animal disease that reaches it. A symbol leads to the gene's own address.
curl https://comparative.janook.org/api/v1/human-genes/ENSG00000198947One human disease, and every animal disease that reaches it. An OMIM number leads to the disease's own address.
curl https://comparative.janook.org/api/v1/human-diseases/MONDO:0010679Search, as the search box does.
curl https://comparative.janook.org/api/v1/search?q=eteplirsenThe disease groups one search term leads to, such as a species.
curl https://comparative.janook.org/api/v1/search/disease-groups?kind=SPECIES&key=9615How the natural-model score is computed.
curl https://comparative.janook.org/api/v1/scoreThe current build, and the release of each source it read.
curl https://comparative.janook.org/api/v1/buildWhat every answer holds
An answer that holds data has three parts. build names the build it was read from, and the
address that lists the release of each source. credits holds OMIA's citation, and ChEMBL's
credit where the answer holds drugs. data is the answer itself.
Codes. Every status is given as a code a program can test, such as
NO_NCBI_GENE, next to the same words the page shows. Test the code: the words may be improved
at any time.
What does not change. Within /api/v1, a field is never
renamed or removed, and its meaning never changes. New fields may be added, so a program must ignore fields
it does not know.
Errors. A failed request answers with status,
code, such as NOT_FOUND, a message for a person, and
fields, which names any parameter that was refused, and why.
The limit
One address may ask 60
times a minute. Every answer says how many requests are left, in RateLimit-Limit,
RateLimit-Remaining and RateLimit-Reset, the seconds until the count starts again.
Past the limit the answer is 429, with Retry-After. A program should wait that many
seconds and ask again. Requests sent from the Swagger page count too.
An answer changes only when a new build becomes current, about once a month. Each answer carries an
ETag, and may be kept for an hour. A request that sends If-None-Match with the
current ETag gets 304, with no body.
Credits
The animal disease data comes from OMIA, Online Mendelian Inheritance in Animals, used with the permission of its curators. Anything built from it must cite OMIA as:
Nicholas, F.W., Tammen, I., & Sydney Informatics Hub. (1995). Online Mendelian Inheritance in Animals (OMIA) [dataset]. https://omia.org/; https://doi.org/10.25910/2AMR-PV70. The data were made available by software support from the Sydney Informatics Hub, funded from the Ronald Bruce Anstee bequest to the Sydney School of Veterinary Science for the Anstee Hub for Inherited Diseases in Animals (AHIDA)
The drug data is ChEMBL's, under CC BY-SA 3.0, and came through Open Targets. Anything that holds it must name ChEMBL and keep the same licence. Every source, and its terms.