diff options
| -rw-r--r-- | api/API-structure-implementation-notes.org | 92 |
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. |