API documentation

progenetix · Nov 11, 2024 · 9912d31 · 9912d31
1 parent c7611de
commit 9912d31
Show file tree

Hide file tree

Showing 13 changed files with 580 additions and 228 deletions.
diff --git a/bycon/config/entity_defaults.yaml b/bycon/config/entity_defaults.yaml
@@ -125,7 +125,7 @@ individual:
     The type of response used for the endpoint depends on the requested and granted
     `responseGranularity`, _i.e._ while a "record" level `responseGranularity`
     has to be served through a `beaconResultsetsResponse` other granularities
-    might employ aggregate response types.
+    might employ summary response types.
   request_entity_path_id: individuals
   response_entity_id: individual
   collection: individuals

diff --git a/docs/API-beacon.md b/docs/API-beacon.md
@@ -0,0 +1,20 @@
+# API: Beacon Responses
+
+The following is a list of standard Beacon responses supported by the `bycon` package.
+Responses for individual entities or endpoints are grouped by their Beacon framework
+response classes (e.g. `beaconResultsetsResponse` for `biosamples`, `g_variants` etc.).\n\n
+Please be reminded about the general syntax used in Beacon: A **path element** such
+as `/biosamples` corresponds to an entity (here `biosample`). Below these relations
+are indicated by the `@` symbol.\n\n
+
+!!! info "API Parameters"
+    A complete list of parameters accepted by the API is provided on the [_Web and Command Line Parameters_](API-parameters.md) page.
+
+#### Schemas **{S}**, Tests **{T}** and Examples **{E}**
+Tests, examples and schemas are run from the server defined in this site's build instructions
+(see the `reference_server_url` entry in `mkdocs.yaml` file in the repository's root).
+
+{%
+    include-markdown "generated/beacon-responses.md"
+%}
+
diff --git a/docs/API-parameters.md b/docs/API-parameters.md
@@ -0,0 +1,32 @@
+# API: Web and Command Line Parameters
+
+## General API Parameters
+
+The `bycon` package supports number of parameters for filtering and querying the data which includes and extends
+standard Beacon parameters and can - depending on the parameter and the current scope - in general be
+invoked through HTTP requests and as command line arguments.
+
+Only parameters sefined in `config/argument_definitions.yaml` will be
+interpreted.
+
+Parameters are listed in `snake_case` format although for command line arguments
+(and also optionally web requests) `camelCase` versions are required (see the `cmdFlags`).
+
+
+{%
+    include-markdown "generated/argument_definitions.md"
+%}
+
+## Services: Plot Parameters
+
+The `byconServices` package inside `bycon` provides a number of plotting functions which can be used to visualize the data in the database. Generally
+plot functionality is focussed on generating CNV visualizations for per-sample and
+aggregated CNV data (e.g. frequencyplots). Additionally some geographic map projectins are provided e.g. for samples and metadata.
+
+More information can be found on these pages:
+
+* plot documentation on [this page](plotting.md)
+
+{%
+    include-markdown "generated/plot_defaults.md"
+%}
diff --git a/docs/API-services.md b/docs/API-services.md
@@ -0,0 +1,58 @@
+# API: Beacon Services
+
+The _bycon_ environment provides a number of data services beyond typical Beacon
+functionality. These services can be loosely grouped into two major types:
+
+* services which extend Beacon formats, _i.e._ use Beacon concepts and query
+  parameters but provide non-standard output
+    - plotting functions
+    - tabular and text output
+    - aggregated data such as CNV frequencies (see [_intervalFrequencies_](services/intervalFrequencies.md))
+* services which make use of utility function and data existing primarily for the
+  support of Beacon functionality
+    - ontology term cross mapping
+    - geneId to location lookup
+    - geographic location mapping and map projections (see [_geolocations_](services/geolocations.md))
+    - ISCN cytogenetic band mapping
+    - publication data for cancer genome screening publications
+
+!!! info "API Parameters"
+    A complete list of parameters accepted by the API is provided on the [_Web and Command Line Parameters_](API-parameters.md) page.
+
+## Response formats
+
+Standard responses are provided as `Content-Type: application/json`. The wrapper
+format is based on the Beacon v2 response format, with the data returned in the
+`results` array: 
+
+```
+meta:
+  api_version: ...
+  returned_schemas: [ ]
+response:
+  exists: true | false
+  info: { }
+  resultSets: [ ]
+```
+
+This (incomplete) example response may help with understanding the general
+format. Here, the data is a dictionary/object with a single key (`genes`):
+
+#### Request Example
+
+* <https://progenetix.org/services/genespans?geneId=CDKN2>
+
+## Plotting
+
+The `byconServices` package inside `bycon` provides a number of plotting functions which can be used to visualize the data in the database. Generally
+plot functionality is focussed on generating CNV visualizations for per-sample and
+aggregated CNV data (e.g. frequencyplots). Additionally some geographic map projectins are provided e.g. for samples and metadata.
+
+More information can be found in the plot documentation on [this page](plotting.md).
+
+## List of Services
+
+{%
+    include-markdown "generated/beacon-services.md"
+%}
+
diff --git a/docs/API.md b/docs/API.md
@@ -1,19 +1,20 @@
 # API Documentation
 
-## Beacon Responses [:link:](/generated/beacon-responses)
+{%
+    include-markdown "generated/beacon-responses.md"
+%}
 
-
-## Service Endpoints [:link:](/generated/services)
+## Service Endpoints [:link:](/generated/services.md)
 
 Additionally to the standard Beacon endpoints provided for the Beacon framework and default data model
 `bycon` also has a number of service endpoints. Some of them are used to provide direct Beacon support (e.g. `/endpoints` or `/schemas` to implement endpoints accessed from Beacon responses), while others
 provide more specialized functionality (e.g. `/cytomapper`).
 
 More information:
 
-* [list of bycon services](/generated/services)
+* [list of bycon services](/generated/services.md)
 
-## Parameters  [... more](/generated/argument_definitions)
+## Parameters  [... more](/generated/argument_definitions.md)
 
 The `bycon` package supports number of parameters for filtering and querying the data which includes and extends
 standard Beacon parameters and can - depending on the parameter and the current scope - in general be
@@ -22,7 +23,7 @@ invoked through HTTP requests and as command line arguments.
 Only parameters sefined in `config/argument_definitions.yaml` will be
 interpreted. Those parameters are listed in [this document](/generated/argument_definitions).
 
-## Endpoint Tests [... more](/tests)
+## Endpoint Tests [... more](/tests.md)
 
 ==TBD==
 
@@ -34,5 +35,5 @@ aggregated CNV data (e.g. frequencyplots). Additionally some geographic map proj
 
 More information can be found on these pages:
 
-* plot documentation on [this page](/plotting)
-* plot [parameters and defaults](/generated/plot_defaults)
+* plot documentation on [this page](./plotting.md)
+* plot [parameters and defaults](./generated/plot_defaults.md)