[pull] master from federated-data-sharing:master

.gitignore

@@ -0,0 +1,2 @@
+.RData
+.Rhistory

.gitmodules

@@ -0,0 +1,9 @@
+[submodule "common-api-metadata"]
+	path = common-api-metadata
+	url = git@github.com:federated-data-sharing/common-api-metadata.git
+[submodule "common-api-selection"]
+	path = common-api-selection
+	url = git@github.com:federated-data-sharing/common-api-selection.git
+[submodule "common-api-tasks"]
+	path = common-api-tasks
+	url = git@github.com:federated-data-sharing/common-api-tasks.git

README.md

@@ -2,46 +2,76 @@
 
 ## Introduction
 
-This repository contains OpenAPI definitions for the Common API for Federated Data Sharing. The API was original developed to facilitate collaboration and trusted data sharing networks between trusted research environments and data repositories. 
+This repository contains OpenAPI definitions for the Common API for Federated Data Sharing. The Common API was developed to facilitate collaboration and trusted data sharing networks between trusted research environments and data providers.
 
-The code is licensed under the [Mozilla Public License 2.0](https://www.mozilla.org/en-US/MPL/2.0/) see [LICENSE](./LICENSE). As more organisations are joining the effort, a new governance process will be established. In the meantime, please contact [Aridhia Informatics](https://www.aridhia.com/contact-our-team/) for more information.
+## Documentation
 
-## API overview
+- [API Overview](./doc/API_Overview.md)
+- [User Guide](./doc/User_Guide.md)
+- [Origins](./doc/Origins.md)
+- A separate repository provides [Worked examples](https://github.com/federated-data-sharing/common-api-examples)
+- *Coming Soon*  A reference implementation is being developed to facilitate the technical choices for data providers.
 
-The federated data sharing API provides a set of endpoints required that provide a 'common' API to organisations wishing to participate in data sharing or federated analysis. There are three sections to the API:
+## Summary benefits
 
-- Metadata
-- Selection
-- Federated compute 
+<table>
+    <tr>
+        <td valign="top">
 
-Note that the federated compute API section is being reviewed and will be added shortly.
+**For Data providers**
 
-The table below illustrates how different sections of the API could be opened up to support levels of sharing between a hub and a client (such as a user in a trusted Workspace).
+A data provider may be an existing data repository or platform, or groups managing research data at their institutions. They have complex and varying data governance constraints and technical capabiliities which means that contributing data to research projects or more data sharing in a network may be difficult. 
 
-| Mode     | Metadata                     | Selection & Filtering of record-level data          | Federated compute on record level data.                |
-|:---------|:-----------------------------|:----------------------------------------------------|:-------------------------------------------------------|
-| Level 0  | Can be queried and retrieved | Can be queried remotely and transferred to a client | Federation not required, computation happens at client |
-| Level 1  | Can be queried and retrieved | Can be queried remotely and transferred to a client | Federation not required, computation happens at client |
-| Level 2  | Can be queried and retrieved | Not permitted                                       | Containerised computations can be executed remotely with<br>selection query input, approved results returned  |
+The Common API approach allows data providers to choose how they join a collaboration network.
 
-Features:
+- Level 0: transferring data directly for hosting to a trusted research environment (TRE)
+- Level 1: providing remote access to data
+- Level 2: providing remote computation on data held at source
 
-- The API is defined in an [Open API specification](api/common_api.yml)
-- API endpoints should be authenticated using OAuth tokens (out of band for this version)
-- Selections are defined in [GraphQL](https://graphql.org/) as an abstraction over querying
+Level 0 is provided by a Trusted Research Environment (TRE), while data providers must implement Level 1 or Level 2 using their own infrastructure.
 
-Details of each endpoint:
+Data providers are often in multiple collaborations at the same time. Investment in a Level 1 and Level 2 implementation can be repurposed for more than one network.
+        </td>
+        <td valign="top">
+**For Data users**
+
+A researcher or group of researchers working with multiple data sources have to navigate varying access mechanisms and APIs. By working in a network with data providers that implement the Common API, they can use their favourite tools to query, compute and analyse data in a consistent and efficient way. 
+
+The Common API allows users to:
+
+- Find data and detailed metadata about available data sources
+- Define selections and filters on data
+- Retrieve record level data (Level 1) or compute over record level data using containerised scripts (Level 2) 
+
+Currently the API is geared at users within a research team who can program. We expect in time that graphical user interfaces will be built or adapted that take advantage of the standard and reach a wider audience more directly.
+        </td>
+    </tr>
+</table>
+
+## Partners
+
+The Common API is an open source co-development between a number of partner organisations
+
+[![ADDI logo](./doc/addi-logo.png "ADDI logo")](https://www.alzheimersdata.org/)
+&nbsp;&nbsp;&nbsp;&nbsp;
+[![ICODA Research logo](./doc/icoda-research-logo.png "ICODA Research Logo")](https://www.icoda-research.org) 
+&nbsp;&nbsp;&nbsp;&nbsp;
+[![HDR UK logo](./doc/hdruk-logo.png "HDR UK Logo")](https://www.hdruk.ac.uk) 
+
+[![Aridhia DRE logo](./doc/aridhia-dre-logo.png "Aridhia DRE Logo")](https://www.aridhia.com) 
+
+## Acknowledgments
+
+The Common API gratefully builds on work from standardisation communities:  
+
+- [World Wide Web Consortium (W3C)](https://www.w3.org/)
+- [GraphQL Foundation](https://foundation.graphql.org/)
+- [Global Alliance for Genomics and Health (GA4GH)](https://www.ga4gh.org/)
+- [IETF](https://www.ietf.org/) OAuth Working Group - see https://oauth.net/2/
+
+## Contributing
+
+The code is licensed under the [Mozilla Public License 2.0](https://www.mozilla.org/en-US/MPL/2.0/) see [LICENSE](./LICENSE). 
+
+The project was [originally](./doc/Origins.md) part of an international collaboration on sharing data in clinical research. We now welcome contributions from a wider community. As more organisations are joining the effort, a new governance process will be established. In the meantime, please contact the [maintainers of the repository](mailto:info@fds-api.org).
 
-|Endpoint                                             |HTTP   |Summary                                                    |
-|:----------------------------------------------------|:------|:----------------------------------------------------------|
-|`/datasets`                                          |`GET`  |Get a list of available datasets. Shows the list of all datasets available for querying. |
-|`/datasets/{datasetid}`                              |`GET`  |Get Catalogue entry (metadata) and Dictionaries (field descriptions) for dataset. Returns the catalogue metadata and a list of field descriptions for a specified dataset (by dataset ID). |
-|`/datasets/{datasetid}/catalogue`                    |`GET`  |Get Catalogue entry (metadata) for dataset. Returns the catalogue metadata for a specified dataset (by dataset ID). |
-|`/datasets/{datasetid}/dictionaries`                 |`GET`  |Get Dictionaries (field descriptions) for dataset. Returns a list of field descriptions for each table within a specified dataset (by dataset ID). |
-|`/datasets/{datasetid}/dictionaries/{tableid}`       |`GET`  |Get a single dataset Dictionary for a specified table. Returns a set field descriptions for the specified table (by table ID) within a specified dataset (by dataset ID). |
-|`/selection/validate`                                |`POST` |Validate a given selection query. With a simple GraphQL query, check whether the query is valid and corresponds to real fields at this location.  |
-|`/selection/beacon`                                  |`POST` |Get a Beacon (T/F) for a specified data selection. With a simple Graph QL query, check which locations contain data relevant to a specific query. |
-|`/selection/select`                                  |`POST` |Perform a selection operation on a dataset. With a simple Graph QL query, returns the full selection of data in a JSON or .csv format. |
-|`/selection/preview`                                 |`POST` |Preview the results of a selection operation on a dataset. With a simple Graph QL query, returns a small sample of the selection in a JSON or .csv format.  |
-|`/selection/profile`                                 |`POST` |Get a profile of a selection operation on a dataset. Returns a set of metrics for the given selection operation.  |
-|`/health_check`                                      |`GET` |Get a health check of the service. |

VERSION

@@ -0,0 +1 @@
+1.1.0-alpha