aboutsummaryrefslogtreecommitdiff
path: root/api
diff options
context:
space:
mode:
authorFrederick Muriuki Muriithi2023-07-14 11:42:43 +0300
committerFrederick Muriuki Muriithi2023-07-14 11:42:43 +0300
commitcf62638ab1b1ed30d59e85dcbfd77c7413862f8f (patch)
tree2b01a21580aeffe7ab804932830231693357df01 /api
parent86e27511a05c44f342340490cffc0ea00c32aac6 (diff)
downloadgn-docs-cf62638ab1b1ed30d59e85dcbfd77c7413862f8f.tar.gz
Add notes with ideas on implementation.
Diffstat (limited to 'api')
-rw-r--r--api/API-structure-implementation-notes.org92
1 files changed, 92 insertions, 0 deletions
diff --git a/api/API-structure-implementation-notes.org b/api/API-structure-implementation-notes.org
new file mode 100644
index 0000000..7763236
--- /dev/null
+++ b/api/API-structure-implementation-notes.org
@@ -0,0 +1,92 @@
+#+STARTUP: content
+#+TITLE: API Structure Implementation Notes
+
+* Introduction
+
+This document is subservient to the following documents:
+- [[./alternative-API-structure.md][Notes on the API]]
+- [[./questions-to-ask-GN.md][Questions to ask GN]]
+
+If there are any conflicts, refer to the documents above for clarification. This
+simply follows those documents, and might thus be out of sync from time to time.
+
+This document is mostly for those concerned with the implementation of the API.
+End users of the API should probably concern themselves with the other document,
+though that is not to say they will not find useful information here.
+
+* Routing
+
+It is possible to have separate API versions: we could make use of blueprints
+for this and flask's ~add_url_rule~. With this, we should be able to reuse
+existing code, writing new code for only the endpoints that might need them.
+
+For example, we could have a file =gn3/api/version02.py= with
+content like:
+
+#+BEGIN_SRC python
+ from flask import url_for, Blueprint
+
+ from wqflask import species
+ from wqflask import populations
+ ...
+
+ v2 = Blueprint("v2", __name__)
+
+ @v2.route("/")
+ @v2.route("/info")
+ def info():
+ """Information for the root of the V2 endpoints"""
+ return {
+ "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": url_for("api.v2.species.index"),
+ "next level options": url_for("api.v2.index")
+ }
+
+ def index():
+ """The index of the URIs accessible from this level of the API."""
+ return {
+ "API": {
+ url_for(rule.endpoint): rule.endpoint.__doc__
+ for rule in v2.url_map.iter_rules()
+ }
+ }
+
+ v2.add_url_rule("/species", endpoint=species.index, methods=["GET"])
+ v2.add_url_rule("/<species>", endpoint=species.species_info, methods=["GET"])
+ v2.add_url_rule("/<species>/populations",
+ endpoint=populations.index,
+ methods=["GET"])
+ v2.add_url_rule("/<species>/<population>",
+ endpoint=populations.population,
+ methods=["GET"])
+ ...
+#+END_SRC
+
+and that would then be registered with the main application with something like:
+
+#+BEGIN_SRC python
+ # file gn3/app.py
+ ...
+
+ def create_app(...):
+ ...
+ from api.version02 import v2
+ ...
+ app.register_blueprint(v2, url_prefix="/api/2.0")
+ ...
+#+END_SRC
+
+The code above demonstrates the idea, but will probably need some cleanup for
+real-world use.
+
+Some url endpoints, especially =.../index= endpoint, will need for the final
+URI's to be computed from the available data, e.g. for =/species/index= we have
+eleven (11) species listed in the proposed documentation, but the underlying
+data could change, if say, a new species is added to the system.