diff options
| -rw-r--r-- | api/GN-REST-API-v2.md | 77 |
1 files changed, 77 insertions, 0 deletions
diff --git a/api/GN-REST-API-v2.md b/api/GN-REST-API-v2.md new file mode 100644 index 0000000..1576a74 --- /dev/null +++ b/api/GN-REST-API-v2.md @@ -0,0 +1,77 @@ +# 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: `api:species/Mus_musculus.json` or, the short form, `api:mouse.json`. This typically represents the API call that people use + +* 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` + +* 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 of parsin. Example for `api:mouse.json` can be + +```js +{ + "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" +} +``` + +# Metadata + +Metadata contains information on a record, but typically not the data that is already served by above JSON record. Example for `api:mouse.meta.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", + } + } +} +``` |