DevNotes

Overview

For a general schematic of the open tree architecture, see this [architectural diagram] 1. The basic goal of this repo is provide web-service interfaces to the corpus of phylogenetic studies. The corpus is referred to as phylesystem.

The phylesystem-api provides basic read/write access and format conversion. Search functionality is supplied by oti.

Workflow

A typical series of study edit operations, as choreographed by the open tree curator app (which is running the code in the curator subdir of the opentree repo is shown below. We are in the process of moving from v1 of the API to v2, so some of the URLs used could be stale. The template configuration file holds the patterns used to construct the actual URLs used by the curator app; so you should use that if you need the exact URLs.

1. request brief list of studies and metadata from oti's findAllStudies service
2. user selects a study, and curator app fetches a "NexSON with extra info" using a GET to phylesystem-api's v1/study/{STUDY_ID}.
3. the user corrects various deficiencies of the study, and the curator app saves these changes using a PUT to phylesystem-api's v1/study/{STUDY_ID}

Step 2 of editing - the GET by the curator app:

On the server side this triggers several calls to peyotl's Phylesystem wrapper. The key one's are:

1. phylesystem.return_study
2. phylesystem.add_validation_annotation
3. phylesystem.get_version_history_for_study_id

In terms of the actions performed on the server, these steps entail.

1. the phylesystem-api waits for lock on the phylesystem git repo
2. the master branch is checked out
3. the requested study is read.
4. If a no cached validation annotation for the study is available, then one is generated.
5. The annotation injected into the NexSON
6. the version history of the study is constructed
7. the phylesystem git repo is unlocked.
8. the "extra info" is added to the response JSON which will also hold the NexSON

Side note (or slide note, if you prefer)

The slide presentation containing the [architectural diagram] 1 is posted at http://phylo.bio.ku.edu/slides/ot.html and it can be regenerated by running https://github.com/OpenTreeOfLife/phylesystem-api/blob/master/docs/build-presentations.sh)