Adding api standards pages

docs/getting-started/command-line-interface.md

@@ -34,9 +34,5 @@ poetry install
 
 ## Usage
 
-!!! warning "Coming Soon"
-    [//]: # (TODO)
-    For now, please use the built-in help to learn about the command line interface.
-    ```
-    $ geneweaver --help    
-    ```
+!!! tip
+    Check out the command line interface [reference documentation.](/reference/command-line)

docs/getting-started/index.md

@@ -8,7 +8,7 @@ For more in-depth information about the concepts presented in this section, plea
 the [Concepts](../concepts/index.md) section and the [Reference](../reference/index.md)
 section.
 
-## User Specific Entrypoints
+## Quick Start
 If you're already familiar with Geneweaver, and just need to find content specific to
 your use-case, you can use the following links to jump to the appropriate documentation.
 If you find that you need more information, head back to this website and keep reading!

docs/index.md

@@ -12,82 +12,88 @@
 **Web Application**: 
 [https://www.geneweaver.org](https://www.geneweaver.org)
 
-**Web Application Documentation**: 
-[https://geneweaver.org/help/](https://geneweaver.org/help/)
-
-**Project Documentation (this site)**: 
-[https://bergsalex.github.io/geneweaver-docs/](https://bergsalex.github.io/geneweaver-docs/)
+**API Documentation**:
+[https://geneweaver.jax.org/api/docs](https://geneweaver.jax.org/api/docs)
 ---
 
+<div class="grid cards" markdown>
+
+-   :material-clock-fast:{ .lg .middle } __Get Going Quickly__
+
+    ---
+
+    Architected to make it easy to get started, whichever way makes sense for you.
+
+    [:octicons-arrow-right-24: Jump Into Using The Website](/getting-started/web-application/)
+
+    [:octicons-arrow-right-24: Download the Geneweaver CLI](/reference/command-line/)
+
+    [:octicons-arrow-right-24: Build With Our Python Packages](/reference/available-packages/)
+
+-   :simple-jupyter:{ .lg .middle } __Example Workflows__
+
+    ---
+
+    Follow real examples of how GeneWeaver's tools will be used to do analysis.
+
+    [:octicons-arrow-right-24: NCI-60 Workflow](/tutorial/nci_60_example_01/)
 
-## Components of GeneWeaver
-GeneWeaver is two things: 
+    [:octicons-arrow-right-24: Authenticating With The Client Library](/tutorial/geneweaver_client_login/)
 
-1. A web application 🖥️, and 
-2. An ecosystem of software packages ⚙️.
+-   :material-api:{ .lg .middle } __API Standards__
 
-**Genomics Researchers** will find the web application useful as a fully integrated 
-platform for the analysis of heterogeneous functional genomics data.
+    ---
 
-**Educators**, **students** and **software developers** will find the ecosystem of 
-software packages useful for the development of new tools and applications.
+    Developed to be consistent with our open API Standards.
+
+    [:octicons-arrow-right-24: Standards Documentation](/reference/api-standards/)
+
+-   :material-scale-balance:{ .lg .middle } __Open Source, Apache License 2.0__
+
+    ---
+
+    GeneWeaver is open source and available on [GitHub](https://github.com/orgs/TheJacksonLaboratory/repositories?q=geneweaver).
+
+    [:octicons-arrow-right-24: License](https://github.com/TheJacksonLaboratory/geneweaver-docs/blob/main/LICENSE)
+
+</div>
+
+
+## What Is GeneWeaver?
+**[GeneWeaver](http://www.geneweaver.org)** is a web application for the integrated
+cross-species analysis of functional genomics data from heterogeneous sources. The
+application consists of a large database of gene sets curated from multiple public data
+resources and curated submissions, along with a suite of analysis tools designed to
+allow flexible, customized workflows through web-based interactive analysis or scripted
+API driven analysis. Gene sets come from multiple widely studied species and include
+ontology annotations, brain gene expression atlases, systems genetic study results, gene
+regulatory information, pathway databases, drug interaction databases and many other
+sources. Users can retrieve, store, analyze and share gene sets through a graded access
+system. Gene sets and analysis results can be stored, shared and compared privately,
+among user defined groups of investigators, and across all users. Analysis tools are
+based on combinatorics and statistical methods for comparing, contrasting and
+classifying gene sets based on their members.
+
+## What Is a Gene Set?
+Each **"gene set"** contains a list of genomic features, free text descriptive content,
+ontology annotations and gene association scores. Genomic features are mapped within and
+across multiple species. Currently, 10 species are supported, *Mus musculus, Homo
+sapiens, Rattus norvegicus, Danio rerio, Drosophilia melanogaster, Macaca mulatta,
+Caenorhabditis elegans, Saccharomyces cervisiae, Gallus gallus, Canis familiaris.*
+Additional species are added in response to community request.
+
+## What Can You Do With GeneWeaver?
+**[GeneWeaver](http://www.geneweaver.org)** allows users to integrate these diverse
+functional genomics data across species, tissue and experimental platform to address
+questions about the relations among genes and biological functions. Applications include
+the prioritization of gene-disease associations from multiple evidence sources, the
+classification and comparison of biological functions based on biological substrates,
+and the identification of similar genes based on function. Cross species analysis
+enables the discovery of conserved mechanisms of biological functions, and the discovery
+of divergent functions served by conserved biological mechanisms. 
 
 ## What is this Documentation?
-This documentation is intended to be the foundational documentation for the entire
-Geneweaver software ecosystem. It provides an introduction to the system and ways of
+This documentation provides an introduction to the system and ways of
 working with it, explanations of core concepts, tutorials of general utility,
 as well as detailed reference documentation for the various components and processes
 that make up the system.
-
-## GeneWeaver Use Cases
-Your entrypoint to GeneWeaver will depend on who you are, and what you would like to
-do with GeneWeaver. The following sections will help you find the right place to start
-depending on our best guess as to your goals, based on who you are. Ultimately, you
-will need to make your own decisions about what approach works best for you.
-
-=== "Researchers 🔬"
-    Geneweaver is a valuable resource for any genomics researchers looking to integrate and 
-    analyze complex datasets in order to gain new insights into biological processes and 
-    pathways.
-
-    Geneweaver allows researchers to easily compare and combine datasets from various 
-    sources and analyze the results in an interactive and user-friendly interface. The 
-    system includes a large collection of publicly available datasets, including gene 
-    expression data, protein-protein interactions, and gene ontology annotations, among 
-    others. Geneweaver is a valuable resource for researchers in the field of genomics and 
-    can be used to identify novel gene interactions and pathways, as well as to explore the 
-    functional relationships between genes and biological processes.
-=== "Educators & Students 📚"
-    For educators, GeneWeaver provides a comprehensive platform for integrating real world 
-    data and open sources software into the classroom. GeneWeaver provides data, tools, 
-    systems, and workflows that can be used to teach students about genomics, 
-    bioinformatics, computer science and data science. 
-
-    GeneWeaver allows students and educators to integrate with a full cycle of development 
-    and learning, starting with application to real-world concepts and data, and ending with
-    the development and contribution of new tools and applications.
-
-    The following disciplines might find GeneWeaver useful:
-
-    - **Computer Science**
-        - Algorithms
-        - Software Engineering
-        - Databases
-        - Data Science
-    - **Biology and Genomics**
-    - **Bioinformatics**
-    - **Mathematics**
-=== "Software Developers 💻"
-    For software developers, GeneWeaver provides a suite of open source software 
-    packages that can be used for the development of new tools and applications. 
-    GeneWeaver is built on a collection of open source software 
-    packages. A software developer could use all or some of that ecosystem to build new
-    applications and tools.
-
-    Software developers can leverage the ecosystem of open source Python packages used 
-    in Geneweaver.org through its package-based architecture to build new bioinformatics 
-    tools and applications, contribute to existing packages, integrate with other tools,
-    and address specific needs or gaps in the ecosystem.
-
-
-

docs/reference/api-standards/api_monitoring.md

@@ -0,0 +1,35 @@
+# API Monitoring
+> These guiding principles will help stability, uptime, and awareness for your applications.
+
+Actuator endpoints let you monitor and interact with your application. For language
+specific tutorials (please see here)[/Development/Tutorials/Monitoring/endpoints]. 
+
+## Monitoring
+Our endpoints for monitoring and info will exist at 
+
+```
+/api/monitor/<resource>/<type>
+```
+
+## Health Endpoint
+
+<span style="color:red">**Required**</span>
+
+
+This endpoint provides health information, mainly the status of the application. It will be the
+primary target for monitoring services.
+
+Location:
+```
+http://127.0.0.1/api/monitor/server/health
+```
+Example Response:
+````
+{"name":"Fancy Application","status":"UP","details":"Everything seems okay."}
+````
+
+| Status Text      | Http Status Code                     |
+| ----------- | ------------------------------------ |
+| `UP`        |  200 |
+| `UNKNOWN`   |  200 |
+| `DOWN`      |  503 |

docs/reference/api-standards/api_versioning.md

@@ -0,0 +1,152 @@
+# API Versioning and Backwards Compatibility
+
+!!! success "Overview" 
+    In order to prioritize simplicity, reliability, and maintainability we seek to 
+    **minimize the need for API versioning** _as much as possible_.
+
+API versioning is a strategy to ensure that changes to the structure, 
+features, or behavior of an API (Application Programming Interface) do not break 
+applications that depend on it. APIs allow different software applications to 
+communicate and interact with each other, so changes to an API can have broad impacts.
+
+!!! tip
+    If your service has a single client, **which you control**, then you can avoid
+    versioning altogether. You also **do not** need to version APIs which have not yet
+    been released. 
+
+!!! warning 
+    This document talks about versioning API deployments, a process that is separate 
+    from application release versioning, which is described in the 
+    [Software Versions Document](/Operations/Best_Practices/software_versions/).
+
+    In the context of application release versioning, this document describes the 
+    process of incrementing the **major** version number. For example, going from
+    `v1.0.0` to `v2.0.0`.
+
+
+## Guiding Principles
+
+1. **Minimal versioning**: We avoid versioning unless absolutely necessary. This
+   approach reduces complexity, both for the team developing the API and for those who
+   consume it. We strive, whenever possible, to make changes that are backwards
+   compatible.
+
+2. **Independent changes for reproducible science**: To support reproducible science,
+   it's essential that we can modify APIs without impacting the analysis. This principle
+   allows us to evolve our systems independently, providing robustness and flexibility.
+
+When versioning becomes unavoidable due to changes that can break existing clients, we
+should follow the strategies provided in
+this [guide](https://www.xmatters.com/blog/blog-four-rest-api-versioning-strategies/).
+
+!!! danger
+    Versioning is not a substitute for good API design. We should always strive to
+    design APIs that are flexible and extensible, and that can evolve without breaking
+    existing integrations. **Incrementing a major version should be a last resort.**
+
+
+## Backwards Compatibility
+
+Backwards compatibility is as important as versioning. By maintaining backwards
+compatibility, we allow API consumers to upgrade at their own pace without breaking
+their existing integrations. Strategies to ensure backwards compatibility include:
+
+1. **Adding new fields**: When adding new data, do so by adding new fields that older
+   clients will simply ignore. The simplest way to do this is to add new fields that 
+   have a default value. 
+
+2. **Avoid removing fields**: Removing data fields may break existing integrations. It's
+   safer to deprecate old fields and leave them in place, while encouraging clients to
+   use new fields.
+
+3. **Keeping old endpoints**: If creating a new version of an endpoint, consider keeping
+   the old one for a time to allow clients to transition gradually.
+
+4. **Communicating changes**: Whenever a change is made that affects the API, it's
+   important to inform consumers in advance to give them time to adapt.
+
+
+## Service Information Endpoint
+
+A service information endpoint is a valuable tool in API design, especially in terms of
+API versioning and backwards compatibility. The service information endpoint provides a
+clear way for client applications to understand the current state of the service, its
+capabilities, and its versioning details. This enables clients to interact more
+intelligently and efficiently with the service, adjusting their behavior based on the
+information returned by this endpoint.
+
+Here's how a service information endpoint contributes to API versioning and backward
+compatibility:
+
+1. **Communicating Version Information**:
+   The version of the API is often part of the service information. This makes it clear
+   to any consumers of the API what version they are interfacing with. Consumers can
+   then decide how to handle any changes based on the version information. This is where
+   an application would provide its deployed
+   [Software Version](/Operations/Best_Practices/software_versions/) number.
+
+2. **Facilitating Backward Compatibility**:
+   By communicating what features, workflows, and filesystem protocols are supported by
+   the service, a client application can adjust its behavior to only use features
+   supported by the current API version. This allows older clients to still function
+   correctly, even if new features or changes have been introduced in the latest version
+   of the API.
+
+3. **Providing Useful Metadata**:
+   Additional information such as the name, description, environment, and contact
+   details helps clients understand more about the service. For instance, it can help
+   debug issues (e.g., if the environment is "test", the behavior might be different
+   from a production environment).
+
+4. **Allowing Intelligent Client Behavior**:
+   In a more advanced use case, a client application might use the service information
+   to decide between different APIs or services. 
+
+## When We Need to Version
+
+Despite our minimal versioning philosophy, there may be situations that require it.
+These could include major architectural changes, the addition of new features that
+aren't compatible with the current API design, or the nature of the system that's being
+changed. 
+
+In these cases, we should follow the versioning strategies outlined below.
+
+### Versioning Strategies
+
+When we need to introduce versioning, you might consider adopting one of the following
+strategies:
+
+1. **URI Versioning**: In this strategy, the version information is included in the URI
+   itself. This is very simple and straightforward, but it can break URI consistency and
+   may cause confusion.
+
+      1. **URI Path**: This option involves including the version number as part of
+         the URI path. This allows clients to cache resources easily, but requires 
+         branching the entire API when incrementing the version.
+
+      2. **Query Parameters**: This option involves including the version number as a
+         query parameter. This is straightforward to implement, but can become 
+         difficult to manage across multiple endpoints. It also requires maintaining
+         all versions of the endpoints in a single application build.
+
+2. **Request Header Versioning**: This approach keeps the URI clean and includes the
+   version information in the request header. This preserves URI consistency, but it
+   requires consumers to add version information to their requests.
+
+3. **Media Type Versioning (Accept Header)**: This strategy requires the client to
+   specify the version in the Accept header. It offers clean URIs, but it may increase
+   complexity for clients.
+
+4. **Hypermedia As The Engine Of Application State (HATEOAS)**: This is the most complex
+   strategy, but it provides a lot of flexibility. It allows API consumers to navigate
+   APIs through hypermedia links.
+
+Remember, the choice of versioning strategy should be informed by our guiding
+principles, the needs of our API consumers, and the nature of the changes that require
+versioning. You should pick the strategy that best fits the situation of your 
+application and it's needs, and prioritize minimizing API versioning as much as 
+possible.
+
+!!! tip
+    For more information on possible versioning strategies, see this
+    [guide](https://www.xmatters.com/blog/blog-four-rest-api-versioning-strategies/).