1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
|
# GeneNetwork REST API (version 2)
We are working on a new REST API that is more consistent.
## Prefix
* `api:` is the prefix we use for the API and expands to https://genenetwork.org/api/v2 or similar, so `api:species` expands to https://genenetwork.org/api/v2/species
* `doc:` is the prefix we use for the documentation and expands to https://genenetork.org/doc, so `doc:species.html` expands to https://genenetwork.org/doc/species.html
## Postfix extension
* The API call with .json extension returns a record *without* metadata, i.e., the data version. Example of a URI: `api:species/Mus_musculus.json` or, the short form, `api:mouse.json`. This typically represents the API call that people use (see below for some output).
* The API call with .meta.json extension returns the metadata, including a link to the docs and links to dig further into the API. Example: `api:species/Mus_musculus.meta.json`, or the short form, `api:mouse.meta.json` (see below for output).
* The API call with other extensions may return CSV, TSV etc. Depending on *documented* implementation details.
So, for species list in GN we get:
* api:species.json
* api:species.meta.json
* doc:species.html
We may forward api:species/ (no extension) to doc:species.html.
So, for mouse with its alias we'll get:
* api:species/Mus_musculus.json
* api:mouse.json
* api:species/Mus_musculus.meta.json
* api:mouse.meta.json
* doc:species/Mus_musculus.html
* doc:mouse.html
We may forward `api:mouse` and `api:species/Mus_musculus` (no extension) to `doc:Mus_musculus.html`
# JSON data
Standard JSON data (the .json postfix) will return a minimal structure that requires the minimum amount of work to parse. Example `api:mouse.json` can result in a dictionary of:
```json
{
"id": "Mouse",
"wikidata": "Q83310",
"taxonomy-id": "10090",
"ncbi-url": "https://www.ncbi.nlm.nih.gov/Taxonomy/Browser/wwwtax.cgi?mode=Info&id=10090",
"uniprot-url": "https://www.uniprot.org/taxonomy/10090",
"wikidata-url": "http://www.wikidata.org/entity/Q83310",
"taxonomy-name": "Mus musculus",
"description": "species of mammal",
"organism": "http://purl.uniprot.org/taxonomy/10090",
"family": "Vertebrates",
"binomialName": "Mus musculus",
"22-rdf-syntax-ns#isDefinedBy": "http://www.wikidata.org/entity/Q83310",
"rdf-schema#label": "Mouse (Mus musculus, mm10)",
"name": "Mouse"
}
```
We'll probably get rid of some duplication and terms.
# Metadata
Metadata contains further information on a JSON record, but typically not the data that is already served by above JSON record. Example for `api:mouse.meta.json`
```json
{
"api": "api:mouse.json",
"doc": "doc:mouse.html",
"links": {
# Expand on metadata links that can be followed:
"strains": {
"BXD12": "api:BXD12.meta.json",
"BXD13": "api:BXD13.meta.json",
}
}
}
```
|
