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",
+    }
+  }
+}
+```