aboutsummaryrefslogtreecommitdiff
path: root/api
diff options
context:
space:
mode:
authorrupertoverall2023-07-12 12:36:08 +0200
committerGitHub2023-07-12 12:36:08 +0200
commit8573f47b50de5b986bb38367d315a2a9053d1dbc (patch)
tree888918e6cfe85d0f3b79cfb0ae5e7fdde466a53e /api
parent1b7060314c1a6d55d1e68d4fb2facf60d598cdb0 (diff)
downloadgn-docs-8573f47b50de5b986bb38367d315a2a9053d1dbc.tar.gz
Update alternative-API-structure.md
Diffstat (limited to 'api')
-rw-r--r--api/alternative-API-structure.md113
1 files changed, 112 insertions, 1 deletions
diff --git a/api/alternative-API-structure.md b/api/alternative-API-structure.md
index df65b9b..5261e09 100644
--- a/api/alternative-API-structure.md
+++ b/api/alternative-API-structure.md
@@ -83,7 +83,118 @@ Suggested URLs for each query are given below.
<hr>
-## Fetch tests
+## Mock-up API
+Each level has two types of associated metadata: detailed information about the current level ('info') and a listing of options/endpoints at the next level ('index').
+One of these endpoints could/should be returned without a keyword---probably the 'info' is more useful and intuitive.
+
+### API version
+For the highest level ('version'), the results might look like this:
+
+https://genenetwork.org/api/2.0/info
+
+or
+
+https://genenetwork.org/api/2.0
+```
+{
+ "name": "GeneNetwork REST API",
+ "version": "2.0",
+ "comment": "This is the official REST API for the GeneNetwork service hosted at https://genenetwork.org/",
+ "license": {
+ "source code": "AGPL"
+ },
+ "note": "work in progress (WIP)",
+ "see also": "https://genenetwork.org/api/2.0/meta",
+ "next level": "species",
+ "next level options": "https://genenetwork.org/api/2.0/index"
+}
+```
+
+https://genenetwork.org/api/2.0/index *Has the advantage that the 'index' keyword works at all levels even if the next level is unknown to the user.*
+```
+{
+ "API": {
+ "https://genenetwork.org/api/2.0/species": "Get a list of all species",
+ "https://genenetwork.org/api/2.0/Arabidopsis_thaliana": "Get information on mouse (Arabidopsis thaliana; Taxonomy ID 3702)",
+ "https://genenetwork.org/api/2.0/Drosophila_melanogaster": "Get information on fruit fly (Drosophila melanogaster; Taxonomy ID 7227)",
+ "https://genenetwork.org/api/2.0/Glossophaga_soricina": "Get information on bat (Glossophaga soricina; Taxonomy ID 27638)",
+ "https://genenetwork.org/api/2.0/Glycine_max": "Get information on soybean (Glycine max; Taxonomy ID 3847)",
+ "https://genenetwork.org/api/2.0/Homo_sapiens": "Get information on human (Homo sapiens; Taxonomy ID 9606)",
+ "https://genenetwork.org/api/2.0/Hordeum_vulgare": "Get information on barley (Hordeum_vulgare; Taxonomy ID 4513)",
+ "https://genenetwork.org/api/2.0/Mus_musculus": "Get information on mouse (Mus musculus; Taxonomy ID 10090)",
+ "https://genenetwork.org/api/2.0/Oryzias_latipes": "Get information on medaka fish (Oryzias latipes; Taxonomy ID 8090)",
+ "https://genenetwork.org/api/2.0/Populus_trichocarpa": "Get information on California poplar/black cottonwood (Populus trichocarpa; Taxonomy ID 3694)",
+ "https://genenetwork.org/api/2.0/Rattus_norvegicus": "Get information on rat (Rattus norvegicus; Taxonomy ID 10116)",
+ "https://genenetwork.org/api/2.0/Solanum_lycopersicum": "Get information on tomato (Solanum lycopersicum; Taxonomy ID 4081)"
+ }
+}
+```
+
+
+### Species
+The next level is 'species'.
+A listing of all the species available can be obtained from `$api/2.0/index` as above, but it might also be useful to have an alias like `$api/2.0/species`.
+
+https://genenetwork.org/api/2.0/species
+```
+{
+ "API": {
+ "https://genenetwork.org/api/2.0/species": "Get a list of all species",
+ "https://genenetwork.org/api/2.0/Arabidopsis_thaliana": "Get information on mouse (Arabidopsis thaliana; Taxonomy ID 3702)",
+ "https://genenetwork.org/api/2.0/Drosophila_melanogaster": "Get information on fruit fly (Drosophila melanogaster; Taxonomy ID 7227)",
+ "https://genenetwork.org/api/2.0/Glossophaga_soricina": "Get information on bat (Glossophaga soricina; Taxonomy ID 27638)",
+ "https://genenetwork.org/api/2.0/Glycine_max": "Get information on soybean (Glycine max; Taxonomy ID 3847)",
+ "https://genenetwork.org/api/2.0/Homo_sapiens": "Get information on human (Homo sapiens; Taxonomy ID 9606)",
+ "https://genenetwork.org/api/2.0/Hordeum_vulgare": "Get information on barley (Hordeum_vulgare; Taxonomy ID 4513)",
+ "https://genenetwork.org/api/2.0/Mus_musculus": "Get information on mouse (Mus musculus; Taxonomy ID 10090)",
+ "https://genenetwork.org/api/2.0/Oryzias_latipes": "Get information on medaka fish (Oryzias latipes; Taxonomy ID 8090)",
+ "https://genenetwork.org/api/2.0/Populus_trichocarpa": "Get information on California poplar/black cottonwood (Populus trichocarpa; Taxonomy ID 3694)",
+ "https://genenetwork.org/api/2.0/Rattus_norvegicus": "Get information on rat (Rattus norvegicus; Taxonomy ID 10116)",
+ "https://genenetwork.org/api/2.0/Solanum_lycopersicum": "Get information on tomato (Solanum lycopersicum; Taxonomy ID 4081)"
+ }
+}
+```
+
+To get information on a particular species, use the ID/key given in the listing:
+
+https://genenetwork.org/api/2.0/Mus_musculus
+
+```
+{
+ "binomial_name": "Mus musculus",
+ "id": Mus_musculus,
+ "alias": "mouse",
+ "taxon_id": "10090",
+ "wikidata_id": "Q83310",
+ "tags", ["vertebrate", "mammal", "rodent"]
+}
+```
+
+At the next level are 'populations' and the available mouse populations can be determined using the index endpoint as above:
+
+https://genenetwork.org/api/2.0/Mus_musculus/index
+
+```
+{
+ "API": {
+ "https://genenetwork.org/api/2.0/Mus_musculus/populations": "Get a list of all populations available for this species",
+ "https://genenetwork.org/api/2.0/Mus_musculus/BXD": "Get information on the BXD population",
+ "https://genenetwork.org/api/2.0/Mus_musculus/MDP": "Get information on the MDP population",
+ "https://genenetwork.org/api/2.0/Mus_musculus/LXS": "Get information on the LXS population",
+ "https://genenetwork.org/api/2.0/Mus_musculus/BXH": "Get information on the BXH population",
+ "https://genenetwork.org/api/2.0/Mus_musculus/AXBXA": "Get information on the AXBXA population",
+ "https://genenetwork.org/api/2.0/Mus_musculus/B6D2F2": "Get information on the B6D2F2 population",
+ "https://genenetwork.org/api/2.0/Mus_musculus/AKXD": "Get information on the AKXD population",
+ "https://genenetwork.org/api/2.0/Mus_musculus/CFW": "Get information on the CFW population",
+ "https://genenetwork.org/api/2.0/Mus_musculus/HS": "Get information on the HS population",
+ "https://genenetwork.org/api/2.0/Mus_musculus/LGSM": "Get information on the LGSM population",
+ "https://genenetwork.org/api/2.0/Mus_musculus/DO": "Get information on the DO population",
+ "https://genenetwork.org/api/2.0/Mus_musculus/CC": "Get information on the CC population"
+ }
+}
+```
+
+## Fetch tests (to be updated with real URLs as they are implemented)
### Fetch species listing
Species are the highest level of grouping.
```{r echo = FALSE}