From 1b72bafdc2a6c062f34f0bcd13d45a02c71ccccc Mon Sep 17 00:00:00 2001 From: oleg parkhomenko Date: Fri, 14 Nov 2025 18:41:13 +0400 Subject: [PATCH 1/9] template integration --- openapi/v1/integrationUser.yaml | 17 +- ...ionCurator.yaml => integration{Role}.yaml} | 451 +++++++++++------- 2 files changed, 289 insertions(+), 179 deletions(-) rename openapi/v1/{integrationCurator.yaml => integration{Role}.yaml} (96%) diff --git a/openapi/v1/integrationUser.yaml b/openapi/v1/integrationUser.yaml index 8944dea1..b99afbc8 100644 --- a/openapi/v1/integrationUser.yaml +++ b/openapi/v1/integrationUser.yaml @@ -7,13 +7,12 @@ info: To try out calls in this swagger page: - 1. Click the 'Authorize' button below to enter your API token - 2. Scroll to the 'Parameters' section for the method you wish to try out and click the 'Try it out' button - 3. Enter parameter values that you wish to try - 4. Scroll to the bottom of the Parameters section and click the 'Execute' bar that appears + 1. Click the 'Authorize' button below to enter your API token + 2. Scroll to the 'Parameters' section for the method you wish to try out and click the 'Try it out' button + 3. Enter parameter values that you wish to try + 4. Scroll to the bottom of the Parameters section and click the 'Execute' bar that appears - - The server response will be in the section that follows. + The server response will be in the section that follows. title: ODM Integration API version: default-released tags: @@ -3820,7 +3819,7 @@ paths: operationId: omicsSearchStreamedExpressionDataAsUser parameters: - description: | - Filter by sample metadata (key-value metadata pair(s)). E.g.`"Species or strain"="Homo sapiens"` + Filter by sample metadata (key-value metadata pair(s)). E.g. `"Species or strain"="Homo sapiens"` in: query name: sampleFilter schema: @@ -5735,10 +5734,10 @@ components: $ref: "./schemas/integration/FindObjectsResponse.yaml" ObjectsPage: $ref: "./schemas/integration/ObjectsPage.yaml" - StudySearchInfo: - $ref: "./schemas/integration/StudySearchInfo.yaml" ResponseFormat: $ref: "./schemas/common/ResponseFormat.yaml" + StudySearchInfo: + $ref: "./schemas/integration/StudySearchInfo.yaml" MetainfoKeyForSummary: $ref: "./schemas/integration/MetainfoKeyForSummary.yaml" FilterOptionGroup: diff --git a/openapi/v1/integrationCurator.yaml b/openapi/v1/integration{Role}.yaml similarity index 96% rename from openapi/v1/integrationCurator.yaml rename to openapi/v1/integration{Role}.yaml index 66b7b0f2..a9bfab1d 100644 --- a/openapi/v1/integrationCurator.yaml +++ b/openapi/v1/integration{Role}.yaml @@ -1,6 +1,9 @@ openapi: 3.1.0 info: - description: | + description: |- + ##{Role=Curator} + This swagger page describes the integrationUser APIs for ODM. These are typically used to find and retrieve study, sample and processed (signal) data and metadata for a given query. + ## end {Role=User} Before carrying out any API calls you will need an API token. API tokens can be obtained under your profile within the Genestack software. To try out calls in this swagger page: @@ -14,25 +17,25 @@ info: title: ODM Integration API version: default-released tags: -- name: Cell integration as Curator -- name: Expression integration as Curator -- name: Files integration as Curator -- name: Flow Cytometry (FACS) integration as Curator -- name: Library integration as Curator -- name: Linkage as Curator -- name: Metadata versioning as Curator -- name: Omics queries as Curator -- name: Preparation integration as Curator -- name: Sample integration as Curator -- name: Study integration as Curator +- name: Cell integration as Curator #{Role=Curator} +- name: Expression integration as {Role} +- name: Files integration as {Role} +- name: Flow Cytometry (FACS) integration as {Role} +- name: Library integration as {Role} +- name: Linkage as {Role} +- name: Metadata versioning as Curator #{Role=Curator} +- name: Omics queries as {Role} +- name: Preparation integration as {Role} +- name: Sample integration as {Role} +- name: Study integration as {Role} #{Role=Curator} - name: Validation summary as Curator -- name: Variant integration as Curator +- name: Variant integration as {Role} paths: - /api/v1/as-curator/data-types: + /api/v1/as-{role}/data-types: get: description: This endpoint is for instructional uses and can be used to get the latest list of Data Types. - operationId: getDataTypesAsCurator + operationId: getDataTypesAs{Role} responses: "200": content: @@ -62,12 +65,12 @@ paths: - Genestack-API-Token: [] summary: Lists all available data types. tags: - - Linkage as Curator - /api/v1/as-curator/data-types/links: + - Linkage as {Role} + /api/v1/as-{role}/data-types/links: get: description: "This endpoint should be used for instructional needs, and can\ \ be used in order to get the links between the Data Types." - operationId: getDataTypesLinksAsCurator + operationId: getDataTypesLinksAs{Role} parameters: - description: Return only links with the specified data type. in: query @@ -104,8 +107,8 @@ paths: summary: List all possible links between data types that match the specified criteria. tags: - - Linkage as Curator - /api/v1/as-curator/integration/link/expression/by/library/{id}: + - Linkage as {Role} + /api/v1/as-{role}/integration/link/expression/by/library/{id}: get: description: |+ ## Versioning @@ -123,7 +126,7 @@ paths: ## Paging For performance reasons this endpoint returns results in "pages" of limited size. In order to retrieve all matching results the client needs to request multiple pages starting from an offset to the first result. You can do this using the pageOffset query parameter. A value of 0 (the default) instructs the server to return the first page of results, 100 would return a page of results starting from the 101st result and so on. To retrieve all results, iterate through pages using `pageOffset` values of `n * pageLimit` until a page returns fewer results than the page limit, which indicates there are no more results. - operationId: getExpressionByLibraryAsCurator + operationId: getExpressionByLibraryAs{Role} parameters: - description: Supply this parameter with the value `term_id` as part of the query to return extended information including IDs for values and dictionaries. @@ -203,8 +206,8 @@ paths: - Genestack-API-Token: [] summary: Retrieve expression run-level data by querying related library ID (accession) tags: - - Expression integration as Curator - /api/v1/as-curator/integration/link/expression/by/preparation/{id}: + - Expression integration as {Role} + /api/v1/as-{role}/integration/link/expression/by/preparation/{id}: get: description: |+ ## Versioning @@ -303,8 +306,8 @@ paths: summary: Retrieve expression run-level data by querying related preparation ID (accession) tags: - - Expression integration as Curator - /api/v1/as-curator/integration/link/expression/by/sample/{id}: + - Expression integration as {role} + /api/v1/as-{role}/integration/link/expression/by/sample/{id}: get: description: |+ ## Versioning @@ -322,7 +325,7 @@ paths: ## Paging For performance reasons this endpoint returns results in "pages" of limited size. In order to retrieve all matching results the client needs to request multiple pages starting from an offset to the first result. You can do this using the pageOffset query parameter. A value of 0 (the default) instructs the server to return the first page of results, 100 would return a page of results starting from the 101st result and so on. To retrieve all results, iterate through pages using `pageOffset` values of `n * pageLimit` until a page returns fewer results than the page limit, which indicates there are no more results. - operationId: getExpressionBySampleAsCurator + operationId: getExpressionBySampleAs{Role} parameters: - description: Supply this parameter with the value `term_id` as part of the query to return extended information including IDs for values and dictionaries. @@ -402,8 +405,8 @@ paths: - Genestack-API-Token: [] summary: Retrieve expression run-level data by querying related sample ID (accession) tags: - - Expression integration as Curator - /api/v1/as-curator/integration/link/expression/group/by/study/{id}: + - Expression integration as {Role} + /api/v1/as-{role}/integration/link/expression/group/by/study/{id}: get: description: |+ ## Versioning @@ -418,7 +421,7 @@ paths: Rules for multiple CHAIN_IDs can be supplied to the parameter using the ; separator. - operationId: getExpressionGroupsByStudyAsCurator + operationId: getExpressionGroupsByStudyAs{Role} parameters: - description: Supply this parameter with the value `term_id` as part of the query to return extended information including IDs for values and dictionaries. @@ -481,7 +484,8 @@ paths: - Genestack-API-Token: [] summary: Retrieve group metadata by querying study ID (accession) tags: - - Expression integration as Curator + - Expression integration as {Role} +##{Role=Curator} ? /api/v1/as-curator/integration/link/expression/group/{sourceId}/to/cell/group/{targetId} : post: description: |- @@ -813,13 +817,14 @@ paths: sample objects tags: - Expression integration as Curator - /api/v1/as-curator/integration/link/expression/run-to-libraries/by/group/{id}: +## end {Role=Curator} + /api/v1/as-{role}/integration/link/expression/run-to-libraries/by/group/{id}: get: description: |+ ## Paging For performance reasons this endpoint returns results in "pages" of limited size. In order to retrieve all matching results the client needs to request multiple pages starting from an offset to the first result. You can do this using the pageOffset query parameter. A value of 0 (the default) instructs the server to return the first page of results, 100 would return a page of results starting from the 101st result and so on. To retrieve all results, iterate through pages using `pageOffset` values of `n * pageLimit` until a page returns fewer results than the page limit, which indicates there are no more results. - operationId: getExpressionRunToLibraryPairsAsCurator + operationId: getExpressionRunToLibraryPairsAs{Role} parameters: - description: Unique identifier (accession) of the object. in: path @@ -872,14 +877,14 @@ paths: summary: "Retrieve run-library pairs by group id. Pagination is based on unique\ \ runs, not unique pairs." tags: - - Expression integration as Curator - /api/v1/as-curator/integration/link/expression/run-to-preparations/by/group/{id}: + - Expression integration as {Role} + /api/v1/as-{role}/integration/link/expression/run-to-preparations/by/group/{id}: get: description: |+ ## Paging For performance reasons this endpoint returns results in "pages" of limited size. In order to retrieve all matching results the client needs to request multiple pages starting from an offset to the first result. You can do this using the pageOffset query parameter. A value of 0 (the default) instructs the server to return the first page of results, 100 would return a page of results starting from the 101st result and so on. To retrieve all results, iterate through pages using `pageOffset` values of `n * pageLimit` until a page returns fewer results than the page limit, which indicates there are no more results. - operationId: getExpressionRunToPreparationPairsAsCurator + operationId: getExpressionRunToPreparationPairsAs{Role} parameters: - description: Unique identifier (accession) of the object. in: path @@ -932,14 +937,14 @@ paths: summary: "Retrieve run-preparation pairs by group id. Pagination is based on\ \ unique runs, not unique pairs." tags: - - Expression integration as Curator - /api/v1/as-curator/integration/link/expression/run-to-samples/by/group/{id}: + - Expression integration as {Role} + /api/v1/as-{role}/integration/link/expression/run-to-samples/by/group/{id}: get: description: |+ ## Paging For performance reasons this endpoint returns results in "pages" of limited size. In order to retrieve all matching results the client needs to request multiple pages starting from an offset to the first result. You can do this using the pageOffset query parameter. A value of 0 (the default) instructs the server to return the first page of results, 100 would return a page of results starting from the 101st result and so on. To retrieve all results, iterate through pages using `pageOffset` values of `n * pageLimit` until a page returns fewer results than the page limit, which indicates there are no more results. - operationId: getExpressionRunToSamplePairsAsCurator + operationId: getExpressionRunToSamplePairsAs{Role} parameters: - description: Unique identifier (accession) of the object. in: path @@ -992,7 +997,8 @@ paths: summary: "Retrieve run-sample pairs by group id. Pagination is based on unique\ \ runs, not unique pairs." tags: - - Expression integration as Curator + - Expression integration as {Role} +##{Role=Curator} /api/v1/as-curator/integration/link/expression/{sourceId}/to/library/{targetId}: delete: description: Delete link between an expression object and a library @@ -1210,7 +1216,7 @@ paths: An expression object can be linked to one object only. If an expression object is already linked to another object, this link will be deleted and a new link with the specified object will be created. Expression objects of the same group can only be linked to objects of the same study. - operationId: createExpressionSampleLinkAsCurator + operationId: createExpressionSampleLinkAs{Role} parameters: - description: The ID (accession) of the run-level object (corresponding to the column in a VCG/GCT file) @@ -1248,7 +1254,8 @@ paths: summary: Create a link between an expression object and a sample tags: - Expression integration as Curator - /api/v1/as-curator/integration/link/flow-cytometry/by/sample/{id}: +## end {Role=Curator} + /api/v1/as-{role}/integration/link/flow-cytometry/by/sample/{id}: get: description: |+ ## Versioning @@ -1266,7 +1273,7 @@ paths: ## Paging For performance reasons this endpoint returns results in "pages" of limited size. In order to retrieve all matching results the client needs to request multiple pages starting from an offset to the first result. You can do this using the pageOffset query parameter. A value of 0 (the default) instructs the server to return the first page of results, 100 would return a page of results starting from the 101st result and so on. To retrieve all results, iterate through pages using `pageOffset` values of `n * pageLimit` until a page returns fewer results than the page limit, which indicates there are no more results. - operationId: getFlowCytometryBySampleAsCurator + operationId: getFlowCytometryBySampleAs{Role} parameters: - description: Supply this parameter with the value `term_id` as part of the query to return extended information including IDs for values and dictionaries. @@ -1347,8 +1354,8 @@ paths: summary: Retrieve flow cytometry run-level data by querying related sample ID (accession) tags: - - Flow Cytometry (FACS) integration as Curator - /api/v1/as-curator/integration/link/flow-cytometry/group/by/study/{id}: + - Flow Cytometry (FACS) integration as {Role} + /api/v1/as-{role}/integration/link/flow-cytometry/group/by/study/{id}: get: description: |+ ## Versioning @@ -1363,7 +1370,7 @@ paths: Rules for multiple CHAIN_IDs can be supplied to the parameter using the ; separator. - operationId: getFlowCytometryGroupsByStudyAsCurator + operationId: getFlowCytometryGroupsByStudyAs{Role} parameters: - description: Supply this parameter with the value `term_id` as part of the query to return extended information including IDs for values and dictionaries. @@ -1426,7 +1433,8 @@ paths: - Genestack-API-Token: [] summary: Retrieve group metadata by querying study ID (accession) tags: - - Flow Cytometry (FACS) integration as Curator + - Flow Cytometry (FACS) integration as {Role} +##{Role=Curator} ? /api/v1/as-curator/integration/link/flow-cytometry/group/{sourceId}/to/sample/group/{targetId} : delete: description: Delete link between a group of flow-cytometry objects and a group @@ -1529,13 +1537,14 @@ paths: of sample objects tags: - Flow Cytometry (FACS) integration as Curator - /api/v1/as-curator/integration/link/flow-cytometry/run-to-samples/by/group/{id}: +## end {Role=Curator} + /api/v1/as-{role}/integration/link/flow-cytometry/run-to-samples/by/group/{id}: get: description: |+ ## Paging For performance reasons this endpoint returns results in "pages" of limited size. In order to retrieve all matching results the client needs to request multiple pages starting from an offset to the first result. You can do this using the pageOffset query parameter. A value of 0 (the default) instructs the server to return the first page of results, 100 would return a page of results starting from the 101st result and so on. To retrieve all results, iterate through pages using `pageOffset` values of `n * pageLimit` until a page returns fewer results than the page limit, which indicates there are no more results. - operationId: getFlowCytometryRunToSamplePairsAsCurator + operationId: getFlowCytometryRunToSamplePairsAs{Role} parameters: - description: Unique identifier (accession) of the object. in: path @@ -1588,7 +1597,8 @@ paths: summary: "Retrieve run-sample pairs by group id. Pagination is based on unique\ \ runs, not unique pairs." tags: - - Flow Cytometry (FACS) integration as Curator + - Flow Cytometry (FACS) integration as {Role} +##{Role=Curator} /api/v1/as-curator/integration/link/flow-cytometry/{sourceId}/to/sample/{targetId}: delete: description: Delete link between a flow-cytometry object and a sample @@ -1672,7 +1682,8 @@ paths: summary: Create a link between a flow-cytometry object and a sample tags: - Flow Cytometry (FACS) integration as Curator - /api/v1/as-curator/integration/link/libraries/by/samples: +## end {Role=Curator} + /api/v1/as-{role}/integration/link/libraries/by/samples: get: description: |+ Retrieve library metadata objects whose linked sample metadata matches all supplied conditions. @@ -1713,7 +1724,7 @@ paths: ## Paging For performance reasons this endpoint returns results in "pages" of limited size. In order to retrieve all matching results the client needs to request multiple pages starting from an offset to the first result. You can do this using the pageOffset query parameter. A value of 0 (the default) instructs the server to return the first page of results, 100 would return a page of results starting from the 101st result and so on. To retrieve all results, iterate through pages using `pageOffset` values of `n * pageLimit` until a page returns fewer results than the page limit, which indicates there are no more results. - operationId: getLibrariesBySamplesAsCurator + operationId: getLibrariesBySamplesAs{Role} parameters: - description: Supply this parameter with the value `term_id` as part of the query to return extended information including IDs for values and dictionaries. @@ -1801,8 +1812,8 @@ paths: - Genestack-API-Token: [] summary: Retrieve library metadata by querying related samples tags: - - Library integration as Curator - /api/v1/as-curator/integration/link/library/by/sample/{id}: + - Library integration as {Role} + /api/v1/as-{role}/integration/link/library/by/sample/{id}: get: operationId: getLibraryBySampleAsCurator parameters: @@ -1865,10 +1876,10 @@ paths: - Genestack-API-Token: [] summary: Retrieve library metadata by querying related sample ID (accession) tags: - - Library integration as Curator - /api/v1/as-curator/integration/link/library/group/by/study/{id}: + - Library integration as {Role} + /api/v1/as-{role}/integration/link/library/group/by/study/{id}: get: - operationId: getLibraryGroupsByStudyAsCurator + operationId: getLibraryGroupsByStudyAs{Role} parameters: - description: Supply this parameter with the value `term_id` as part of the query to return extended information including IDs for values and dictionaries. @@ -1909,7 +1920,8 @@ paths: - Genestack-API-Token: [] summary: Retrieve group metadata by querying study ID (accession) tags: - - Library integration as Curator + - Library integration as {Role} +##{Role=Curator} /api/v1/as-curator/integration/link/library/group/{sourceId}/to/sample/group/{targetId}: delete: description: Delete links between samples and libraries related to the specified @@ -1994,13 +2006,14 @@ paths: summary: Create links between samples and libraries tags: - Library integration as Curator - /api/v1/as-curator/integration/link/library/libraries-to-samples/by/group/{id}: +## end {Role=Curator} + /api/v1/as-{role}/integration/link/library/libraries-to-samples/by/group/{id}: get: description: |+ ## Paging For performance reasons this endpoint returns results in "pages" of limited size. In order to retrieve all matching results the client needs to request multiple pages starting from an offset to the first result. You can do this using the pageOffset query parameter. A value of 0 (the default) instructs the server to return the first page of results, 100 would return a page of results starting from the 101st result and so on. To retrieve all results, iterate through pages using `pageOffset` values of `n * pageLimit` until a page returns fewer results than the page limit, which indicates there are no more results. - operationId: getLibraryLinksToSamplesAsCurator + operationId: getLibraryLinksToSamplesAs{Role} parameters: - description: Unique identifier (accession) of the object. in: path @@ -2053,7 +2066,8 @@ paths: summary: "Retrieve library-samples pairs by group id. Pagination is based on\ \ unique libraries, not unique pairs." tags: - - Library integration as Curator + - Library integration as {Role} +##{Role=Curator} /api/v1/as-curator/integration/link/library/{sourceId}/to/sample/{targetId}: delete: description: Delete a link between a library and a sample @@ -2136,9 +2150,10 @@ paths: summary: Create a link between a library and a sample tags: - Library integration as Curator - /api/v1/as-curator/integration/link/preparation/by/sample/{id}: +## end {Role=Curator} + /api/v1/as-{role}/integration/link/preparation/by/sample/{id}: get: - operationId: getPreparationBySampleAsCurator + operationId: getPreparationBySampleAs{Role} parameters: - description: Supply this parameter with the value `term_id` as part of the query to return extended information including IDs for values and dictionaries. @@ -2199,10 +2214,10 @@ paths: - Genestack-API-Token: [] summary: Retrieve preparation metadata by querying related sample ID (accession) tags: - - Preparation integration as Curator - /api/v1/as-curator/integration/link/preparation/group/by/study/{id}: + - Preparation integration as {Role} + /api/v1/as-{role}/integration/link/preparation/group/by/study/{id}: get: - operationId: getPreparationGroupsByStudyAsCurator + operationId: getPreparationGroupsByStudyAs{Role} parameters: - description: Supply this parameter with the value `term_id` as part of the query to return extended information including IDs for values and dictionaries. @@ -2243,7 +2258,8 @@ paths: - Genestack-API-Token: [] summary: Retrieve group metadata by querying study ID (accession) tags: - - Preparation integration as Curator + - Preparation integration as {Role} +##{Role=Curator} ? /api/v1/as-curator/integration/link/preparation/group/{sourceId}/to/sample/group/{targetId} : delete: description: Delete links between samples and preparations related to the specified @@ -2328,13 +2344,14 @@ paths: summary: Create links between samples and preparations tags: - Preparation integration as Curator - /api/v1/as-curator/integration/link/preparation/preparations-to-samples/by/group/{id}: +## end {Role=Curator} + /api/v1/as-{role}/integration/link/preparation/preparations-to-samples/by/group/{id}: get: description: |+ ## Paging For performance reasons this endpoint returns results in "pages" of limited size. In order to retrieve all matching results the client needs to request multiple pages starting from an offset to the first result. You can do this using the pageOffset query parameter. A value of 0 (the default) instructs the server to return the first page of results, 100 would return a page of results starting from the 101st result and so on. To retrieve all results, iterate through pages using `pageOffset` values of `n * pageLimit` until a page returns fewer results than the page limit, which indicates there are no more results. - operationId: getPreparationLinksToSamplesAsCurator + operationId: getPreparationLinksToSamplesAs{Role} parameters: - description: Unique identifier (accession) of the object. in: path @@ -2387,7 +2404,8 @@ paths: summary: "Retrieve run-sample pairs by group id. Pagination is based on unique\ \ preparations, not unique pairs." tags: - - Preparation integration as Curator + - Preparation integration as {Role} +##{Role=Curator} /api/v1/as-curator/integration/link/preparation/{sourceId}/to/sample/{targetId}: delete: description: Delete a link between a preparation and a sample @@ -2470,7 +2488,8 @@ paths: summary: Create a link between a preparation and a sample tags: - Preparation integration as Curator - /api/v1/as-curator/integration/link/preparations/by/samples: +## end {Role=Curator} + /api/v1/as-{role}/integration/link/preparations/by/samples: get: description: |+ Retrieve preparation metadata objects whose linked sample metadata matches all supplied conditions. @@ -2511,7 +2530,7 @@ paths: ## Paging For performance reasons this endpoint returns results in "pages" of limited size. In order to retrieve all matching results the client needs to request multiple pages starting from an offset to the first result. You can do this using the pageOffset query parameter. A value of 0 (the default) instructs the server to return the first page of results, 100 would return a page of results starting from the 101st result and so on. To retrieve all results, iterate through pages using `pageOffset` values of `n * pageLimit` until a page returns fewer results than the page limit, which indicates there are no more results. - operationId: getPreparationsBySamplesAsCurator + operationId: getPreparationsBySamplesAs{Role} parameters: - description: Supply this parameter with the value `term_id` as part of the query to return extended information including IDs for values and dictionaries. @@ -2599,7 +2618,8 @@ paths: - Genestack-API-Token: [] summary: Retrieve preparation metadata by querying related samples tags: - - Preparation integration as Curator + - Preparation integration as {Role} +##{Role=Curator} /api/v1/as-curator/integration/link/sample/group/{sourceId}/to/study/{targetId}: delete: description: Delete link between a group of sample objects and a study @@ -2764,7 +2784,8 @@ paths: summary: Create a link between a sample and a study tags: - Sample integration as Curator - /api/v1/as-curator/integration/link/samples/by/libraries: +## end {Role=Curator} + /api/v1/as-{role}/integration/link/samples/by/libraries: get: description: |+ Retrieve sample metadata objects whose linked library metadata matches all supplied conditions. @@ -2805,7 +2826,7 @@ paths: ## Paging For performance reasons this endpoint returns results in "pages" of limited size. In order to retrieve all matching results the client needs to request multiple pages starting from an offset to the first result. You can do this using the pageOffset query parameter. A value of 0 (the default) instructs the server to return the first page of results, 100 would return a page of results starting from the 101st result and so on. To retrieve all results, iterate through pages using `pageOffset` values of `n * pageLimit` until a page returns fewer results than the page limit, which indicates there are no more results. - operationId: getSamplesByLibrariesAsCurator + operationId: getSamplesByLibrariesAs{Role} parameters: - description: Supply this parameter with the value `term_id` as part of the query to return extended information including IDs for values and dictionaries. @@ -2893,8 +2914,8 @@ paths: - Genestack-API-Token: [] summary: Retrieve sample metadata by querying related libraries tags: - - Sample integration as Curator - /api/v1/as-curator/integration/link/samples/by/preparations: + - Sample integration as {Role} + /api/v1/as-{role}/integration/link/samples/by/preparations: get: description: |+ Retrieve sample metadata objects whose linked preparation metadata matches all supplied conditions. @@ -2935,7 +2956,7 @@ paths: ## Paging For performance reasons this endpoint returns results in "pages" of limited size. In order to retrieve all matching results the client needs to request multiple pages starting from an offset to the first result. You can do this using the pageOffset query parameter. A value of 0 (the default) instructs the server to return the first page of results, 100 would return a page of results starting from the 101st result and so on. To retrieve all results, iterate through pages using `pageOffset` values of `n * pageLimit` until a page returns fewer results than the page limit, which indicates there are no more results. - operationId: getSamplesByPreparationsAsCurator + operationId: getSamplesByPreparationsAs{Role} parameters: - description: Supply this parameter with the value `term_id` as part of the query to return extended information including IDs for values and dictionaries. @@ -3024,14 +3045,14 @@ paths: - Genestack-API-Token: [] summary: Retrieve sample metadata by querying related preparations tags: - - Sample integration as Curator - /api/v1/as-curator/integration/link/samples/by/study/{id}: + - Sample integration as {Role} + /api/v1/as-{role}/integration/link/samples/by/study/{id}: get: description: |+ ## Paging For performance reasons this endpoint returns results in "pages" of limited size. In order to retrieve all matching results the client needs to request multiple pages starting from an offset to the first result. You can do this using the pageOffset query parameter. A value of 0 (the default) instructs the server to return the first page of results, 100 would return a page of results starting from the 101st result and so on. To retrieve all results, iterate through pages using `pageOffset` values of `n * pageLimit` until a page returns fewer results than the page limit, which indicates there are no more results. - operationId: getSamplesByStudyAsCurator + operationId: getSamplesByStudyAs{Role} parameters: - description: Supply this parameter with the value `term_id` as part of the query to return extended information including IDs for values and dictionaries. @@ -3103,8 +3124,8 @@ paths: - Genestack-API-Token: [] summary: Retrieve sample metadata by querying related study ID (accession) tags: - - Sample integration as Curator - /api/v1/as-curator/integration/link/studies/by/libraries: + - Sample integration as {Role} + /api/v1/as-{role}/integration/link/studies/by/libraries: get: description: |+ Retrieve study metadata objects whose linked library metadata matches all supplied conditions. @@ -3145,7 +3166,7 @@ paths: ## Paging For performance reasons this endpoint returns results in "pages" of limited size. In order to retrieve all matching results the client needs to request multiple pages starting from an offset to the first result. You can do this using the pageOffset query parameter. A value of 0 (the default) instructs the server to return the first page of results, 100 would return a page of results starting from the 101st result and so on. To retrieve all results, iterate through pages using `pageOffset` values of `n * pageLimit` until a page returns fewer results than the page limit, which indicates there are no more results. - operationId: getStudiesByLibrariesAsCurator + operationId: getStudiesByLibrariesAs{Role} parameters: - description: Supply this parameter with the value `term_id` as part of the query to return extended information including IDs for values and dictionaries. @@ -3233,8 +3254,8 @@ paths: - Genestack-API-Token: [] summary: Retrieve study metadata objects by querying related libraries tags: - - Study integration as Curator - /api/v1/as-curator/integration/link/studies/by/preparations: + - Study integration as {Role} + /api/v1/as-{role}/integration/link/studies/by/preparations: get: description: |+ Retrieve study metadata objects whose linked preparation metadata matches all supplied conditions. @@ -3275,7 +3296,7 @@ paths: ## Paging For performance reasons this endpoint returns results in "pages" of limited size. In order to retrieve all matching results the client needs to request multiple pages starting from an offset to the first result. You can do this using the pageOffset query parameter. A value of 0 (the default) instructs the server to return the first page of results, 100 would return a page of results starting from the 101st result and so on. To retrieve all results, iterate through pages using `pageOffset` values of `n * pageLimit` until a page returns fewer results than the page limit, which indicates there are no more results. - operationId: getStudiesByPreparationsAsCurator + operationId: getStudiesByPreparationsAs{Role} parameters: - description: Supply this parameter with the value `term_id` as part of the query to return extended information including IDs for values and dictionaries. @@ -3364,8 +3385,8 @@ paths: - Genestack-API-Token: [] summary: Retrieve study metadata objects by querying related preparations tags: - - Study integration as Curator - /api/v1/as-curator/integration/link/studies/by/samples: + - Study integration as {Role} + /api/v1/as-{role}/integration/link/studies/by/samples: get: description: |+ Retrieve study metadata objects whose linked sample metadata matches all supplied conditions. @@ -3406,7 +3427,7 @@ paths: ## Paging For performance reasons this endpoint returns results in "pages" of limited size. In order to retrieve all matching results the client needs to request multiple pages starting from an offset to the first result. You can do this using the pageOffset query parameter. A value of 0 (the default) instructs the server to return the first page of results, 100 would return a page of results starting from the 101st result and so on. To retrieve all results, iterate through pages using `pageOffset` values of `n * pageLimit` until a page returns fewer results than the page limit, which indicates there are no more results. - operationId: getStudiesBySamplesAsCurator + operationId: getStudiesBySamplesAs{Role} parameters: - description: Supply this parameter with the value `term_id` as part of the query to return extended information including IDs for values and dictionaries. @@ -3494,10 +3515,10 @@ paths: - Genestack-API-Token: [] summary: Retrieve study metadata objects by querying related samples tags: - - Study integration as Curator - /api/v1/as-curator/integration/link/study/by/sample/{id}: + - Study integration as {Role} + /api/v1/as-{role}/integration/link/study/by/sample/{id}: get: - operationId: getStudyBySampleAsCurator + operationId: getStudyBySampleAs{Role} parameters: - description: Supply this parameter with the value `term_id` as part of the query to return extended information including IDs for values and dictionaries. @@ -3550,8 +3571,8 @@ paths: - Genestack-API-Token: [] summary: Retrieve study metadata by querying sample ID (accession) tags: - - Study integration as Curator - /api/v1/as-curator/integration/link/studies/by/files: + - Study integration as {Role} + /api/v1/as-{role}/integration/link/studies/by/files: get: description: |+ Retrieve study metadata objects whose linked attached files metadata matches all supplied conditions. @@ -3574,7 +3595,7 @@ paths: ## Paging For performance reasons this endpoint returns results in "pages" of limited size. In order to retrieve all matching results the client needs to request multiple pages starting from an offset to the first result. You can do this using the pageOffset query parameter. A value of 0 (the default) instructs the server to return the first page of results, 100 would return a page of results starting from the 101st result and so on. To retrieve all results, iterate through pages using `pageOffset` values of `n * pageLimit` until a page returns fewer results than the page limit, which indicates there are no more results. - operationId: getStudiesByFilesAsCurator + operationId: getStudiesByFilesAs{Role} parameters: - description: Supply this parameter with the value `term_id` as part of the query to return extended information including IDs for values and dictionaries. @@ -3650,10 +3671,10 @@ paths: - Genestack-API-Token: [] summary: Retrieve study metadata objects by querying related attachment files tags: - - Study integration as Curator - /api/v1/as-curator/integration/link/study/by/file/{id}: + - Study integration as {Role} + /api/v1/as-{role}/integration/link/study/by/file/{id}: get: - operationId: getStudyByFileAsCurator + operationId: getStudyByFileAs{Role} parameters: - description: Supply this parameter with the value `term_id` as part of the query to return extended information including IDs for values and dictionaries. @@ -3706,8 +3727,62 @@ paths: - Genestack-API-Token: [] summary: Retrieve study metadata by querying attachment file ID (accession) tags: - - Study integration as Curator - /api/v1/as-curator/integration/link/variant/by/sample/{id}: + - Study integration as User + /api/v1/as-user/integration/fulltext/search/studies: + post: + description: |- + Find studies and retrieve their data using full-text search or facet search by metadata of study itself or child object (samples, libraries, preparations, signal groups). Only studies available to that users are returned. + + The endpoint returns: + - a list of studies with their metadata summary; + - a list of filter objects with counts; filter list is the same for all users in an and can be configured in “Study Browser” application via "Configure facets" (by a user with corresponding permission); for each filter object, only the first 5 most popular facets are returned, the facts are sorted by the count value in descending order; only studies available to user are counted. + + Filter attributes for fulltext search: + - `"type": "FULL_TEXT"` + - `"match"` + - `"mode"` + + For details on two latter ones, see the request body model. Only one filter with `"type=": "FULL_TEXT"` can be passed in the request body. + + To filter studies via facets, the filter attributes are necessary: type = SELECT, filterOptionId. For details, use the request body model. filterOptionId can be obtained from the response body when the endpoint is first called without filters. Multiple filters with type = SELECT can be passed in the request body. Filters within the same attribute are automatically used with the OR operator. Filters of different attributes are automatically used with the AND operator. This behaviour can not be changed. + + It is possible to call the endpoint without any filters, then all the studies available to the user are returned. + + The endpoint searches by staging version of the object metadata. + operationId: searchStudiesByFilterAsUser + requestBody: + content: + application/json: + schema: + $ref: "#/components/schemas/SearchStudyRequest" + required: true + responses: + "200": + content: + application/json: + schema: + $ref: "#/components/schemas/FindObjectsResponse" + description: The request was successful. Retrieved studies and filters. + "400": + content: {} + description: Invalid request body + "401": + content: {} + description: User is not authenticated. Please supply a valid Genestack + API token in the `Genestack-API-Token` HTTP header (this token may be + obtained from the Genestack UI _Profile_ page). + "500": + content: {} + description: "An internal server error occurred. This indicates an unexpected\ + \ failure in the Genestack system, please file a bug report to support@genestack.com,\ + \ including the error details." + security: + - Genestack-API-Token: [] + summary: Find and retrieve studies by full-text or facet query + tags: + - Study integration as User + x-codegen-request-body-name: request + /api/v1/as-user/integration/link/variant/by/sample/{id}: get: description: |+ ## Versioning @@ -3725,7 +3800,7 @@ paths: ## Paging For performance reasons this endpoint returns results in "pages" of limited size. In order to retrieve all matching results the client needs to request multiple pages starting from an offset to the first result. You can do this using the pageOffset query parameter. A value of 0 (the default) instructs the server to return the first page of results, 100 would return a page of results starting from the 101st result and so on. To retrieve all results, iterate through pages using `pageOffset` values of `n * pageLimit` until a page returns fewer results than the page limit, which indicates there are no more results. - operationId: getVariantBySampleAsCurator + operationId: getVariantBySampleAs{Role} parameters: - description: Supply this parameter with the value `term_id` as part of the query to return extended information including IDs for values and dictionaries. @@ -3805,8 +3880,8 @@ paths: - Genestack-API-Token: [] summary: Retrieve variant run-level data by querying related sample ID (accession) tags: - - Variant integration as Curator - /api/v1/as-curator/integration/link/variant/group/by/study/{id}: + - Variant integration as {Role} + /api/v1/as-{role}/integration/link/variant/group/by/study/{id}: get: description: |+ ## Versioning @@ -3821,7 +3896,7 @@ paths: Rules for multiple CHAIN_IDs can be supplied to the parameter using the ; separator. - operationId: getVariantGroupsByStudyAsCurator + operationId: getVariantGroupsByStudyAs{Role} parameters: - description: Supply this parameter with the value `term_id` as part of the query to return extended information including IDs for values and dictionaries. @@ -3884,8 +3959,9 @@ paths: - Genestack-API-Token: [] summary: Retrieve group metadata by querying study ID (accession) tags: - - Variant integration as Curator - /api/v1/as-curator/integration/link/variant/group/{sourceId}/to/sample/group/{targetId}: + - Variant integration as {Role} +##{Role=Curator} + api/v1/as-curator/integration/link/variant/group/{sourceId}/to/sample/group/{targetId}: delete: description: Delete link between a group of variant objects and a group of sample objects @@ -3987,13 +4063,14 @@ paths: objects tags: - Variant integration as Curator - /api/v1/as-curator/integration/link/variant/run-to-samples/by/group/{id}: +## end {Role=Curator} + /api/v1/as-{role}/integration/link/variant/run-to-samples/by/group/{id}: get: description: |+ ## Paging For performance reasons this endpoint returns results in "pages" of limited size. In order to retrieve all matching results the client needs to request multiple pages starting from an offset to the first result. You can do this using the pageOffset query parameter. A value of 0 (the default) instructs the server to return the first page of results, 100 would return a page of results starting from the 101st result and so on. To retrieve all results, iterate through pages using `pageOffset` values of `n * pageLimit` until a page returns fewer results than the page limit, which indicates there are no more results. - operationId: getVariantRunToSamplePairsAsCurator + operationId: getVariantRunToSamplePairsAs{Role} parameters: - description: Unique identifier (accession) of the object. in: path @@ -4046,7 +4123,8 @@ paths: summary: "Retrieve run-sample pairs by group id. Pagination is based on unique\ \ runs, not unique pairs." tags: - - Variant integration as Curator + - Variant integration as {Role} +##{Role=Curator} /api/v1/as-curator/integration/link/variant/{sourceId}/to/sample/{targetId}: delete: description: Delete link between a variant object and a sample @@ -4241,12 +4319,13 @@ paths: summary: Deletes existing links matching the specified criteria. tags: - Linkage as Curator +## end {Role=Curator} get: description: Please make sure that this endpoint should be used only for getting all links to a specific object. In case you specify both firstId and secondId an expected answer would be true for existing links and false for no link between the objects. - operationId: getLinksByParamsAsCurator + operationId: getLinksByParamsAs{Role} parameters: - description: Object ID (accession) (e.g. accession of study) in: query @@ -4310,7 +4389,8 @@ paths: - Genestack-API-Token: [] summary: Finds existing links matching the specified criteria. tags: - - Linkage as Curator + - Linkage as {Role} +##{Role=Curator} post: description: "This method should be used only in case you need to create links\ \ between 2 objects. Links are created both ways (e.g. when linking Object\ @@ -4356,12 +4436,13 @@ paths: tags: - Linkage as Curator x-codegen-request-body-name: links - /api/v1/as-curator/links/get-batch: +## end {Role=Curator} + /api/v1/as-{role}/links/get-batch: post: description: Please make sure to use that endpoint for batch calls only. You are not allowed to pass 'mixed' objects. e.g. Studies and Samples at the same time. Please always specify firstType. - operationId: getLinksByIdsAsCurator + operationId: getLinksByIdsAs{Role} requestBody: content: application/json: @@ -4395,9 +4476,9 @@ paths: summary: "Finds existing links by passing many IDs. \nPagination goes through\ \ all links matched the criteria." tags: - - Linkage as Curator + - Linkage as {Role} x-codegen-request-body-name: request - /api/v1/as-curator/omics/cells: + /api/v1/as-{role}/omics/cells: get: description: |- Retrieve cell objects whose linked data matches all supplied conditions. @@ -4423,7 +4504,7 @@ paths: ## Paging For performance reasons this endpoint returns results in "pages" of limited size together with a `cursor` tag. To retrieve the next page of results please supply this `cursor` tag to resume the query from your previous result and get the next page. If there are no more results you will just retrieve an empty result. - operationId: omicsSearchCellsAsCurator + operationId: omicsSearchCellsAs{Role} parameters: - description: | Filter by study metadata (key-value metadata pair(s)). E.g. `"Study Source"=ArrayExpress` @@ -4592,8 +4673,8 @@ paths: - Genestack-API-Token: [ ] summary: Retrieve Cell objects by searching across multiple data types tags: - - Omics queries as Curator - /api/v1/as-curator/omics/cells/expression/data: + - Omics queries as {Role} + /api/v1/as-{role}/omics/cells/expression/data: get: description: |- Retrieve cell expression objects by searching across multiple metadata types. @@ -4619,7 +4700,7 @@ paths: ## Paging For performance reasons this endpoint returns results in "pages" of limited size together with a `cursor` tag. To retrieve the next page of results please supply this `cursor` tag to resume the query from your previous result and get the next page. If there are no more results you will just retrieve an empty result. - operationId: omicsSearchCellsExpressionDataAsCurator + operationId: omicsSearchCellsExpressionDataAs{Role} parameters: - description: | Filter by study metadata (key-value metadata pair(s)). E.g. `"Study Source"=ArrayExpress` @@ -4803,8 +4884,8 @@ paths: - Genestack-API-Token: [ ] summary: Retrieve cell expression objects by searching across multiple metadata types tags: - - Omics queries as Curator - /api/v1/as-curator/omics/expression/data: + - Omics queries as {Role} + /api/v1/as-{role}/omics/expression/data: get: description: "Retrieve any data objects whose linked data matches all supplied\ \ conditions.This endpoint does not support search by expression linked to Cell\ @@ -4852,7 +4933,7 @@ paths: \ this `cursor` tag to resume the query from your previous result and get\ \ the next page. To return all results iterate through pages using \ \ cursor values until the `resultsExhausted` response field is true.\n\n" - operationId: omicsSearchExpressionDataAsCurator + operationId: omicsSearchExpressionDataAs{Role} parameters: - description: Supply this parameter with the value `term_id` as part of the query to return extended information including IDs for values and dictionaries. @@ -5078,8 +5159,8 @@ paths: - Genestack-API-Token: [] summary: Retrieve data objects by searching across multiple data types tags: - - Omics queries as Curator - /api/v1/as-curator/omics/expression/group: + - Omics queries as {Role} + /api/v1/as-{role}/omics/expression/group: get: description: |+ Retrieve group objects whose linked data matches all supplied conditions. @@ -5120,7 +5201,7 @@ paths: ## Paging For performance reasons this endpoint returns results in "pages" of limited size together with a cursor tag. To retrieve the next page of results please supply this cursor tag to resume the query from your previous result and get the next page. If there are no more results you will just retrieve an empty result. To return all results iterate through pages using cursor values until the `resultsExhausted` response field is true. - operationId: omicsSearchExpressionGroupsAsCurator + operationId: omicsSearchExpressionGroupsAs{Role} parameters: - description: Supply this parameter with the value `term_id` as part of the query to return extended information including IDs for values and dictionaries. @@ -5346,10 +5427,34 @@ paths: - Genestack-API-Token: [] summary: Retrieve group objects by searching across multiple data types tags: - - Omics queries as Curator - /api/v1/as-curator/omics/expression/streamed-data: + - Omics queries as {Role} + /api/v1/as-{role}/omics/expression/streamed-data: get: description: |+ + ##{Role=User} + "Stream data from a given group for a tabular file that matches\ + \ a sample/library/preparations query/filter. If no query/filters are supplied\ + \ all expression data is returned. If a metadata filter is specified, this\ + \ endpoint will only return expression data that is associated with a sample\ + \ via the Sample Source ID attribute.\n## Conditions\nIt is possible to supply\ + \ conditions for:\n\n1. Samples (full-text or metadata key-value pair)\n2.\ + \ Libraries (full-text or metadata key-value pair)\n3. Preparations (full-text\ + \ or metadata key-value pair)\n## Metadata full-text queries\nSingle words\ + \ can be supplied as is; otherwise, use speech marks (`\"`) to quote queries\ + \ that include whitespace. Speech marks and backslash characters in the query\ + \ need to be escaped with a backslash (`\\`).\n\n## Metadata filters\nMetadata\ + \ filters are key-value pairs joined by an operator. The `=` operator matches\ + \ literal values/string. The `!=` operator matches anything except the literal\ + \ value/string. The `<` or `>` operators match numerical results that are\ + \ less or greater than the supplied value. Strings containing whitespace need\ + \ to be quoted with (`\"`).\n\n## Combinations\nMetadata queries/filters for\ + \ the same parameter can be combined with `&&`, `AND`, `||` and `OR` operators,\ + \ using white-space to separate out the terms and operators. Parentheses `(\ + \ )` can be used for complex expressions.\n \n\n## Error Handling\n In case\ + \ of unexpected internal error during data retrieval, the last line of the\ + \ body will contain an error message, prefixed by the `#` character \n\n" + ##{Role=User} + ##{Role=Curator} Stream data from a given group for a tabular file that matches a sample/library/preparations query/filter. If no query/filters are supplied all expression data is returned. If a metadata filter is specified, this endpoint will only return expression data that is associated with a sample via the Sample Source ID attribute. ## Conditions It is possible to supply conditions for: @@ -5365,8 +5470,8 @@ paths: ## Combinations Metadata queries/filters for the same parameter can be combined with `&&`, `AND`, `||` and `OR` operators, using white-space to separate out the terms and operators. Parentheses `( )` can be used for complex expressions. - - operationId: omicsSearchStreamedExpressionDataAsCurator + ## end {Role=Curator} + operationId: omicsSearchStreamedExpressionDataAs{Role} parameters: - description: | Filter by sample metadata (key-value metadata pair(s)). E.g. `"Species or strain"="Homo sapiens"` @@ -5524,8 +5629,8 @@ paths: - Genestack-API-Token: [] summary: Stream data from a given tabular file tags: - - Omics queries as Curator - /api/v1/as-curator/omics/flow-cytometry/data: + - Omics queries as {Role} + /api/v1/as-{role}/omics/flow-cytometry/data: get: description: |+ Retrieve flow cytometry data objects whose linked data matches all supplied conditions. @@ -5568,7 +5673,7 @@ paths: ## Paging For performance reasons this endpoint returns results in "pages" of limited size together with a cursor tag. To retrieve the next page of results please supply this cursor tag to resume the query from your previous result and get the next page. If there are no more results you will just retrieve an empty result. To return all results iterate through pages using cursor values until the `resultsExhausted` response field is true. - operationId: omicsSearchFlowCytometryDataAsCurator + operationId: omicsSearchFlowCytometryDataAs{Role} parameters: - description: Supply this parameter with the value `term_id` as part of the query to return extended information including IDs for values and dictionaries. @@ -5795,8 +5900,8 @@ paths: summary: Retrieve flow cytometry data objects by searching across multiple data types tags: - - Omics queries as Curator - /api/v1/as-curator/omics/flow-cytometry/group: + - Omics queries as {Role} + /api/v1/as-{role}/omics/flow-cytometry/group: get: description: |+ Retrieve group objects whose linked data matches all supplied conditions. @@ -5837,7 +5942,7 @@ paths: ## Paging For performance reasons this endpoint returns results in "pages" of limited size together with a cursor tag. To retrieve the next page of results please supply this cursor tag to resume the query from your previous result and get the next page. If there are no more results you will just retrieve an empty result. To return all results iterate through pages using cursor values until the `resultsExhausted` response field is true. - operationId: omicsSearchFlowCytometryGroupsAsCurator + operationId: omicsSearchFlowCytometryGroupsAs{Role} parameters: - description: Supply this parameter with the value `term_id` as part of the query to return extended information including IDs for values and dictionaries. @@ -6063,8 +6168,8 @@ paths: - Genestack-API-Token: [] summary: Retrieve group objects by searching across multiple data types tags: - - Omics queries as Curator - /api/v1/as-curator/omics/samples: + - Omics queries as {Role} + /api/v1/as-{role}/omics/samples: get: description: |+ Retrieve sample metadata objects whose linked data matches all supplied conditions. @@ -6105,7 +6210,7 @@ paths: ## Paging For performance reasons this endpoint returns results in "pages" of limited size together with a cursor tag. To retrieve the next page of results please supply this cursor tag to resume the query from your previous result and get the next page. If there are no more results you will just retrieve an empty result. To return all results iterate through pages using cursor values until the `resultsExhausted` response field is true. - operationId: omicsSearchSamplesAsCurator + operationId: omicsSearchSamplesAs{Role} parameters: - description: Supply this parameter with the value `term_id` as part of the query to return extended information including IDs for values and dictionaries. @@ -6332,8 +6437,8 @@ paths: summary: Retrieve sample metadata objects by searching across multiple data types tags: - - Omics queries as Curator - /api/v1/as-curator/omics/variant/data: + - Omics queries as {Role} + /api/v1/as-{role}/omics/variant/data: get: description: |+ Retrieve variant data objects whose linked data matches all supplied conditions. @@ -6376,7 +6481,7 @@ paths: ## Paging For performance reasons this endpoint returns results in "pages" of limited size together with a cursor tag. To retrieve the next page of results please supply this cursor tag to resume the query from your previous result and get the next page. If there are no more results you will just retrieve an empty result. To return all results iterate through pages using cursor values until the `resultsExhausted` response field is true. - operationId: omicsSearchVariantDataAsCurator + operationId: omicsSearchVariantDataAs{Role} parameters: - description: Supply this parameter with the value `term_id` as part of the query to return extended information including IDs for values and dictionaries. @@ -6602,8 +6707,8 @@ paths: - Genestack-API-Token: [] summary: Retrieve variant data objects by searching across multiple data types tags: - - Omics queries as Curator - /api/v1/as-curator/omics/variant/group: + - Omics queries as {Role} + /api/v1/as-{role}/omics/variant/group: get: description: |+ Retrieve group objects whose linked data matches all supplied conditions. @@ -6644,7 +6749,7 @@ paths: ## Paging For performance reasons this endpoint returns results in "pages" of limited size together with a cursor tag. To retrieve the next page of results please supply this cursor tag to resume the query from your previous result and get the next page. If there are no more results you will just retrieve an empty result. To return all results iterate through pages using cursor values until the `resultsExhausted` response field is true. - operationId: omicsSearchVariantGroupsAsCurator + operationId: omicsSearchVariantGroupsAs{Role} parameters: - description: Supply this parameter with the value `term_id` as part of the query to return extended information including IDs for values and dictionaries. @@ -6875,8 +6980,8 @@ paths: - Genestack-API-Token: [] summary: Retrieve group objects by searching across multiple data types tags: - - Omics queries as Curator - /api/v1/as-curator/omics/variant/streamed-data: + - Omics queries as {Role} + /api/v1/as-{role}/omics/variant/streamed-data: get: description: |+ Stream data from a given group for a VCF file that matches a sample query/filter. If no query/filters are supplied all variant data is returned. If a metadata filter is specified, this endpoint will only return variant data that is associated with a sample via metadata attribute. @@ -6893,7 +6998,7 @@ paths: ## Combinations Metadata queries/filters for the same parameter can be combined with `&&`, `AND`, `||` and `OR` operators, using white-space to separate out the terms and operators. Parentheses `( )` can be used for complex expressions. - operationId: omicsSearchStreamedVariantDataAsCurator + operationId: omicsSearchStreamedVariantDataAs{Role} parameters: - description: | Filter by sample metadata (key-value metadata pair(s)). E.g. `"Species or strain"="Homo sapiens"` @@ -7020,13 +7125,13 @@ paths: - Genestack-API-Token: [ ] summary: Stream data from a given VCF file tags: - - Omics queries as Curator - /api/v1/as-curator/omics/cells/analytics/cell-ratio: + - Omics queries as {Role} + /api/v1/as-{role}/omics/cells/analytics/cell-ratio: post: - operationId: cellRatioAsCurator + operationId: cellRatioAs{Role} summary: "[BETA] Compute cell ratio statistics across groups or metadata attributes in single-cell data." tags: - - "[BETA] Analytics omics queries as Curator" + - "[BETA] Analytics omics queries as {Role}" description: |+ This endpoint calculates cell ratio statistics based on single-cell metadata. @@ -7068,12 +7173,12 @@ paths: security: - Access-token: [ ] - Genestack-API-Token: [ ] - /api/v1/as-curator/omics/cells/analytics/differential-expression: + /api/v1/as-{role}/omics/cells/analytics/differential-expression: post: - operationId: differentialExpressionAsCurator + operationId: differentialExpressionAs{Role} summary: "[BETA] Perform differential gene expression analytics between case and control cell groups" tags: - - "[BETA] Analytics omics queries as Curator" + - "[BETA] Analytics omics queries as {Role}" # The descriptions below are also duplicated in the schema description, make sure to keep them in sync. description: |+ This endpoint computes differential gene expression between two specified cell groups (case vs control) within single-cell data. @@ -7122,12 +7227,12 @@ paths: security: - Access-token: [ ] - Genestack-API-Token: [ ] - /api/v1/as-curator/omics/cells/analytics/gene-summary: + /api/v1/as-{role}/omics/cells/analytics/gene-summary: post: - operationId: geneSummaryAsCurator + operationId: geneSummaryAs{Role} summary: "[BETA] Compute and retrieve descriptive statistics and visual summaries for single-cell data." tags: - - "[BETA] Analytics omics queries as Curator" + - "[BETA] Analytics omics queries as {Role}" description: |+ This endpoint provides descriptive statistical metrics for gene expression across single-cell datasets. It aggregates and summarizes expression data for each gene to help assess variability, distribution, @@ -7177,6 +7282,7 @@ paths: security: - Access-token: [ ] - Genestack-API-Token: [ ] +##{Role=Curator} /api/v1/as-curator/integration/studies/{id}/tasks/publish-versions: post: description: This endpoint publishes information from staging and creates new @@ -7257,9 +7363,10 @@ paths: summary: Retrieve validation summary by querying study ID (accession) tags: - Validation summary as Curator - /api/v1/as-curator/integration/link/files/by/study/{id}: +## end {Role=Curator} + /api/v1/as-{role}/integration/link/files/by/study/{id}: get: - operationId: getFilesByStudyAsCurator + operationId: getFilesByStudyAs{Role} parameters: - description: Unique identifier (accession) of the object. in: path @@ -7309,7 +7416,8 @@ paths: - Genestack-API-Token: [ ] summary: Retrieve file's metadata by study ID tags: - - Files integration as Curator + - Files integration as {Role} +##{Role=Curator} /api/v1/as-curator/integration/link/cell/group/{sourceId}/to/sample/group/{targetId}: post: description: |- @@ -7448,28 +7556,37 @@ paths: summary: Create links between cells and preparations tags: - Cell integration as Curator +## end {Role=Curator} components: schemas: +##{Role=Curator} AttributeInvalidValue: $ref: "./schemas/integration/AttributeInvalidValue.yaml" AttributeValidationSummary: $ref: "./schemas/integration/AttributeValidationSummary.yaml" + GroupValidationSummary: + $ref: "./schemas/integration/GroupValidationSummary.yaml" + Link: + $ref: "./schemas/integration/Link.yaml" + StudyValidationSummary: + $ref: "./schemas/integration/StudyValidationSummary.yaml" + TaskInfo: + $ref: "./schemas/tasks/TaskInfo.yaml" + ValidationError: + $ref: "./schemas/integration/ValidationError.yaml" +## end {Role=Curator} BatchOfIds: $ref: "./schemas/integration/BatchOfIds.yaml" DataItem: $ref: "./schemas/integration/DataItem.yaml" DataPresentation: $ref: "./schemas/integration/DataPresentation.yaml" - GroupValidationSummary: - $ref: "./schemas/integration/GroupValidationSummary.yaml" IMetadata: $ref: "./schemas/integration/IMetadata.yaml" IntegrationHelper: $ref: "./schemas/common/IntegrationHelper.yaml" Library: $ref: "./schemas/library/Library.yaml" - Link: - $ref: "./schemas/integration/Link.yaml" ListResponse: $ref: "./schemas/common/ListResponse.yaml" MetaResponse: @@ -7500,12 +7617,6 @@ components: $ref: "./schemas/integration/StreamingOutput.yaml" Study: $ref: "./schemas/study/Study.yaml" - StudyValidationSummary: - $ref: "./schemas/integration/StudyValidationSummary.yaml" - TaskInfo: - $ref: "./schemas/tasks/TaskInfo.yaml" - ValidationError: - $ref: "./schemas/integration/ValidationError.yaml" SearchStudyRequest: $ref: "./schemas/integration/SearchStudyRequest.yaml" AppliedFilter: From 63800dad4fe94a65836f0f65a185d691998c0f2c Mon Sep 17 00:00:00 2001 From: oleg parkhomenko Date: Fri, 14 Nov 2025 19:45:38 +0400 Subject: [PATCH 2/9] implement template task --- build.gradle.kts | 17 +- .../openapi/TemplateSpecification.kt | 120 + openapi/v1/integrationUser.yaml | 5769 ----------------- openapi/v1/integration{Role}.yaml | 16 +- 4 files changed, 141 insertions(+), 5781 deletions(-) create mode 100644 buildSrc/src/main/kotlin/com/genestack/openapi/TemplateSpecification.kt delete mode 100644 openapi/v1/integrationUser.yaml diff --git a/build.gradle.kts b/build.gradle.kts index 89132c03..dbee1d20 100644 --- a/build.gradle.kts +++ b/build.gradle.kts @@ -6,6 +6,7 @@ * actual or intended publication of such source code. */ +import com.genestack.openapi.TemplateSpecification import com.genestack.openapi.DownloadSpecification import org.openapitools.generator.gradle.plugin.tasks.GenerateTask import com.genestack.openapi.MergeSpecifications @@ -27,13 +28,19 @@ val openApiVersion: String = System.getenv("OPENAPI_VERSION") val mergedFileName = "odmApi.yaml" val mergedFilePath = "${sourceDirectory}/${mergedFileName}" -val sourceFileList = KotlinPath(sourceDirectory) - .listDirectoryEntries("*.yaml") - .sorted() - .map { layout.projectDirectory.file("${sourceDirectory}/${it.name}") } +fun specFiles(selectTemplates: Boolean = false) = KotlinPath(sourceDirectory) + .listDirectoryEntries("*.yaml") + .filter { (!selectTemplates).xor(it.name.contains("{Role}")) } + .sorted() + .map { layout.projectDirectory.file("${sourceDirectory}/${it.name}") } tasks { + val templateSpecs by registering(TemplateSpecification::class) { + inputFiles = specFiles(true) + outputDir = layout.projectDirectory.file(sourceDirectory) + } val downloadSpec by registering(DownloadSpecification::class) { + dependsOn(templateSpecs) version.set(processorsControllerVersion) registryUsername.set(System.getenv("NEXUS_USER")) registryPassword.set(System.getenv("NEXUS_PASSWORD")) @@ -43,7 +50,7 @@ tasks { } val mergeSpecifications by registering(MergeSpecifications::class) { dependsOn(downloadSpec) - inputFiles = sourceFileList + inputFiles = specFiles() outputFile = layout.projectDirectory.file(mergedFilePath) } val generateOdmApiPython by registering(GenerateTask::class) { diff --git a/buildSrc/src/main/kotlin/com/genestack/openapi/TemplateSpecification.kt b/buildSrc/src/main/kotlin/com/genestack/openapi/TemplateSpecification.kt new file mode 100644 index 00000000..c167fea3 --- /dev/null +++ b/buildSrc/src/main/kotlin/com/genestack/openapi/TemplateSpecification.kt @@ -0,0 +1,120 @@ +package com.genestack.openapi + +import org.gradle.api.DefaultTask +import org.gradle.api.file.RegularFile +import org.gradle.api.file.RegularFileProperty +import org.gradle.api.provider.ListProperty +import org.gradle.api.tasks.OutputFile +import org.gradle.api.tasks.TaskAction +import org.gradle.api.tasks.InputFiles +import org.gradle.api.tasks.OutputDirectory +import java.io.File + +import com.fasterxml.jackson.databind.ObjectMapper +import com.fasterxml.jackson.dataformat.yaml.YAMLFactory + + +abstract class TemplateSpecification : DefaultTask() { + + @get:InputFiles + abstract val inputFiles: ListProperty + + @get:OutputDirectory + abstract val outputDir: RegularFileProperty + + @TaskAction + fun template() { + inputFiles.get().map { it.asFile } + .forEach { + writeTemplated(it, "User") + writeTemplated(it, "Curator") + } + } + + private fun writeTemplated(spec: File, role: String) { + val content = spec.readText() + val outputContent = StringBuilder() + + // Role in lowercase for substitutions + val roleLowercase = role.lowercase() + + // Define regex patterns for role matching + val rolePattern = """\{Role=([^}]+)\}""".toRegex() + val sectionStartPattern = """##\s*\{Role=([^}]+)\}""".toRegex() + val sectionEndPattern = """##\s*end\s*\{Role=([^}]+)\}""".toRegex() + val lineCommentPattern = """#\{Role=([^}]+)\}""".toRegex() + + // Flag to track if we're inside a conditional section + var insideConditionalSection = false + var shouldIncludeSection = false + var sectionRole = "" + + // Process line by line + content.lineSequence().withIndex().forEach { (index, line) -> + // Check if this line is the start of a conditional section + val sectionStartMatch = sectionStartPattern.find(line) + if (sectionStartMatch != null) { + if (insideConditionalSection) { + throw IllegalStateException("Nested conditional sections are not allowed. Error in file: ${spec.name}, line ${index}") + } + + insideConditionalSection = true + sectionRole = sectionStartMatch.groupValues[1] + shouldIncludeSection = (sectionRole == role) + // Skip this marker line + return@forEach + } + + // Check if this line is the end of a conditional section + val sectionEndMatch = sectionEndPattern.find(line) + if (sectionEndMatch != null) { + if (!insideConditionalSection) { + throw IllegalStateException("Found end marker without start marker. Error in file: ${spec.name}, line ${index}") + } + + val endRole = sectionEndMatch.groupValues[1] + if (endRole != sectionRole) { + throw IllegalStateException("Mismatched roles in section markers: $sectionRole vs $endRole. Error in file: ${spec.name}, line ${index}") + } + + insideConditionalSection = false + shouldIncludeSection = false + // Skip this marker line + return@forEach + } + + // If we're inside a conditional section and shouldn't include it, skip this line + if (insideConditionalSection && !shouldIncludeSection) { + return@forEach + } + + // Handle single line conditional comments: #{Role=X} + val lineCommentMatch = lineCommentPattern.find(line) + if (lineCommentMatch != null) { + val commentRole = lineCommentMatch.groupValues[1] + if (commentRole == role) { + // Keep the line but remove the comment + val processedLine = line.replace(lineCommentPattern, "") + outputContent.appendLine(processedLine) + } + // If role doesn't match, skip this line + return@forEach + } + + // Process regular lines with substitutions + val processedLine = line.replace("{Role}", role).replace("{role}", roleLowercase) + outputContent.appendLine(processedLine) + } + + // Check if we ended with an unclosed section + if (insideConditionalSection) { + throw IllegalStateException("Unclosed conditional section for role: $sectionRole. Error in file: ${spec.name}") + } + + // Create output file with appropriate name + val outputFileName = spec.name.replace("{Role}", role) + val outputFile = File(outputDir.get().asFile, outputFileName) + outputFile.parentFile.mkdirs() + outputFile.writeText(outputContent.toString()) + } +} diff --git a/openapi/v1/integrationUser.yaml b/openapi/v1/integrationUser.yaml deleted file mode 100644 index b99afbc8..00000000 --- a/openapi/v1/integrationUser.yaml +++ /dev/null @@ -1,5769 +0,0 @@ -openapi: 3.1.0 -info: - description: |- - This swagger page describes the integrationUser APIs for ODM. These are typically used to find and retrieve study, sample and processed (signal) data and metadata for a given query. - - Before carrying out any API calls you will need an API token. API tokens can be obtained under your profile within the Genestack software. - - To try out calls in this swagger page: - - 1. Click the 'Authorize' button below to enter your API token - 2. Scroll to the 'Parameters' section for the method you wish to try out and click the 'Try it out' button - 3. Enter parameter values that you wish to try - 4. Scroll to the bottom of the Parameters section and click the 'Execute' bar that appears - - The server response will be in the section that follows. - title: ODM Integration API - version: default-released -tags: -- name: Expression integration as User -- name: Files integration as User -- name: Flow Cytometry (FACS) integration as User -- name: Library integration as User -- name: Linkage as User -- name: Omics queries as User -- name: Preparation integration as User -- name: Sample integration as User -- name: Study integration as User -- name: Variant integration as User -paths: - /api/v1/as-user/data-types: - get: - description: This endpoint is for instructional uses and can be used to get - the latest list of Data Types. - operationId: getDataTypesAsUser - responses: - "200": - content: - application/json: - schema: - items: - type: string - type: array - uniqueItems: true - description: The request was successful. The returned value is a list of - objects. - "400": - content: {} - description: Entities cannot be retrieved. - "401": - content: {} - description: |- - User is not authenticated. Please supply a valid Access Token in the `Authorization` HTTP header (e.g. Authorization: bearer [token]) - or Genestack API token in the `Genestack-API-Token` header (this token may be obtained from the Genestack UI _Profile_ page). - "500": - content: {} - description: "An internal server error occurred. This indicates an unexpected\ - \ failure in the Genestack system, please file a bug report to support@genestack.com,\ - \ including the error details." - security: - - Access-token: [] - - Genestack-API-Token: [] - summary: Lists all available data types. - tags: - - Linkage as User - /api/v1/as-user/data-types/links: - get: - description: "This endpoint should be used for instructional needs, and can\ - \ be used in order to get the links between the Data Types." - operationId: getDataTypesLinksAsUser - parameters: - - description: Return only links with the specified data type. - in: query - name: type - schema: - type: string - responses: - "200": - content: - application/json: - schema: - items: - $ref: "#/components/schemas/SourceTypePair" - type: array - uniqueItems: true - description: The request was successful. The returned value is a list of - objects. - "400": - content: {} - description: Entities cannot be retrieved. - "401": - content: {} - description: |- - User is not authenticated. Please supply a valid Access Token in the `Authorization` HTTP header (e.g. Authorization: bearer [token]) - or Genestack API token in the `Genestack-API-Token` header (this token may be obtained from the Genestack UI _Profile_ page). - "500": - content: {} - description: "An internal server error occurred. This indicates an unexpected\ - \ failure in the Genestack system, please file a bug report to support@genestack.com,\ - \ including the error details." - security: - - Access-token: [] - - Genestack-API-Token: [] - summary: List all possible links between data types that match the specified - criteria. - tags: - - Linkage as User - /api/v1/as-user/integration/link/expression/by/library/{id}: - get: - description: |+ - ## Versioning - Specific versions of omics data files (eg. GCT) can be queried via the useVersions parameter. Different versions of an omics data file are associated via their CHAIN_ID metadata value. This CHAIN_ID can be supplied to the useVersions parameter along with the version number or specific omics data file accessions to include them in the query. If nothing is supplied to the useVersions parameter then only the active version (which is usually the last one imported) is queried. This acts as a filter before the rest of the query is carried out. - - Example usage: - useVersions=* (query all versions, including those without CHAIN_IDs) - useVersions=v2 (query the second version. If there is no second version then the data file is not queried) - useVersions=v1,v0 (query the first version and any data files without CHAIN_IDs(v0) ) - useVersions=GSVC002:v3 (for omics data files with a CHAIN_ID of GSCV002 query the third version) - useVersions=GSVC002:GSF00494,GSF000496 (for omics data files with a CHAIN_ID of GSCV002 query only the specific accessions GSF00494 and GSF000496) - - Rules for multiple CHAIN_IDs can be supplied to the parameter using the ; separator. - - ## Paging - For performance reasons this endpoint returns results in "pages" of limited size. In order to retrieve all matching results the client needs to request multiple pages starting from an offset to the first result. You can do this using the pageOffset query parameter. A value of 0 (the default) instructs the server to return the first page of results, 100 would return a page of results starting from the 101st result and so on. To retrieve all results, iterate through pages using `pageOffset` values of `n * pageLimit` until a page returns fewer results than the page limit, which indicates there are no more results. - - operationId: getExpressionByLibraryAsUser - parameters: - - description: Supply this parameter with the value `term_id` as part of the - query to return extended information including IDs for values and dictionaries. - in: query - name: responseFormat - schema: - $ref: "#/components/schemas/ResponseFormat" - - description: Unique identifier (accession) of the object. - in: path - name: id - required: true - schema: - type: string - - description: Maximum number of results to return. This value must be between - 0 and 2000 (inclusive). - in: query - name: pageLimit - schema: - format: int32 - type: integer - - description: "Show the page {pageOffset+1} results from the start of the results.\ - \ E.g. 100 will show a page of results starting from the 101st result.\ - \ The default value is 0." - in: query - name: pageOffset - schema: - format: int32 - type: integer - - description: |- - Specify which versions of omics data files are used in the query. By default the active version is used. See Versioning above. Syntax: - - \* or `v` or ``:`v` or ``:`` - in: query - name: useVersions - schema: - type: string - - description: |- - The parameter defines amount of metadata attributes to return: - - 1. `minimal_data` - return metadata attributes according to the default template. - 2. `extended_data_included` - return metadata attributes according to applied template, if object doesn’t have applied template default template will be used. This is the default for User endpoints. - 3. `original_data_included` - return all metadata attributes with values and null attributes, if they are present in the applied template. This is the default for Curator endpoints. - in: query - name: returnedMetadataFields - schema: - enum: - - minimal_data - - extended_data_included - - original_data_included - type: string - responses: - "200": - content: - application/json: - schema: - $ref: "#/components/schemas/ListResponse" - text/tab-separated-values: - schema: - $ref: "#/components/schemas/ListResponse" - description: The request was successful. The returned value is a list of - objects. - "400": - content: {} - description: Entities cannot be retrieved. - "401": - content: {} - description: |- - User is not authenticated. Please supply a valid Access Token in the `Authorization` HTTP header (e.g. Authorization: bearer [token]) - or Genestack API token in the `Genestack-API-Token` header (this token may be obtained from the Genestack UI _Profile_ page). - "500": - content: {} - description: "An internal server error occurred. This indicates an unexpected\ - \ failure in the Genestack system, please file a bug report to support@genestack.com,\ - \ including the error details." - security: - - Access-token: [] - - Genestack-API-Token: [] - summary: Retrieve expression run-level data by querying related library ID (accession) - tags: - - Expression integration as User - /api/v1/as-user/integration/link/expression/by/preparation/{id}: - get: - description: |+ - ## Versioning - Specific versions of omics data files (eg. GCT) can be queried via the useVersions parameter. Different versions of an omics data file are associated via their CHAIN_ID metadata value. This CHAIN_ID can be supplied to the useVersions parameter along with the version number or specific omics data file accessions to include them in the query. If nothing is supplied to the useVersions parameter then only the active version (which is usually the last one imported) is queried. This acts as a filter before the rest of the query is carried out. - - Example usage: - useVersions=* (query all versions, including those without CHAIN_IDs) - useVersions=v2 (query the second version. If there is no second version then the data file is not queried) - useVersions=v1,v0 (query the first version and any data files without CHAIN_IDs(v0) ) - useVersions=GSVC002:v3 (for omics data files with a CHAIN_ID of GSCV002 query the third version) - useVersions=GSVC002:GSF00494,GSF000496 (for omics data files with a CHAIN_ID of GSCV002 query only the specific accessions GSF00494 and GSF000496) - - Rules for multiple CHAIN_IDs can be supplied to the parameter using the ; separator. - - ## Paging - For performance reasons this endpoint returns results in "pages" of limited size. In order to retrieve all matching results the client needs to request multiple pages starting from an offset to the first result. You can do this using the pageOffset query parameter. A value of 0 (the default) instructs the server to return the first page of results, 100 would return a page of results starting from the 101st result and so on. To retrieve all results, iterate through pages using `pageOffset` values of `n * pageLimit` until a page returns fewer results than the page limit, which indicates there are no more results. - - operationId: getExpressionByPreparationAsUser - parameters: - - description: Supply this parameter with the value `term_id` as part of the - query to return extended information including IDs for values and dictionaries. - in: query - name: responseFormat - schema: - $ref: "#/components/schemas/ResponseFormat" - - description: Unique identifier (accession) of the object. - in: path - name: id - required: true - schema: - type: string - - description: Maximum number of results to return. This value must be between - 0 and 2000 (inclusive). - in: query - name: pageLimit - schema: - format: int32 - type: integer - - description: "Show the page {pageOffset+1} results from the start of the results.\ - \ E.g. 100 will show a page of results starting from the 101st result.\ - \ The default value is 0." - in: query - name: pageOffset - schema: - format: int32 - type: integer - - description: |- - Specify which versions of omics data files are used in the query. By default the active version is used. See Versioning above. Syntax: - - \* or `v` or ``:`v` or ``:`` - in: query - name: useVersions - schema: - type: string - - description: |- - The parameter defines amount of metadata attributes to return: - - 1. `minimal_data` - return metadata attributes according to the default template. - 2. `extended_data_included` - return metadata attributes according to applied template, if object doesn’t have applied template default template will be used. This is the default for User endpoints. - 3. `original_data_included` - return all metadata attributes with values and null attributes, if they are present in the applied template. This is the default for Curator endpoints. - in: query - name: returnedMetadataFields - schema: - enum: - - minimal_data - - extended_data_included - - original_data_included - type: string - responses: - "200": - content: - application/json: - schema: - $ref: "#/components/schemas/ListResponse" - text/tab-separated-values: - schema: - $ref: "#/components/schemas/ListResponse" - description: The request was successful. The returned value is a list of - objects. - "400": - content: {} - description: Entities cannot be retrieved. - "401": - content: {} - description: |- - User is not authenticated. Please supply a valid Access Token in the `Authorization` HTTP header (e.g. Authorization: bearer [token]) - or Genestack API token in the `Genestack-API-Token` header (this token may be obtained from the Genestack UI _Profile_ page). - "500": - content: {} - description: "An internal server error occurred. This indicates an unexpected\ - \ failure in the Genestack system, please file a bug report to support@genestack.com,\ - \ including the error details." - security: - - Access-token: [] - - Genestack-API-Token: [] - summary: Retrieve expression run-level data by querying related preparation - ID (accession) - tags: - - Expression integration as User - /api/v1/as-user/integration/link/expression/by/sample/{id}: - get: - description: |+ - ## Versioning - Specific versions of omics data files (eg. GCT) can be queried via the useVersions parameter. Different versions of an omics data file are associated via their CHAIN_ID metadata value. This CHAIN_ID can be supplied to the useVersions parameter along with the version number or specific omics data file accessions to include them in the query. If nothing is supplied to the useVersions parameter then only the active version (which is usually the last one imported) is queried. This acts as a filter before the rest of the query is carried out. - - Example usage: - useVersions=* (query all versions, including those without CHAIN_IDs) - useVersions=v2 (query the second version. If there is no second version then the data file is not queried) - useVersions=v1,v0 (query the first version and any data files without CHAIN_IDs(v0) ) - useVersions=GSVC002:v3 (for omics data files with a CHAIN_ID of GSCV002 query the third version) - useVersions=GSVC002:GSF00494,GSF000496 (for omics data files with a CHAIN_ID of GSCV002 query only the specific accessions GSF00494 and GSF000496) - - Rules for multiple CHAIN_IDs can be supplied to the parameter using the ; separator. - - ## Paging - For performance reasons this endpoint returns results in "pages" of limited size. In order to retrieve all matching results the client needs to request multiple pages starting from an offset to the first result. You can do this using the pageOffset query parameter. A value of 0 (the default) instructs the server to return the first page of results, 100 would return a page of results starting from the 101st result and so on. To retrieve all results, iterate through pages using `pageOffset` values of `n * pageLimit` until a page returns fewer results than the page limit, which indicates there are no more results. - - operationId: getExpressionBySampleAsUser - parameters: - - description: Supply this parameter with the value `term_id` as part of the - query to return extended information including IDs for values and dictionaries. - in: query - name: responseFormat - schema: - $ref: "#/components/schemas/ResponseFormat" - - description: Unique identifier (accession) of the object. - in: path - name: id - required: true - schema: - type: string - - description: Maximum number of results to return. This value must be between - 0 and 2000 (inclusive). - in: query - name: pageLimit - schema: - format: int32 - type: integer - - description: "Show the page {pageOffset+1} results from the start of the results.\ - \ E.g. 100 will show a page of results starting from the 101st result.\ - \ The default value is 0." - in: query - name: pageOffset - schema: - format: int32 - type: integer - - description: |- - Specify which versions of omics data files are used in the query. By default the active version is used. See Versioning above. Syntax: - - \* or `v` or ``:`v` or ``:`` - in: query - name: useVersions - schema: - type: string - - description: |- - The parameter defines amount of metadata attributes to return: - - 1. `minimal_data` - return metadata attributes according to the default template. - 2. `extended_data_included` - return metadata attributes according to applied template, if object doesn’t have applied template default template will be used. This is the default for User endpoints. - 3. `original_data_included` - return all metadata attributes with values and null attributes, if they are present in the applied template. This is the default for Curator endpoints. - in: query - name: returnedMetadataFields - schema: - enum: - - minimal_data - - extended_data_included - - original_data_included - type: string - responses: - "200": - content: - application/json: - schema: - $ref: "#/components/schemas/ListResponse" - text/tab-separated-values: - schema: - $ref: "#/components/schemas/ListResponse" - description: The request was successful. The returned value is a list of - objects. - "400": - content: {} - description: Entities cannot be retrieved. - "401": - content: {} - description: |- - User is not authenticated. Please supply a valid Access Token in the `Authorization` HTTP header (e.g. Authorization: bearer [token]) - or Genestack API token in the `Genestack-API-Token` header (this token may be obtained from the Genestack UI _Profile_ page). - "500": - content: {} - description: "An internal server error occurred. This indicates an unexpected\ - \ failure in the Genestack system, please file a bug report to support@genestack.com,\ - \ including the error details." - security: - - Access-token: [] - - Genestack-API-Token: [] - summary: Retrieve expression run-level data by querying related sample ID (accession) - tags: - - Expression integration as User - /api/v1/as-user/integration/link/expression/group/by/study/{id}: - get: - description: |+ - ## Versioning - Specific versions of omics data files (eg. GCT) can be queried via the useVersions parameter. Different versions of an omics data file are associated via their CHAIN_ID metadata value. This CHAIN_ID can be supplied to the useVersions parameter along with the version number or specific omics data file accessions to include them in the query. If nothing is supplied to the useVersions parameter then only the active version (which is usually the last one imported) is queried. This acts as a filter before the rest of the query is carried out. - - Example usage: - useVersions=* (query all versions, including those without CHAIN_IDs) - useVersions=v2 (query the second version. If there is no second version then the data file is not queried) - useVersions=v1,v0 (query the first version and any data files without CHAIN_IDs(v0) ) - useVersions=GSVC002:v3 (for omics data files with a CHAIN_ID of GSCV002 query the third version) - useVersions=GSVC002:GSF00494,GSF000496 (for omics data files with a CHAIN_ID of GSCV002 query only the specific accessions GSF00494 and GSF000496) - - Rules for multiple CHAIN_IDs can be supplied to the parameter using the ; separator. - - operationId: getExpressionGroupsByStudyAsUser - parameters: - - description: Supply this parameter with the value `term_id` as part of the - query to return extended information including IDs for values and dictionaries. - in: query - name: responseFormat - schema: - $ref: "#/components/schemas/ResponseFormat" - - description: Unique identifier (accession) of the object. - in: path - name: id - required: true - schema: - type: string - - description: |- - Specify which versions of omics data files are used in the query. By default the active version is used. See Versioning above. Syntax: - - \* or `v` or ``:`v` or ``:`` - in: query - name: useVersions - schema: - type: string - - description: |- - The parameter defines amount of metadata attributes to return: - - 1. `minimal_data` - return metadata attributes according to the default template. - 2. `extended_data_included` - return metadata attributes according to applied template, if object doesn’t have applied template default template will be used. This is the default for User endpoints. - 3. `original_data_included` - return all metadata attributes with values and null attributes, if they are present in the applied template. This is the default for Curator endpoints. - in: query - name: returnedMetadataFields - schema: - enum: - - minimal_data - - extended_data_included - - original_data_included - type: string - responses: - "200": - content: - application/json: - schema: - items: - $ref: "#/components/schemas/MetadataWithId" - type: array - description: The request was successful. The returned value is the object. - "400": - content: {} - description: The supplied object ID is invalid. - "401": - content: {} - description: |- - User is not authenticated. Please supply a valid Access Token in the `Authorization` HTTP header (e.g. Authorization: bearer [token]) - or Genestack API token in the `Genestack-API-Token` header (this token may be obtained from the Genestack UI _Profile_ page). - "500": - content: {} - description: "An internal server error occurred. This indicates an unexpected\ - \ failure in the Genestack system, please file a bug report to support@genestack.com,\ - \ including the error details." - security: - - Access-token: [] - - Genestack-API-Token: [] - summary: Retrieve group metadata by querying study ID (accession) - tags: - - Expression integration as User - /api/v1/as-user/integration/link/expression/run-to-libraries/by/group/{id}: - get: - description: |+ - ## Paging - For performance reasons this endpoint returns results in "pages" of limited size. In order to retrieve all matching results the client needs to request multiple pages starting from an offset to the first result. You can do this using the pageOffset query parameter. A value of 0 (the default) instructs the server to return the first page of results, 100 would return a page of results starting from the 101st result and so on. To retrieve all results, iterate through pages using `pageOffset` values of `n * pageLimit` until a page returns fewer results than the page limit, which indicates there are no more results. - - operationId: getExpressionRunToLibraryPairsAsUser - parameters: - - description: Unique identifier (accession) of the object. - in: path - name: id - required: true - schema: - type: string - - description: Maximum number of results to return. This value must be between - 0 and 2000 (inclusive). - in: query - name: pageLimit - schema: - format: int32 - type: integer - - description: "Show the page {pageOffset+1} results from the start of the results.\ - \ E.g. 100 will show a page of results starting from the 101st result.\ - \ The default value is 0." - in: query - name: pageOffset - schema: - format: int32 - type: integer - responses: - "200": - content: - application/json: - schema: - $ref: "#/components/schemas/ListResponse" - description: The request was successful. The returned value is a list of - objects. - "400": - content: {} - description: Entities cannot be retrieved. - "401": - content: {} - description: |- - User is not authenticated. Please supply a valid Access Token in the `Authorization` HTTP header (e.g. Authorization: bearer [token]) - or Genestack API token in the `Genestack-API-Token` header (this token may be obtained from the Genestack UI _Profile_ page). - "404": - content: {} - description: No object exists with the given ID. - "500": - content: {} - description: "An internal server error occurred. This indicates an unexpected\ - \ failure in the Genestack system, please file a bug report to support@genestack.com,\ - \ including the error details." - security: - - Access-token: [] - - Genestack-API-Token: [] - summary: "Retrieve run-library pairs by group id. Pagination is based on unique\ - \ runs, not unique pairs." - tags: - - Expression integration as User - /api/v1/as-user/integration/link/expression/run-to-preparations/by/group/{id}: - get: - description: |+ - ## Paging - For performance reasons this endpoint returns results in "pages" of limited size. In order to retrieve all matching results the client needs to request multiple pages starting from an offset to the first result. You can do this using the pageOffset query parameter. A value of 0 (the default) instructs the server to return the first page of results, 100 would return a page of results starting from the 101st result and so on. To retrieve all results, iterate through pages using `pageOffset` values of `n * pageLimit` until a page returns fewer results than the page limit, which indicates there are no more results. - - operationId: getExpressionRunToPreparationPairsAsUser - parameters: - - description: Unique identifier (accession) of the object. - in: path - name: id - required: true - schema: - type: string - - description: Maximum number of results to return. This value must be between - 0 and 2000 (inclusive). - in: query - name: pageLimit - schema: - format: int32 - type: integer - - description: "Show the page {pageOffset+1} results from the start of the results.\ - \ E.g. 100 will show a page of results starting from the 101st result.\ - \ The default value is 0." - in: query - name: pageOffset - schema: - format: int32 - type: integer - responses: - "200": - content: - application/json: - schema: - $ref: "#/components/schemas/ListResponse" - description: The request was successful. The returned value is a list of - objects. - "400": - content: {} - description: Entities cannot be retrieved. - "401": - content: {} - description: |- - User is not authenticated. Please supply a valid Access Token in the `Authorization` HTTP header (e.g. Authorization: bearer [token]) - or Genestack API token in the `Genestack-API-Token` header (this token may be obtained from the Genestack UI _Profile_ page). - "404": - content: {} - description: No object exists with the given ID. - "500": - content: {} - description: "An internal server error occurred. This indicates an unexpected\ - \ failure in the Genestack system, please file a bug report to support@genestack.com,\ - \ including the error details." - security: - - Access-token: [] - - Genestack-API-Token: [] - summary: "Retrieve run-preparation pairs by group id. Pagination is based on\ - \ unique runs, not unique pairs." - tags: - - Expression integration as User - /api/v1/as-user/integration/link/expression/run-to-samples/by/group/{id}: - get: - description: |+ - ## Paging - For performance reasons this endpoint returns results in "pages" of limited size. In order to retrieve all matching results the client needs to request multiple pages starting from an offset to the first result. You can do this using the pageOffset query parameter. A value of 0 (the default) instructs the server to return the first page of results, 100 would return a page of results starting from the 101st result and so on. To retrieve all results, iterate through pages using `pageOffset` values of `n * pageLimit` until a page returns fewer results than the page limit, which indicates there are no more results. - - operationId: getExpressionRunToSamplePairsAsUser - parameters: - - description: Unique identifier (accession) of the object. - in: path - name: id - required: true - schema: - type: string - - description: Maximum number of results to return. This value must be between - 0 and 2000 (inclusive). - in: query - name: pageLimit - schema: - format: int32 - type: integer - - description: "Show the page {pageOffset+1} results from the start of the results.\ - \ E.g. 100 will show a page of results starting from the 101st result.\ - \ The default value is 0." - in: query - name: pageOffset - schema: - format: int32 - type: integer - responses: - "200": - content: - application/json: - schema: - $ref: "#/components/schemas/ListResponse" - description: The request was successful. The returned value is a list of - objects. - "400": - content: {} - description: Entities cannot be retrieved. - "401": - content: {} - description: |- - User is not authenticated. Please supply a valid Access Token in the `Authorization` HTTP header (e.g. Authorization: bearer [token]) - or Genestack API token in the `Genestack-API-Token` header (this token may be obtained from the Genestack UI _Profile_ page). - "404": - content: {} - description: No object exists with the given ID. - "500": - content: {} - description: "An internal server error occurred. This indicates an unexpected\ - \ failure in the Genestack system, please file a bug report to support@genestack.com,\ - \ including the error details." - security: - - Access-token: [] - - Genestack-API-Token: [] - summary: "Retrieve run-sample pairs by group id. Pagination is based on unique\ - \ runs, not unique pairs." - tags: - - Expression integration as User - /api/v1/as-user/integration/link/flow-cytometry/by/sample/{id}: - get: - description: |+ - ## Versioning - Specific versions of omics data files (eg. GCT) can be queried via the useVersions parameter. Different versions of an omics data file are associated via their CHAIN_ID metadata value. This CHAIN_ID can be supplied to the useVersions parameter along with the version number or specific omics data file accessions to include them in the query. If nothing is supplied to the useVersions parameter then only the active version (which is usually the last one imported) is queried. This acts as a filter before the rest of the query is carried out. - - Example usage: - useVersions=* (query all versions, including those without CHAIN_IDs) - useVersions=v2 (query the second version. If there is no second version then the data file is not queried) - useVersions=v1,v0 (query the first version and any data files without CHAIN_IDs(v0) ) - useVersions=GSVC002:v3 (for omics data files with a CHAIN_ID of GSCV002 query the third version) - useVersions=GSVC002:GSF00494,GSF000496 (for omics data files with a CHAIN_ID of GSCV002 query only the specific accessions GSF00494 and GSF000496) - - Rules for multiple CHAIN_IDs can be supplied to the parameter using the ; separator. - - ## Paging - For performance reasons this endpoint returns results in "pages" of limited size. In order to retrieve all matching results the client needs to request multiple pages starting from an offset to the first result. You can do this using the pageOffset query parameter. A value of 0 (the default) instructs the server to return the first page of results, 100 would return a page of results starting from the 101st result and so on. To retrieve all results, iterate through pages using `pageOffset` values of `n * pageLimit` until a page returns fewer results than the page limit, which indicates there are no more results. - - operationId: getFlowCytometryBySampleAsUser - parameters: - - description: Supply this parameter with the value `term_id` as part of the - query to return extended information including IDs for values and dictionaries. - in: query - name: responseFormat - schema: - $ref: "#/components/schemas/ResponseFormat" - - description: Unique identifier (accession) of the object. - in: path - name: id - required: true - schema: - type: string - - description: Maximum number of results to return. This value must be between - 0 and 2000 (inclusive). - in: query - name: pageLimit - schema: - format: int32 - type: integer - - description: "Show the page {pageOffset+1} results from the start of the results.\ - \ E.g. 100 will show a page of results starting from the 101st result.\ - \ The default value is 0." - in: query - name: pageOffset - schema: - format: int32 - type: integer - - description: |- - Specify which versions of omics data files are used in the query. By default the active version is used. See Versioning above. Syntax: - - \* or `v` or ``:`v` or ``:`` - in: query - name: useVersions - schema: - type: string - - description: |- - The parameter defines amount of metadata attributes to return: - - 1. `minimal_data` - return metadata attributes according to the default template. - 2. `extended_data_included` - return metadata attributes according to applied template, if object doesn’t have applied template default template will be used. This is the default for User endpoints. - 3. `original_data_included` - return all metadata attributes with values and null attributes, if they are present in the applied template. This is the default for Curator endpoints. - in: query - name: returnedMetadataFields - schema: - enum: - - minimal_data - - extended_data_included - - original_data_included - type: string - responses: - "200": - content: - application/json: - schema: - $ref: "#/components/schemas/ListResponse" - text/tab-separated-values: - schema: - $ref: "#/components/schemas/ListResponse" - description: The request was successful. The returned value is a list of - objects. - "400": - content: {} - description: Entities cannot be retrieved. - "401": - content: {} - description: |- - User is not authenticated. Please supply a valid Access Token in the `Authorization` HTTP header (e.g. Authorization: bearer [token]) - or Genestack API token in the `Genestack-API-Token` header (this token may be obtained from the Genestack UI _Profile_ page). - "500": - content: {} - description: "An internal server error occurred. This indicates an unexpected\ - \ failure in the Genestack system, please file a bug report to support@genestack.com,\ - \ including the error details." - security: - - Access-token: [] - - Genestack-API-Token: [] - summary: Retrieve flow cytometry run-level data by querying related sample ID - (accession) - tags: - - Flow Cytometry (FACS) integration as User - /api/v1/as-user/integration/link/flow-cytometry/group/by/study/{id}: - get: - description: |+ - ## Versioning - Specific versions of omics data files (eg. GCT) can be queried via the useVersions parameter. Different versions of an omics data file are associated via their CHAIN_ID metadata value. This CHAIN_ID can be supplied to the useVersions parameter along with the version number or specific omics data file accessions to include them in the query. If nothing is supplied to the useVersions parameter then only the active version (which is usually the last one imported) is queried. This acts as a filter before the rest of the query is carried out. - - Example usage: - useVersions=* (query all versions, including those without CHAIN_IDs) - useVersions=v2 (query the second version. If there is no second version then the data file is not queried) - useVersions=v1,v0 (query the first version and any data files without CHAIN_IDs(v0) ) - useVersions=GSVC002:v3 (for omics data files with a CHAIN_ID of GSCV002 query the third version) - useVersions=GSVC002:GSF00494,GSF000496 (for omics data files with a CHAIN_ID of GSCV002 query only the specific accessions GSF00494 and GSF000496) - - Rules for multiple CHAIN_IDs can be supplied to the parameter using the ; separator. - - operationId: getFlowCytometryGroupsByStudyAsUser - parameters: - - description: Supply this parameter with the value `term_id` as part of the - query to return extended information including IDs for values and dictionaries. - in: query - name: responseFormat - schema: - $ref: "#/components/schemas/ResponseFormat" - - description: Unique identifier (accession) of the object. - in: path - name: id - required: true - schema: - type: string - - description: |- - Specify which versions of omics data files are used in the query. By default the active version is used. See Versioning above. Syntax: - - \* or `v` or ``:`v` or ``:`` - in: query - name: useVersions - schema: - type: string - - description: |- - The parameter defines amount of metadata attributes to return: - - 1. `minimal_data` - return metadata attributes according to the default template. - 2. `extended_data_included` - return metadata attributes according to applied template, if object doesn’t have applied template default template will be used. This is the default for User endpoints. - 3. `original_data_included` - return all metadata attributes with values and null attributes, if they are present in the applied template. This is the default for Curator endpoints. - in: query - name: returnedMetadataFields - schema: - enum: - - minimal_data - - extended_data_included - - original_data_included - type: string - responses: - "200": - content: - application/json: - schema: - items: - $ref: "#/components/schemas/MetadataWithId" - type: array - description: The request was successful. The returned value is the object. - "400": - content: {} - description: The supplied object ID is invalid. - "401": - content: {} - description: |- - User is not authenticated. Please supply a valid Access Token in the `Authorization` HTTP header (e.g. Authorization: bearer [token]) - or Genestack API token in the `Genestack-API-Token` header (this token may be obtained from the Genestack UI _Profile_ page). - "500": - content: {} - description: "An internal server error occurred. This indicates an unexpected\ - \ failure in the Genestack system, please file a bug report to support@genestack.com,\ - \ including the error details." - security: - - Access-token: [] - - Genestack-API-Token: [] - summary: Retrieve group metadata by querying study ID (accession) - tags: - - Flow Cytometry (FACS) integration as User - /api/v1/as-user/integration/link/flow-cytometry/run-to-samples/by/group/{id}: - get: - description: |+ - ## Paging - For performance reasons this endpoint returns results in "pages" of limited size. In order to retrieve all matching results the client needs to request multiple pages starting from an offset to the first result. You can do this using the pageOffset query parameter. A value of 0 (the default) instructs the server to return the first page of results, 100 would return a page of results starting from the 101st result and so on. To retrieve all results, iterate through pages using `pageOffset` values of `n * pageLimit` until a page returns fewer results than the page limit, which indicates there are no more results. - - operationId: getFlowCytometryRunToSamplePairsAsUser - parameters: - - description: Unique identifier (accession) of the object. - in: path - name: id - required: true - schema: - type: string - - description: Maximum number of results to return. This value must be between - 0 and 2000 (inclusive). - in: query - name: pageLimit - schema: - format: int32 - type: integer - - description: "Show the page {pageOffset+1} results from the start of the results.\ - \ E.g. 100 will show a page of results starting from the 101st result.\ - \ The default value is 0." - in: query - name: pageOffset - schema: - format: int32 - type: integer - responses: - "200": - content: - application/json: - schema: - $ref: "#/components/schemas/ListResponse" - description: The request was successful. The returned value is a list of - objects. - "400": - content: {} - description: Entities cannot be retrieved. - "401": - content: {} - description: |- - User is not authenticated. Please supply a valid Access Token in the `Authorization` HTTP header (e.g. Authorization: bearer [token]) - or Genestack API token in the `Genestack-API-Token` header (this token may be obtained from the Genestack UI _Profile_ page). - "404": - content: {} - description: No object exists with the given ID. - "500": - content: {} - description: "An internal server error occurred. This indicates an unexpected\ - \ failure in the Genestack system, please file a bug report to support@genestack.com,\ - \ including the error details." - security: - - Access-token: [] - - Genestack-API-Token: [] - summary: "Retrieve run-sample pairs by group id. Pagination is based on unique\ - \ runs, not unique pairs." - tags: - - Flow Cytometry (FACS) integration as User - /api/v1/as-user/integration/link/libraries/by/samples: - get: - description: |+ - Retrieve library metadata objects whose linked sample metadata matches all supplied conditions. - - ## Conditions - It is possible to supply conditions for: - - 1. Samples (full-text or metadata key-value pair) - 2. Parent studies (full-text or metadata key-value pair) - 3. Linked variant objects (list of data key-value pairs) - 4. Linked flow cytometry objects (list of data key-value pairs) - 5. Linked any data (except variant and flow cytometry) objects (list of data key-value pairs) - - ## Metadata full-text queries - Single words can be supplied as is; otherwise, use speech marks (`"`) to quote queries that include whitespace. Speech marks and backslash characters in the query need to be escaped with a backslash (`\`). - - ## Metadata filters - Metadata filters are key-value pairs joined by an operator. The `=` operator matches literal values/string. The `!=` operator matches anything except the literal value/string. The `<` or `>` operators match numerical results that are less or greater than the supplied value. Strings containing whitespace need to be quoted with (`"`). - - ## Data queries - Data queries must be a list of key-value pairs, separated by whitespace. The set of valid keys depends on the specific query type, and is documented in the query parameter summary. The values can be simple non-whitespace strings, or strings enclosed by speech marks (`"`). Depending on the key, the value may be be a comma-delimited list of string values. Others require numerical values. - - ## Combinations - Metadata queries/filters for the same parameter can be combined with `&&`, `AND`, `||` and `OR` operators, using white-space to separate out the terms and operators. Parentheses `( )` can be used for complex expressions. - - ## Versioning - Specific versions of omics data files (eg. GCT) can be queried via the useVersions parameter. Different versions of an omics data file are associated via their CHAIN_ID metadata value. This CHAIN_ID can be supplied to the useVersions parameter along with the version number or specific omics data file accessions to include them in the query. If nothing is supplied to the useVersions parameter then only the active version (which is usually the last one imported) is queried. This acts as a filter before the rest of the query is carried out. - - Example usage: - useVersions=* (query all versions, including those without CHAIN_IDs) - useVersions=v2 (query the second version. If there is no second version then the data file is not queried) - useVersions=v1,v0 (query the first version and any data files without CHAIN_IDs(v0) ) - useVersions=GSVC002:v3 (for omics data files with a CHAIN_ID of GSCV002 query the third version) - useVersions=GSVC002:GSF00494,GSF000496 (for omics data files with a CHAIN_ID of GSCV002 query only the specific accessions GSF00494 and GSF000496) - - Rules for multiple CHAIN_IDs can be supplied to the parameter using the ; separator. - - ## Paging - For performance reasons this endpoint returns results in "pages" of limited size. In order to retrieve all matching results the client needs to request multiple pages starting from an offset to the first result. You can do this using the pageOffset query parameter. A value of 0 (the default) instructs the server to return the first page of results, 100 would return a page of results starting from the 101st result and so on. To retrieve all results, iterate through pages using `pageOffset` values of `n * pageLimit` until a page returns fewer results than the page limit, which indicates there are no more results. - - operationId: getLibrariesBySamplesAsUser - parameters: - - description: Supply this parameter with the value `term_id` as part of the - query to return extended information including IDs for values and dictionaries. - in: query - name: responseFormat - schema: - $ref: "#/components/schemas/ResponseFormat" - - description: | - Filter by sample metadata (key-value metadata pair(s)). E.g. `"Species or strain"="Homo sapiens"` - in: query - name: filter - schema: - type: string - - description: Search for objects via a full-text query over all sample metadata - fields. E.g. `Clozapine`. Queries matching dictionary terms are automatically - expanded to include synonyms. - in: query - name: query - schema: - type: string - - description: |- - If the full-text query term is present in an ODM dictionary, enabling this parameter will modify the query to include child terms of the full-text query. - - For example, the search query "Body fluid" can be expanded to include the term "Blood" (a child term of "Body fluid") so files containing either "Body fluid" or "Blood" in their metadata will be returned in the search results. - - The parent-child relationship is defined by the key "broaders" or "subClassOf" in the dictionary. - - If the full query term is not present in a dictionary then this parameter has no effect. - in: query - name: searchSpecificTerms - schema: - type: boolean - - description: Maximum number of results to return. This value must be between - 0 and 2000 (inclusive). - in: query - name: pageLimit - schema: - format: int32 - type: integer - - description: "Show the page {pageOffset+1} results from the start of the results.\ - \ E.g. 100 will show a page of results starting from the 101st result.\ - \ The default value is 0." - in: query - name: pageOffset - schema: - format: int32 - type: integer - - description: |- - The parameter defines amount of metadata attributes to return: - - 1. `minimal_data` - return metadata attributes according to the default template. - 2. `extended_data_included` - return metadata attributes according to applied template, if object doesn’t have applied template default template will be used. This is the default for User endpoints. - 3. `original_data_included` - return all metadata attributes with values and null attributes, if they are present in the applied template. This is the default for Curator endpoints. - in: query - name: returnedMetadataFields - schema: - enum: - - minimal_data - - extended_data_included - - original_data_included - type: string - responses: - "200": - content: - application/json: - schema: - $ref: "#/components/schemas/ListResponse" - text/tab-separated-values: - schema: - $ref: "#/components/schemas/ListResponse" - description: The request was successful. The returned value is a list of - objects. - "401": - content: {} - description: |- - User is not authenticated. Please supply a valid Access Token in the `Authorization` HTTP header (e.g. Authorization: bearer [token]) - or Genestack API token in the `Genestack-API-Token` header (this token may be obtained from the Genestack UI _Profile_ page). - "500": - content: {} - description: "An internal server error occurred. This indicates an unexpected\ - \ failure in the Genestack system, please file a bug report to support@genestack.com,\ - \ including the error details." - security: - - Access-token: [] - - Genestack-API-Token: [] - summary: Retrieve library metadata by querying related samples - tags: - - Library integration as User - /api/v1/as-user/integration/link/library/by/sample/{id}: - get: - operationId: getLibraryBySampleAsUser - parameters: - - description: Supply this parameter with the value `term_id` as part of the - query to return extended information including IDs for values and dictionaries. - in: query - name: responseFormat - schema: - $ref: "#/components/schemas/ResponseFormat" - - description: Unique identifier (accession) of the object. - in: path - name: id - required: true - schema: - type: string - - description: |- - The parameter defines amount of metadata attributes to return: - - 1. `minimal_data` - return metadata attributes according to the default template. - 2. `extended_data_included` - return metadata attributes according to applied template, if object doesn’t have applied template default template will be used. This is the default for User endpoints. - 3. `original_data_included` - return all metadata attributes with values and null attributes, if they are present in the applied template. This is the default for Curator endpoints. - in: query - name: returnedMetadataFields - schema: - enum: - - minimal_data - - extended_data_included - - original_data_included - type: string - responses: - "200": - content: - application/json: - schema: - items: - $ref: "#/components/schemas/Library" - type: array - text/tab-separated-values: - schema: - items: - $ref: "#/components/schemas/Library" - type: array - description: The request was successful. The returned value is a list of - objects. - "400": - content: {} - description: Entities cannot be retrieved. - "401": - content: {} - description: |- - User is not authenticated. Please supply a valid Access Token in the `Authorization` HTTP header (e.g. Authorization: bearer [token]) - or Genestack API token in the `Genestack-API-Token` header (this token may be obtained from the Genestack UI _Profile_ page). - "500": - content: {} - description: "An internal server error occurred. This indicates an unexpected\ - \ failure in the Genestack system, please file a bug report to support@genestack.com,\ - \ including the error details." - security: - - Access-token: [] - - Genestack-API-Token: [] - summary: Retrieve library metadata by querying related sample ID (accession) - tags: - - Library integration as User - /api/v1/as-user/integration/link/library/group/by/study/{id}: - get: - operationId: getLibraryGroupsByStudyAsUser - parameters: - - description: Supply this parameter with the value `term_id` as part of the - query to return extended information including IDs for values and dictionaries. - in: query - name: responseFormat - schema: - $ref: "#/components/schemas/ResponseFormat" - - description: Unique identifier (accession) of the object. - in: path - name: id - required: true - schema: - type: string - responses: - "200": - content: - application/json: - schema: - items: - $ref: "#/components/schemas/MetadataWithId" - type: array - description: The request was successful. The returned value is the object. - "400": - content: {} - description: The supplied object ID is invalid. - "401": - content: {} - description: |- - User is not authenticated. Please supply a valid Access Token in the `Authorization` HTTP header (e.g. Authorization: bearer [token]) - or Genestack API token in the `Genestack-API-Token` header (this token may be obtained from the Genestack UI _Profile_ page). - "500": - content: {} - description: "An internal server error occurred. This indicates an unexpected\ - \ failure in the Genestack system, please file a bug report to support@genestack.com,\ - \ including the error details." - security: - - Access-token: [] - - Genestack-API-Token: [] - summary: Retrieve group metadata by querying study ID (accession) - tags: - - Library integration as User - /api/v1/as-user/integration/link/library/libraries-to-samples/by/group/{id}: - get: - description: |+ - ## Paging - For performance reasons this endpoint returns results in "pages" of limited size. In order to retrieve all matching results the client needs to request multiple pages starting from an offset to the first result. You can do this using the pageOffset query parameter. A value of 0 (the default) instructs the server to return the first page of results, 100 would return a page of results starting from the 101st result and so on. To retrieve all results, iterate through pages using `pageOffset` values of `n * pageLimit` until a page returns fewer results than the page limit, which indicates there are no more results. - - operationId: getLibraryLinksToSamplesAsUser - parameters: - - description: Unique identifier (accession) of the object. - in: path - name: id - required: true - schema: - type: string - - description: Maximum number of results to return. This value must be between - 0 and 2000 (inclusive). - in: query - name: pageLimit - schema: - format: int32 - type: integer - - description: "Show the page {pageOffset+1} results from the start of the results.\ - \ E.g. 100 will show a page of results starting from the 101st result.\ - \ The default value is 0." - in: query - name: pageOffset - schema: - format: int32 - type: integer - responses: - "200": - content: - application/json: - schema: - $ref: "#/components/schemas/ListResponse" - description: The request was successful. The returned value is a list of - objects. - "400": - content: {} - description: Entities cannot be retrieved. - "401": - content: {} - description: |- - User is not authenticated. Please supply a valid Access Token in the `Authorization` HTTP header (e.g. Authorization: bearer [token]) - or Genestack API token in the `Genestack-API-Token` header (this token may be obtained from the Genestack UI _Profile_ page). - "404": - content: {} - description: No object exists with the given ID. - "500": - content: {} - description: "An internal server error occurred. This indicates an unexpected\ - \ failure in the Genestack system, please file a bug report to support@genestack.com,\ - \ including the error details." - security: - - Access-token: [] - - Genestack-API-Token: [] - summary: "Retrieve library-samples pairs by group id. Pagination is based on\ - \ unique libraries, not unique pairs." - tags: - - Library integration as User - /api/v1/as-user/integration/link/preparation/by/sample/{id}: - get: - operationId: getPreparationBySampleAsUser - parameters: - - description: Supply this parameter with the value `term_id` as part of the - query to return extended information including IDs for values and dictionaries. - in: query - name: responseFormat - schema: - $ref: "#/components/schemas/ResponseFormat" - - description: Unique identifier (accession) of the object. - in: path - name: id - required: true - schema: - type: string - - description: |- - The parameter defines amount of metadata attributes to return: - - 1. `minimal_data` - return metadata attributes according to the default template. - 2. `extended_data_included` - return metadata attributes according to applied template, if object doesn’t have applied template default template will be used. This is the default for User endpoints. - 3. `original_data_included` - return all metadata attributes with values and null attributes, if they are present in the applied template. This is the default for Curator endpoints. - in: query - name: returnedMetadataFields - schema: - enum: - - minimal_data - - extended_data_included - - original_data_included - type: string - responses: - "200": - content: - application/json: - schema: - items: - $ref: "#/components/schemas/Preparation" - type: array - text/tab-separated-values: - schema: - items: - $ref: "#/components/schemas/Preparation" - type: array - description: The request was successful. The returned value is a list of - objects. - "400": - content: {} - description: Entities cannot be retrieved. - "401": - content: {} - description: |- - User is not authenticated. Please supply a valid Access Token in the `Authorization` HTTP header (e.g. Authorization: bearer [token]) - or Genestack API token in the `Genestack-API-Token` header (this token may be obtained from the Genestack UI _Profile_ page). - "500": - content: {} - description: "An internal server error occurred. This indicates an unexpected\ - \ failure in the Genestack system, please file a bug report to support@genestack.com,\ - \ including the error details." - security: - - Access-token: [] - - Genestack-API-Token: [] - summary: Retrieve preparation metadata by querying related sample ID (accession) - tags: - - Preparation integration as User - /api/v1/as-user/integration/link/preparation/group/by/study/{id}: - get: - operationId: getPreparationGroupsByStudyAsUser - parameters: - - description: Supply this parameter with the value `term_id` as part of the - query to return extended information including IDs for values and dictionaries. - in: query - name: responseFormat - schema: - $ref: "#/components/schemas/ResponseFormat" - - description: Unique identifier (accession) of the object. - in: path - name: id - required: true - schema: - type: string - responses: - "200": - content: - application/json: - schema: - items: - $ref: "#/components/schemas/MetadataWithId" - type: array - description: The request was successful. The returned value is the object. - "400": - content: {} - description: The supplied object ID is invalid. - "401": - content: {} - description: |- - User is not authenticated. Please supply a valid Access Token in the `Authorization` HTTP header (e.g. Authorization: bearer [token]) - or Genestack API token in the `Genestack-API-Token` header (this token may be obtained from the Genestack UI _Profile_ page). - "500": - content: {} - description: "An internal server error occurred. This indicates an unexpected\ - \ failure in the Genestack system, please file a bug report to support@genestack.com,\ - \ including the error details." - security: - - Access-token: [] - - Genestack-API-Token: [] - summary: Retrieve group metadata by querying study ID (accession) - tags: - - Preparation integration as User - /api/v1/as-user/integration/link/preparation/preparations-to-samples/by/group/{id}: - get: - description: |+ - ## Paging - For performance reasons this endpoint returns results in "pages" of limited size. In order to retrieve all matching results the client needs to request multiple pages starting from an offset to the first result. You can do this using the pageOffset query parameter. A value of 0 (the default) instructs the server to return the first page of results, 100 would return a page of results starting from the 101st result and so on. To retrieve all results, iterate through pages using `pageOffset` values of `n * pageLimit` until a page returns fewer results than the page limit, which indicates there are no more results. - - operationId: getPreparationLinksToSamplesAsUser - parameters: - - description: Unique identifier (accession) of the object. - in: path - name: id - required: true - schema: - type: string - - description: Maximum number of results to return. This value must be between - 0 and 2000 (inclusive). - in: query - name: pageLimit - schema: - format: int32 - type: integer - - description: "Show the page {pageOffset+1} results from the start of the results.\ - \ E.g. 100 will show a page of results starting from the 101st result.\ - \ The default value is 0." - in: query - name: pageOffset - schema: - format: int32 - type: integer - responses: - "200": - content: - application/json: - schema: - $ref: "#/components/schemas/ListResponse" - description: The request was successful. The returned value is a list of - objects. - "400": - content: {} - description: Entities cannot be retrieved. - "401": - content: {} - description: |- - User is not authenticated. Please supply a valid Access Token in the `Authorization` HTTP header (e.g. Authorization: bearer [token]) - or Genestack API token in the `Genestack-API-Token` header (this token may be obtained from the Genestack UI _Profile_ page). - "404": - content: {} - description: No object exists with the given ID. - "500": - content: {} - description: "An internal server error occurred. This indicates an unexpected\ - \ failure in the Genestack system, please file a bug report to support@genestack.com,\ - \ including the error details." - security: - - Access-token: [] - - Genestack-API-Token: [] - summary: "Retrieve run-sample pairs by group id. Pagination is based on unique\ - \ preparations, not unique pairs." - tags: - - Preparation integration as User - /api/v1/as-user/integration/link/preparations/by/samples: - get: - description: |+ - Retrieve preparation metadata objects whose linked sample metadata matches all supplied conditions. - - ## Conditions - It is possible to supply conditions for: - - 1. Samples (full-text or metadata key-value pair) - 2. Parent studies (full-text or metadata key-value pair) - 3. Linked variant objects (list of data key-value pairs) - 4. Linked flow cytometry objects (list of data key-value pairs) - 5. Linked any data (except variant and flow cytometry) objects (list of data key-value pairs) - - ## Metadata full-text queries - Single words can be supplied as is; otherwise, use speech marks (`"`) to quote queries that include whitespace. Speech marks and backslash characters in the query need to be escaped with a backslash (`\`). - - ## Metadata filters - Metadata filters are key-value pairs joined by an operator. The `=` operator matches literal values/string. The `!=` operator matches anything except the literal value/string. The `<` or `>` operators match numerical results that are less or greater than the supplied value. Strings containing whitespace need to be quoted with (`"`). - - ## Data queries - Data queries must be a list of key-value pairs, separated by whitespace. The set of valid keys depends on the specific query type, and is documented in the query parameter summary. The values can be simple non-whitespace strings, or strings enclosed by speech marks (`"`). Depending on the key, the value may be be a comma-delimited list of string values. Others require numerical values. - - ## Combinations - Metadata queries/filters for the same parameter can be combined with `&&`, `AND`, `||` and `OR` operators, using white-space to separate out the terms and operators. Parentheses `( )` can be used for complex expressions. - - ## Versioning - Specific versions of omics data files (eg. GCT) can be queried via the useVersions parameter. Different versions of an omics data file are associated via their CHAIN_ID metadata value. This CHAIN_ID can be supplied to the useVersions parameter along with the version number or specific omics data file accessions to include them in the query. If nothing is supplied to the useVersions parameter then only the active version (which is usually the last one imported) is queried. This acts as a filter before the rest of the query is carried out. - - Example usage: - useVersions=* (query all versions, including those without CHAIN_IDs) - useVersions=v2 (query the second version. If there is no second version then the data file is not queried) - useVersions=v1,v0 (query the first version and any data files without CHAIN_IDs(v0) ) - useVersions=GSVC002:v3 (for omics data files with a CHAIN_ID of GSCV002 query the third version) - useVersions=GSVC002:GSF00494,GSF000496 (for omics data files with a CHAIN_ID of GSCV002 query only the specific accessions GSF00494 and GSF000496) - - Rules for multiple CHAIN_IDs can be supplied to the parameter using the ; separator. - - ## Paging - For performance reasons this endpoint returns results in "pages" of limited size. In order to retrieve all matching results the client needs to request multiple pages starting from an offset to the first result. You can do this using the pageOffset query parameter. A value of 0 (the default) instructs the server to return the first page of results, 100 would return a page of results starting from the 101st result and so on. To retrieve all results, iterate through pages using `pageOffset` values of `n * pageLimit` until a page returns fewer results than the page limit, which indicates there are no more results. - - operationId: getPreparationsBySamplesAsUser - parameters: - - description: Supply this parameter with the value `term_id` as part of the - query to return extended information including IDs for values and dictionaries. - in: query - name: responseFormat - schema: - $ref: "#/components/schemas/ResponseFormat" - - description: | - Filter by sample metadata (key-value metadata pair(s)). E.g. `"Species or strain"="Homo sapiens"` - in: query - name: filter - schema: - type: string - - description: Search for objects via a full-text query over all sample metadata - fields. E.g. `Clozapine`. Queries matching dictionary terms are automatically - expanded to include synonyms. - in: query - name: query - schema: - type: string - - description: |- - If the full-text query term is present in an ODM dictionary, enabling this parameter will modify the query to include child terms of the full-text query. - - For example, the search query "Body fluid" can be expanded to include the term "Blood" (a child term of "Body fluid") so files containing either "Body fluid" or "Blood" in their metadata will be returned in the search results. - - The parent-child relationship is defined by the key "broaders" or "subClassOf" in the dictionary. - - If the full query term is not present in a dictionary then this parameter has no effect. - in: query - name: searchSpecificTerms - schema: - type: boolean - - description: Maximum number of results to return. This value must be between - 0 and 2000 (inclusive). - in: query - name: pageLimit - schema: - format: int32 - type: integer - - description: "Show the page {pageOffset+1} results from the start of the results.\ - \ E.g. 100 will show a page of results starting from the 101st result.\ - \ The default value is 0." - in: query - name: pageOffset - schema: - format: int32 - type: integer - - description: |- - The parameter defines amount of metadata attributes to return: - - 1. `minimal_data` - return metadata attributes according to the default template. - 2. `extended_data_included` - return metadata attributes according to applied template, if object doesn’t have applied template default template will be used. This is the default for User endpoints. - 3. `original_data_included` - return all metadata attributes with values and null attributes, if they are present in the applied template. This is the default for Curator endpoints. - in: query - name: returnedMetadataFields - schema: - enum: - - minimal_data - - extended_data_included - - original_data_included - type: string - responses: - "200": - content: - application/json: - schema: - $ref: "#/components/schemas/ListResponse" - text/tab-separated-values: - schema: - $ref: "#/components/schemas/ListResponse" - description: The request was successful. The returned value is a list of - objects. - "401": - content: {} - description: |- - User is not authenticated. Please supply a valid Access Token in the `Authorization` HTTP header (e.g. Authorization: bearer [token]) - or Genestack API token in the `Genestack-API-Token` header (this token may be obtained from the Genestack UI _Profile_ page). - "500": - content: {} - description: "An internal server error occurred. This indicates an unexpected\ - \ failure in the Genestack system, please file a bug report to support@genestack.com,\ - \ including the error details." - security: - - Access-token: [] - - Genestack-API-Token: [] - summary: Retrieve preparation metadata by querying related samples - tags: - - Preparation integration as User - /api/v1/as-user/integration/link/samples/by/libraries: - get: - description: |+ - Retrieve sample metadata objects whose linked library metadata matches all supplied conditions. - - ## Conditions - It is possible to supply conditions for: - - 1. Samples (full-text or metadata key-value pair) - 2. Parent studies (full-text or metadata key-value pair) - 3. Linked variant objects (list of data key-value pairs) - 4. Linked flow cytometry objects (list of data key-value pairs) - 5. Linked any data (except variant and flow cytometry) objects (list of data key-value pairs) - - ## Metadata full-text queries - Single words can be supplied as is; otherwise, use speech marks (`"`) to quote queries that include whitespace. Speech marks and backslash characters in the query need to be escaped with a backslash (`\`). - - ## Metadata filters - Metadata filters are key-value pairs joined by an operator. The `=` operator matches literal values/string. The `!=` operator matches anything except the literal value/string. The `<` or `>` operators match numerical results that are less or greater than the supplied value. Strings containing whitespace need to be quoted with (`"`). - - ## Data queries - Data queries must be a list of key-value pairs, separated by whitespace. The set of valid keys depends on the specific query type, and is documented in the query parameter summary. The values can be simple non-whitespace strings, or strings enclosed by speech marks (`"`). Depending on the key, the value may be be a comma-delimited list of string values. Others require numerical values. - - ## Combinations - Metadata queries/filters for the same parameter can be combined with `&&`, `AND`, `||` and `OR` operators, using white-space to separate out the terms and operators. Parentheses `( )` can be used for complex expressions. - - ## Versioning - Specific versions of omics data files (eg. GCT) can be queried via the useVersions parameter. Different versions of an omics data file are associated via their CHAIN_ID metadata value. This CHAIN_ID can be supplied to the useVersions parameter along with the version number or specific omics data file accessions to include them in the query. If nothing is supplied to the useVersions parameter then only the active version (which is usually the last one imported) is queried. This acts as a filter before the rest of the query is carried out. - - Example usage: - useVersions=* (query all versions, including those without CHAIN_IDs) - useVersions=v2 (query the second version. If there is no second version then the data file is not queried) - useVersions=v1,v0 (query the first version and any data files without CHAIN_IDs(v0) ) - useVersions=GSVC002:v3 (for omics data files with a CHAIN_ID of GSCV002 query the third version) - useVersions=GSVC002:GSF00494,GSF000496 (for omics data files with a CHAIN_ID of GSCV002 query only the specific accessions GSF00494 and GSF000496) - - Rules for multiple CHAIN_IDs can be supplied to the parameter using the ; separator. - - ## Paging - For performance reasons this endpoint returns results in "pages" of limited size. In order to retrieve all matching results the client needs to request multiple pages starting from an offset to the first result. You can do this using the pageOffset query parameter. A value of 0 (the default) instructs the server to return the first page of results, 100 would return a page of results starting from the 101st result and so on. To retrieve all results, iterate through pages using `pageOffset` values of `n * pageLimit` until a page returns fewer results than the page limit, which indicates there are no more results. - - operationId: getSamplesByLibrariesAsUser - parameters: - - description: Supply this parameter with the value `term_id` as part of the - query to return extended information including IDs for values and dictionaries. - in: query - name: responseFormat - schema: - $ref: "#/components/schemas/ResponseFormat" - - description: Filter by library metadata (key-value metadata pair(s)). E.g. - `"Library Type"=RNA-Seq-1` - in: query - name: filter - schema: - type: string - - description: Search for library objects via a full-text query over all library - metadata fields. E.g. `"illumina HiSeq500"`. Queries matching dictionary - terms are automatically expanded to include synonyms. - in: query - name: query - schema: - type: string - - description: |- - If the full-text query term is present in an ODM dictionary, enabling this parameter will modify the query to include child terms of the full-text query. - - For example, the search query "Body fluid" can be expanded to include the term "Blood" (a child term of "Body fluid") so files containing either "Body fluid" or "Blood" in their metadata will be returned in the search results. - - The parent-child relationship is defined by the key "broaders" or "subClassOf" in the dictionary. - - If the full query term is not present in a dictionary then this parameter has no effect. - in: query - name: searchSpecificTerms - schema: - type: boolean - - description: Maximum number of results to return. This value must be between - 0 and 2000 (inclusive). - in: query - name: pageLimit - schema: - format: int32 - type: integer - - description: "Show the page {pageOffset+1} results from the start of the results.\ - \ E.g. 100 will show a page of results starting from the 101st result.\ - \ The default value is 0." - in: query - name: pageOffset - schema: - format: int32 - type: integer - - description: |- - The parameter defines amount of metadata attributes to return: - - 1. `minimal_data` - return metadata attributes according to the default template. - 2. `extended_data_included` - return metadata attributes according to applied template, if object doesn’t have applied template default template will be used. This is the default for User endpoints. - 3. `original_data_included` - return all metadata attributes with values and null attributes, if they are present in the applied template. This is the default for Curator endpoints. - in: query - name: returnedMetadataFields - schema: - enum: - - minimal_data - - extended_data_included - - original_data_included - type: string - responses: - "200": - content: - application/json: - schema: - $ref: "#/components/schemas/ListResponse" - text/tab-separated-values: - schema: - $ref: "#/components/schemas/ListResponse" - description: The request was successful. The returned value is a list of - objects. - "401": - content: {} - description: |- - User is not authenticated. Please supply a valid Access Token in the `Authorization` HTTP header (e.g. Authorization: bearer [token]) - or Genestack API token in the `Genestack-API-Token` header (this token may be obtained from the Genestack UI _Profile_ page). - "500": - content: {} - description: "An internal server error occurred. This indicates an unexpected\ - \ failure in the Genestack system, please file a bug report to support@genestack.com,\ - \ including the error details." - security: - - Access-token: [] - - Genestack-API-Token: [] - summary: Retrieve sample metadata by querying related libraries - tags: - - Sample integration as User - /api/v1/as-user/integration/link/samples/by/preparations: - get: - description: |+ - Retrieve sample metadata objects whose linked preparation metadata matches all supplied conditions. - - ## Conditions - It is possible to supply conditions for: - - 1. Samples (full-text or metadata key-value pair) - 2. Parent studies (full-text or metadata key-value pair) - 3. Linked variant objects (list of data key-value pairs) - 4. Linked flow cytometry objects (list of data key-value pairs) - 5. Linked any data (except variant and flow cytometry) objects (list of data key-value pairs) - - ## Metadata full-text queries - Single words can be supplied as is; otherwise, use speech marks (`"`) to quote queries that include whitespace. Speech marks and backslash characters in the query need to be escaped with a backslash (`\`). - - ## Metadata filters - Metadata filters are key-value pairs joined by an operator. The `=` operator matches literal values/string. The `!=` operator matches anything except the literal value/string. The `<` or `>` operators match numerical results that are less or greater than the supplied value. Strings containing whitespace need to be quoted with (`"`). - - ## Data queries - Data queries must be a list of key-value pairs, separated by whitespace. The set of valid keys depends on the specific query type, and is documented in the query parameter summary. The values can be simple non-whitespace strings, or strings enclosed by speech marks (`"`). Depending on the key, the value may be be a comma-delimited list of string values. Others require numerical values. - - ## Combinations - Metadata queries/filters for the same parameter can be combined with `&&`, `AND`, `||` and `OR` operators, using white-space to separate out the terms and operators. Parentheses `( )` can be used for complex expressions. - - ## Versioning - Specific versions of omics data files (eg. GCT) can be queried via the useVersions parameter. Different versions of an omics data file are associated via their CHAIN_ID metadata value. This CHAIN_ID can be supplied to the useVersions parameter along with the version number or specific omics data file accessions to include them in the query. If nothing is supplied to the useVersions parameter then only the active version (which is usually the last one imported) is queried. This acts as a filter before the rest of the query is carried out. - - Example usage: - useVersions=* (query all versions, including those without CHAIN_IDs) - useVersions=v2 (query the second version. If there is no second version then the data file is not queried) - useVersions=v1,v0 (query the first version and any data files without CHAIN_IDs(v0) ) - useVersions=GSVC002:v3 (for omics data files with a CHAIN_ID of GSCV002 query the third version) - useVersions=GSVC002:GSF00494,GSF000496 (for omics data files with a CHAIN_ID of GSCV002 query only the specific accessions GSF00494 and GSF000496) - - Rules for multiple CHAIN_IDs can be supplied to the parameter using the ; separator. - - ## Paging - For performance reasons this endpoint returns results in "pages" of limited size. In order to retrieve all matching results the client needs to request multiple pages starting from an offset to the first result. You can do this using the pageOffset query parameter. A value of 0 (the default) instructs the server to return the first page of results, 100 would return a page of results starting from the 101st result and so on. To retrieve all results, iterate through pages using `pageOffset` values of `n * pageLimit` until a page returns fewer results than the page limit, which indicates there are no more results. - - operationId: getSamplesByPreparationsAsUser - parameters: - - description: Supply this parameter with the value `term_id` as part of the - query to return extended information including IDs for values and dictionaries. - in: query - name: responseFormat - schema: - $ref: "#/components/schemas/ResponseFormat" - - description: Filter by preparation metadata (key-value metadata pair(s)). - E.g. `Digestion=Trypsin` - in: query - name: filter - schema: - type: string - - description: Search for preparation objects via a full-text query over all - preparation metadata fields. E.g. `"reversed-phase liquid chromatography"`. - Queries matching dictionary terms are automatically expanded to include - synonyms. - in: query - name: query - schema: - type: string - - description: |- - If the full-text query term is present in an ODM dictionary, enabling this parameter will modify the query to include child terms of the full-text query. - - For example, the search query "Body fluid" can be expanded to include the term "Blood" (a child term of "Body fluid") so files containing either "Body fluid" or "Blood" in their metadata will be returned in the search results. - - The parent-child relationship is defined by the key "broaders" or "subClassOf" in the dictionary. - - If the full query term is not present in a dictionary then this parameter has no effect. - in: query - name: searchSpecificTerms - schema: - type: boolean - - description: Maximum number of results to return. This value must be between - 0 and 2000 (inclusive). - in: query - name: pageLimit - schema: - format: int32 - type: integer - - description: "Show the page {pageOffset+1} results from the start of the results.\ - \ E.g. 100 will show a page of results starting from the 101st result.\ - \ The default value is 0." - in: query - name: pageOffset - schema: - format: int32 - type: integer - - description: |- - The parameter defines amount of metadata attributes to return: - - 1. `minimal_data` - return metadata attributes according to the default template. - 2. `extended_data_included` - return metadata attributes according to applied template, if object doesn’t have applied template default template will be used. This is the default for User endpoints. - 3. `original_data_included` - return all metadata attributes with values and null attributes, if they are present in the applied template. This is the default for Curator endpoints. - in: query - name: returnedMetadataFields - schema: - enum: - - minimal_data - - extended_data_included - - original_data_included - type: string - responses: - "200": - content: - application/json: - schema: - $ref: "#/components/schemas/ListResponse" - text/tab-separated-values: - schema: - $ref: "#/components/schemas/ListResponse" - description: The request was successful. The returned value is a list of - objects. - "401": - content: {} - description: |- - User is not authenticated. Please supply a valid Access Token in the `Authorization` HTTP header (e.g. Authorization: bearer [token]) - or Genestack API token in the `Genestack-API-Token` header (this token may be obtained from the Genestack UI _Profile_ page). - "500": - content: {} - description: "An internal server error occurred. This indicates an unexpected\ - \ failure in the Genestack system, please file a bug report to support@genestack.com,\ - \ including the error details." - security: - - Access-token: [] - - Genestack-API-Token: [] - summary: Retrieve sample metadata by querying related preparations - tags: - - Sample integration as User - /api/v1/as-user/integration/link/samples/by/study/{id}: - get: - description: |+ - ## Paging - For performance reasons this endpoint returns results in "pages" of limited size. In order to retrieve all matching results the client needs to request multiple pages starting from an offset to the first result. You can do this using the pageOffset query parameter. A value of 0 (the default) instructs the server to return the first page of results, 100 would return a page of results starting from the 101st result and so on. To retrieve all results, iterate through pages using `pageOffset` values of `n * pageLimit` until a page returns fewer results than the page limit, which indicates there are no more results. - - operationId: getSamplesByStudyAsUser - parameters: - - description: Supply this parameter with the value `term_id` as part of the - query to return extended information including IDs for values and dictionaries. - in: query - name: responseFormat - schema: - $ref: "#/components/schemas/ResponseFormat" - - description: Unique identifier (accession) of the object. - in: path - name: id - required: true - schema: - type: string - - description: Maximum number of results to return. This value must be between - 0 and 2000 (inclusive). - in: query - name: pageLimit - schema: - format: int32 - type: integer - - description: "Show the page {pageOffset+1} results from the start of the results.\ - \ E.g. 100 will show a page of results starting from the 101st result.\ - \ The default value is 0." - in: query - name: pageOffset - schema: - format: int32 - type: integer - - description: |- - The parameter defines amount of metadata attributes to return: - - 1. `minimal_data` - return metadata attributes according to the default template. - 2. `extended_data_included` - return metadata attributes according to applied template, if object doesn’t have applied template default template will be used. This is the default for User endpoints. - 3. `original_data_included` - return all metadata attributes with values and null attributes, if they are present in the applied template. This is the default for Curator endpoints. - in: query - name: returnedMetadataFields - schema: - enum: - - minimal_data - - extended_data_included - - original_data_included - type: string - responses: - "200": - content: - application/json: - schema: - $ref: "#/components/schemas/ListResponse" - text/tab-separated-values: - schema: - $ref: "#/components/schemas/ListResponse" - description: The request was successful. The returned value is a list of - objects. - "400": - content: {} - description: Entities cannot be retrieved. - "401": - content: {} - description: |- - User is not authenticated. Please supply a valid Access Token in the `Authorization` HTTP header (e.g. Authorization: bearer [token]) - or Genestack API token in the `Genestack-API-Token` header (this token may be obtained from the Genestack UI _Profile_ page). - "500": - content: {} - description: "An internal server error occurred. This indicates an unexpected\ - \ failure in the Genestack system, please file a bug report to support@genestack.com,\ - \ including the error details." - security: - - Access-token: [] - - Genestack-API-Token: [] - summary: Retrieve sample metadata by querying related study ID (accession) - tags: - - Sample integration as User - /api/v1/as-user/integration/link/studies/by/libraries: - get: - description: |+ - Retrieve study metadata objects whose linked library metadata matches all supplied conditions. - - ## Conditions - It is possible to supply conditions for: - - 1. Samples (full-text or metadata key-value pair) - 2. Parent studies (full-text or metadata key-value pair) - 3. Linked variant objects (list of data key-value pairs) - 4. Linked flow cytometry objects (list of data key-value pairs) - 5. Linked any data (except variant and flow cytometry) objects (list of data key-value pairs) - - ## Metadata full-text queries - Single words can be supplied as is; otherwise, use speech marks (`"`) to quote queries that include whitespace. Speech marks and backslash characters in the query need to be escaped with a backslash (`\`). - - ## Metadata filters - Metadata filters are key-value pairs joined by an operator. The `=` operator matches literal values/string. The `!=` operator matches anything except the literal value/string. The `<` or `>` operators match numerical results that are less or greater than the supplied value. Strings containing whitespace need to be quoted with (`"`). - - ## Data queries - Data queries must be a list of key-value pairs, separated by whitespace. The set of valid keys depends on the specific query type, and is documented in the query parameter summary. The values can be simple non-whitespace strings, or strings enclosed by speech marks (`"`). Depending on the key, the value may be be a comma-delimited list of string values. Others require numerical values. - - ## Combinations - Metadata queries/filters for the same parameter can be combined with `&&`, `AND`, `||` and `OR` operators, using white-space to separate out the terms and operators. Parentheses `( )` can be used for complex expressions. - - ## Versioning - Specific versions of omics data files (eg. GCT) can be queried via the useVersions parameter. Different versions of an omics data file are associated via their CHAIN_ID metadata value. This CHAIN_ID can be supplied to the useVersions parameter along with the version number or specific omics data file accessions to include them in the query. If nothing is supplied to the useVersions parameter then only the active version (which is usually the last one imported) is queried. This acts as a filter before the rest of the query is carried out. - - Example usage: - useVersions=* (query all versions, including those without CHAIN_IDs) - useVersions=v2 (query the second version. If there is no second version then the data file is not queried) - useVersions=v1,v0 (query the first version and any data files without CHAIN_IDs(v0) ) - useVersions=GSVC002:v3 (for omics data files with a CHAIN_ID of GSCV002 query the third version) - useVersions=GSVC002:GSF00494,GSF000496 (for omics data files with a CHAIN_ID of GSCV002 query only the specific accessions GSF00494 and GSF000496) - - Rules for multiple CHAIN_IDs can be supplied to the parameter using the ; separator. - - ## Paging - For performance reasons this endpoint returns results in "pages" of limited size. In order to retrieve all matching results the client needs to request multiple pages starting from an offset to the first result. You can do this using the pageOffset query parameter. A value of 0 (the default) instructs the server to return the first page of results, 100 would return a page of results starting from the 101st result and so on. To retrieve all results, iterate through pages using `pageOffset` values of `n * pageLimit` until a page returns fewer results than the page limit, which indicates there are no more results. - - operationId: getStudiesByLibrariesAsUser - parameters: - - description: Supply this parameter with the value `term_id` as part of the - query to return extended information including IDs for values and dictionaries. - in: query - name: responseFormat - schema: - $ref: "#/components/schemas/ResponseFormat" - - description: Filter by library metadata (key-value metadata pair(s)). E.g. - `"Library Type"=RNA-Seq-1` - in: query - name: filter - schema: - type: string - - description: Search for library objects via a full-text query over all library - metadata fields. E.g. `"illumina HiSeq500"`. Queries matching dictionary - terms are automatically expanded to include synonyms. - in: query - name: query - schema: - type: string - - description: |- - If the full-text query term is present in an ODM dictionary, enabling this parameter will modify the query to include child terms of the full-text query. - - For example, the search query "Body fluid" can be expanded to include the term "Blood" (a child term of "Body fluid") so files containing either "Body fluid" or "Blood" in their metadata will be returned in the search results. - - The parent-child relationship is defined by the key "broaders" or "subClassOf" in the dictionary. - - If the full query term is not present in a dictionary then this parameter has no effect. - in: query - name: searchSpecificTerms - schema: - type: boolean - - description: Maximum number of results to return. This value must be between - 0 and 2000 (inclusive). - in: query - name: pageLimit - schema: - format: int32 - type: integer - - description: "Show the page {pageOffset+1} results from the start of the results.\ - \ E.g. 100 will show a page of results starting from the 101st result.\ - \ The default value is 0." - in: query - name: pageOffset - schema: - format: int32 - type: integer - - description: |- - The parameter defines amount of metadata attributes to return: - - 1. `minimal_data` - return metadata attributes according to the default template. - 2. `extended_data_included` - return metadata attributes according to applied template, if object doesn’t have applied template default template will be used. This is the default for User endpoints. - 3. `original_data_included` - return all metadata attributes with values and null attributes, if they are present in the applied template. This is the default for Curator endpoints. - in: query - name: returnedMetadataFields - schema: - enum: - - minimal_data - - extended_data_included - - original_data_included - type: string - responses: - "200": - content: - application/json: - schema: - $ref: "#/components/schemas/ListResponse" - text/tab-separated-values: - schema: - $ref: "#/components/schemas/ListResponse" - description: The request was successful. The returned value is a list of - objects. - "401": - content: {} - description: |- - User is not authenticated. Please supply a valid Access Token in the `Authorization` HTTP header (e.g. Authorization: bearer [token]) - or Genestack API token in the `Genestack-API-Token` header (this token may be obtained from the Genestack UI _Profile_ page). - "500": - content: {} - description: "An internal server error occurred. This indicates an unexpected\ - \ failure in the Genestack system, please file a bug report to support@genestack.com,\ - \ including the error details." - security: - - Access-token: [] - - Genestack-API-Token: [] - summary: Retrieve study metadata objects by querying related libraries - tags: - - Study integration as User - /api/v1/as-user/integration/link/studies/by/preparations: - get: - description: |+ - Retrieve study metadata objects whose linked preparation metadata matches all supplied conditions. - - ## Conditions - It is possible to supply conditions for: - - 1. Samples (full-text or metadata key-value pair) - 2. Parent studies (full-text or metadata key-value pair) - 3. Linked variant objects (list of data key-value pairs) - 4. Linked flow cytometry objects (list of data key-value pairs) - 5. Linked any data (except variant and flow cytometry) objects (list of data key-value pairs) - - ## Metadata full-text queries - Single words can be supplied as is; otherwise, use speech marks (`"`) to quote queries that include whitespace. Speech marks and backslash characters in the query need to be escaped with a backslash (`\`). - - ## Metadata filters - Metadata filters are key-value pairs joined by an operator. The `=` operator matches literal values/string. The `!=` operator matches anything except the literal value/string. The `<` or `>` operators match numerical results that are less or greater than the supplied value. Strings containing whitespace need to be quoted with (`"`). - - ## Data queries - Data queries must be a list of key-value pairs, separated by whitespace. The set of valid keys depends on the specific query type, and is documented in the query parameter summary. The values can be simple non-whitespace strings, or strings enclosed by speech marks (`"`). Depending on the key, the value may be be a comma-delimited list of string values. Others require numerical values. - - ## Combinations - Metadata queries/filters for the same parameter can be combined with `&&`, `AND`, `||` and `OR` operators, using white-space to separate out the terms and operators. Parentheses `( )` can be used for complex expressions. - - ## Versioning - Specific versions of omics data files (eg. GCT) can be queried via the useVersions parameter. Different versions of an omics data file are associated via their CHAIN_ID metadata value. This CHAIN_ID can be supplied to the useVersions parameter along with the version number or specific omics data file accessions to include them in the query. If nothing is supplied to the useVersions parameter then only the active version (which is usually the last one imported) is queried. This acts as a filter before the rest of the query is carried out. - - Example usage: - useVersions=* (query all versions, including those without CHAIN_IDs) - useVersions=v2 (query the second version. If there is no second version then the data file is not queried) - useVersions=v1,v0 (query the first version and any data files without CHAIN_IDs(v0) ) - useVersions=GSVC002:v3 (for omics data files with a CHAIN_ID of GSCV002 query the third version) - useVersions=GSVC002:GSF00494,GSF000496 (for omics data files with a CHAIN_ID of GSCV002 query only the specific accessions GSF00494 and GSF000496) - - Rules for multiple CHAIN_IDs can be supplied to the parameter using the ; separator. - - ## Paging - For performance reasons this endpoint returns results in "pages" of limited size. In order to retrieve all matching results the client needs to request multiple pages starting from an offset to the first result. You can do this using the pageOffset query parameter. A value of 0 (the default) instructs the server to return the first page of results, 100 would return a page of results starting from the 101st result and so on. To retrieve all results, iterate through pages using `pageOffset` values of `n * pageLimit` until a page returns fewer results than the page limit, which indicates there are no more results. - - operationId: getStudiesByPreparationsAsUser - parameters: - - description: Supply this parameter with the value `term_id` as part of the - query to return extended information including IDs for values and dictionaries. - in: query - name: responseFormat - schema: - $ref: "#/components/schemas/ResponseFormat" - - description: Filter by preparation metadata (key-value metadata pair(s)). - E.g. `Digestion=Trypsin` - in: query - name: filter - schema: - type: string - - description: Search for preparation objects via a full-text query over all - preparation metadata fields. E.g. `"reversed-phase liquid chromatography"`. - Queries matching dictionary terms are automatically expanded to include - synonyms. - in: query - name: query - schema: - type: string - - description: |- - If the full-text query term is present in an ODM dictionary, enabling this parameter will modify the query to include child terms of the full-text query. - - For example, the search query "Body fluid" can be expanded to include the term "Blood" (a child term of "Body fluid") so files containing either "Body fluid" or "Blood" in their metadata will be returned in the search results. - - The parent-child relationship is defined by the key "broaders" or "subClassOf" in the dictionary. - - If the full query term is not present in a dictionary then this parameter has no effect. - in: query - name: searchSpecificTerms - schema: - type: boolean - - description: Maximum number of results to return. This value must be between - 0 and 2000 (inclusive). - in: query - name: pageLimit - schema: - format: int32 - type: integer - - description: "Show the page {pageOffset+1} results from the start of the results.\ - \ E.g. 100 will show a page of results starting from the 101st result.\ - \ The default value is 0." - in: query - name: pageOffset - schema: - format: int32 - type: integer - - description: |- - The parameter defines amount of metadata attributes to return: - - 1. `minimal_data` - return metadata attributes according to the default template. - 2. `extended_data_included` - return metadata attributes according to applied template, if object doesn’t have applied template default template will be used. This is the default for User endpoints. - 3. `original_data_included` - return all metadata attributes with values and null attributes, if they are present in the applied template. This is the default for Curator endpoints. - in: query - name: returnedMetadataFields - schema: - enum: - - minimal_data - - extended_data_included - - original_data_included - type: string - responses: - "200": - content: - application/json: - schema: - $ref: "#/components/schemas/ListResponse" - text/tab-separated-values: - schema: - $ref: "#/components/schemas/ListResponse" - description: The request was successful. The returned value is a list of - objects. - "401": - content: {} - description: |- - User is not authenticated. Please supply a valid Access Token in the `Authorization` HTTP header (e.g. Authorization: bearer [token]) - or Genestack API token in the `Genestack-API-Token` header (this token may be obtained from the Genestack UI _Profile_ page). - "500": - content: {} - description: "An internal server error occurred. This indicates an unexpected\ - \ failure in the Genestack system, please file a bug report to support@genestack.com,\ - \ including the error details." - security: - - Access-token: [] - - Genestack-API-Token: [] - summary: Retrieve study metadata objects by querying related preparations - tags: - - Study integration as User - /api/v1/as-user/integration/link/studies/by/samples: - get: - description: |+ - Retrieve study metadata objects whose linked sample metadata matches all supplied conditions. - - ## Conditions - It is possible to supply conditions for: - - 1. Samples (full-text or metadata key-value pair) - 2. Parent studies (full-text or metadata key-value pair) - 3. Linked variant objects (list of data key-value pairs) - 4. Linked flow cytometry objects (list of data key-value pairs) - 5. Linked any data (except variant and flow cytometry) objects (list of data key-value pairs) - - ## Metadata full-text queries - Single words can be supplied as is; otherwise, use speech marks (`"`) to quote queries that include whitespace. Speech marks and backslash characters in the query need to be escaped with a backslash (`\`). - - ## Metadata filters - Metadata filters are key-value pairs joined by an operator. The `=` operator matches literal values/string. The `!=` operator matches anything except the literal value/string. The `<` or `>` operators match numerical results that are less or greater than the supplied value. Strings containing whitespace need to be quoted with (`"`). - - ## Data queries - Data queries must be a list of key-value pairs, separated by whitespace. The set of valid keys depends on the specific query type, and is documented in the query parameter summary. The values can be simple non-whitespace strings, or strings enclosed by speech marks (`"`). Depending on the key, the value may be be a comma-delimited list of string values. Others require numerical values. - - ## Combinations - Metadata queries/filters for the same parameter can be combined with `&&`, `AND`, `||` and `OR` operators, using white-space to separate out the terms and operators. Parentheses `( )` can be used for complex expressions. - - ## Versioning - Specific versions of omics data files (eg. GCT) can be queried via the useVersions parameter. Different versions of an omics data file are associated via their CHAIN_ID metadata value. This CHAIN_ID can be supplied to the useVersions parameter along with the version number or specific omics data file accessions to include them in the query. If nothing is supplied to the useVersions parameter then only the active version (which is usually the last one imported) is queried. This acts as a filter before the rest of the query is carried out. - - Example usage: - useVersions=* (query all versions, including those without CHAIN_IDs) - useVersions=v2 (query the second version. If there is no second version then the data file is not queried) - useVersions=v1,v0 (query the first version and any data files without CHAIN_IDs(v0) ) - useVersions=GSVC002:v3 (for omics data files with a CHAIN_ID of GSCV002 query the third version) - useVersions=GSVC002:GSF00494,GSF000496 (for omics data files with a CHAIN_ID of GSCV002 query only the specific accessions GSF00494 and GSF000496) - - Rules for multiple CHAIN_IDs can be supplied to the parameter using the ; separator. - - ## Paging - For performance reasons this endpoint returns results in "pages" of limited size. In order to retrieve all matching results the client needs to request multiple pages starting from an offset to the first result. You can do this using the pageOffset query parameter. A value of 0 (the default) instructs the server to return the first page of results, 100 would return a page of results starting from the 101st result and so on. To retrieve all results, iterate through pages using `pageOffset` values of `n * pageLimit` until a page returns fewer results than the page limit, which indicates there are no more results. - - operationId: getStudiesBySamplesAsUser - parameters: - - description: Supply this parameter with the value `term_id` as part of the - query to return extended information including IDs for values and dictionaries. - in: query - name: responseFormat - schema: - $ref: "#/components/schemas/ResponseFormat" - - description: Filter by sample metadata (key-value metadata pair(s)). E.g. - "Species or strain"="Homo sapiens" - in: query - name: filter - schema: - type: string - - description: Search for study metadata objects via a full-text query over - all sample metadata fields. E.g. "RNA-Seq of human dendritic cells". Queries - matching dictionary terms are automatically expanded to include synonyms. - in: query - name: query - schema: - type: string - - description: |- - If the full-text query term is present in an ODM dictionary, enabling this parameter will modify the query to include child terms of the full-text query. - - For example, the search query "Body fluid" can be expanded to include the term "Blood" (a child term of "Body fluid") so files containing either "Body fluid" or "Blood" in their metadata will be returned in the search results. - - The parent-child relationship is defined by the key "broaders" or "subClassOf" in the dictionary. - - If the full query term is not present in a dictionary then this parameter has no effect. - in: query - name: searchSpecificTerms - schema: - type: boolean - - description: Maximum number of results to return. This value must be between - 0 and 2000 (inclusive). - in: query - name: pageLimit - schema: - format: int32 - type: integer - - description: "Show the page {pageOffset+1} results from the start of the results.\ - \ E.g. 100 will show a page of results starting from the 101st result.\ - \ The default value is 0." - in: query - name: pageOffset - schema: - format: int32 - type: integer - - description: |- - The parameter defines amount of metadata attributes to return: - - 1. `minimal_data` - return metadata attributes according to the default template. - 2. `extended_data_included` - return metadata attributes according to applied template, if object doesn’t have applied template default template will be used. This is the default for User endpoints. - 3. `original_data_included` - return all metadata attributes with values and null attributes, if they are present in the applied template. This is the default for Curator endpoints. - in: query - name: returnedMetadataFields - schema: - enum: - - minimal_data - - extended_data_included - - original_data_included - type: string - responses: - "200": - content: - application/json: - schema: - $ref: "#/components/schemas/ListResponse" - text/tab-separated-values: - schema: - $ref: "#/components/schemas/ListResponse" - description: The request was successful. The returned value is a list of - objects. - "401": - content: {} - description: |- - User is not authenticated. Please supply a valid Access Token in the `Authorization` HTTP header (e.g. Authorization: bearer [token]) - or Genestack API token in the `Genestack-API-Token` header (this token may be obtained from the Genestack UI _Profile_ page). - "500": - content: {} - description: "An internal server error occurred. This indicates an unexpected\ - \ failure in the Genestack system, please file a bug report to support@genestack.com,\ - \ including the error details." - security: - - Access-token: [] - - Genestack-API-Token: [] - summary: Retrieve study metadata objects by querying related samples - tags: - - Study integration as User - /api/v1/as-user/integration/link/study/by/sample/{id}: - get: - operationId: getStudyBySampleAsUser - parameters: - - description: Supply this parameter with the value `term_id` as part of the - query to return extended information including IDs for values and dictionaries. - in: query - name: responseFormat - schema: - $ref: "#/components/schemas/ResponseFormat" - - description: Unique identifier (accession) of the object. - in: path - name: id - required: true - schema: - type: string - - description: |- - The parameter defines amount of metadata attributes to return: - - 1. `minimal_data` - return metadata attributes according to the default template. - 2. `extended_data_included` - return metadata attributes according to applied template, if object doesn’t have applied template default template will be used. This is the default for User endpoints. - 3. `original_data_included` - return all metadata attributes with values and null attributes, if they are present in the applied template. This is the default for Curator endpoints. - in: query - name: returnedMetadataFields - schema: - enum: - - minimal_data - - extended_data_included - - original_data_included - type: string - responses: - "200": - content: - application/json: - schema: - $ref: "#/components/schemas/Study" - description: The request was successful. The returned value is the object. - "400": - content: {} - description: The supplied object ID is invalid. - "401": - content: {} - description: |- - User is not authenticated. Please supply a valid Access Token in the `Authorization` HTTP header (e.g. Authorization: bearer [token]) - or Genestack API token in the `Genestack-API-Token` header (this token may be obtained from the Genestack UI _Profile_ page). - "500": - content: {} - description: "An internal server error occurred. This indicates an unexpected\ - \ failure in the Genestack system, please file a bug report to support@genestack.com,\ - \ including the error details." - security: - - Access-token: [] - - Genestack-API-Token: [] - summary: Retrieve study metadata by querying sample ID (accession) - tags: - - Study integration as User - /api/v1/as-user/integration/link/studies/by/files: - get: - description: |+ - Retrieve study metadata objects whose linked attached files metadata matches all supplied conditions. - - ## Conditions - It is possible to supply conditions for: - - 1. Attachment files (full-text or metadata key-value pair) - 2. Parent studies (full-text or metadata key-value pair) - - ## Metadata full-text queries - Single words can be supplied as is; otherwise, use speech marks (`"`) to quote queries that include whitespace. Speech marks and backslash characters in the query need to be escaped with a backslash (`\`). - - ## Metadata filters - Metadata filters are key-value pairs joined by an operator. The `=` operator matches literal values/string. The `!=` operator matches anything except the literal value/string. The `<` or `>` operators match numerical results that are less or greater than the supplied value. Strings containing whitespace need to be quoted with (`"`). - - ## Combinations - Metadata queries/filters for the same parameter can be combined with `&&`, `AND`, `||` and `OR` operators, using white-space to separate out the terms and operators. Parentheses `( )` can be used for complex expressions. - - ## Paging - For performance reasons this endpoint returns results in "pages" of limited size. In order to retrieve all matching results the client needs to request multiple pages starting from an offset to the first result. You can do this using the pageOffset query parameter. A value of 0 (the default) instructs the server to return the first page of results, 100 would return a page of results starting from the 101st result and so on. To retrieve all results, iterate through pages using `pageOffset` values of `n * pageLimit` until a page returns fewer results than the page limit, which indicates there are no more results. - - operationId: getStudiesByFilesAsUser - parameters: - - description: Supply this parameter with the value `term_id` as part of the - query to return extended information including IDs for values and dictionaries. - in: query - name: responseFormat - schema: - $ref: "#/components/schemas/ResponseFormat" - - description: Filter by attachment file metadata (key-value metadata pair(s)). E.g. - "Species or strain"="Homo sapiens" - in: query - name: filter - schema: - type: string - - description: Search for study metadata objects via a full-text query over - all attached files metadata fields. E.g. "RNA-Seq of human dendritic cells". Queries - matching dictionary terms are automatically expanded to include synonyms. - in: query - name: query - schema: - type: string - - description: Maximum number of results to return. This value must be between - 0 and 2000 (inclusive). - in: query - name: pageLimit - schema: - format: int32 - type: integer - - description: "Show the page {pageOffset+1} results from the start of the results.\ - \ E.g. 100 will show a page of results starting from the 101st result.\ - \ The default value is 0." - in: query - name: pageOffset - schema: - format: int32 - type: integer - - description: |- - The parameter defines amount of metadata attributes to return: - - 1. `minimal_data` - return metadata attributes according to the default template. - 2. `extended_data_included` - return metadata attributes according to applied template, if object doesn’t have applied template default template will be used. This is the default for User endpoints. - 3. `original_data_included` - return all metadata attributes with values and null attributes, if they are present in the applied template. This is the default for Curator endpoints. - in: query - name: returnedMetadataFields - schema: - enum: - - minimal_data - - extended_data_included - - original_data_included - type: string - responses: - "200": - content: - application/json: - schema: - $ref: "#/components/schemas/ListResponse" - text/tab-separated-values: - schema: - $ref: "#/components/schemas/ListResponse" - description: The request was successful. The returned value is a list of - objects. - "401": - content: {} - description: |- - User is not authenticated. Please supply a valid Access Token in the `Authorization` HTTP header (e.g. Authorization: bearer [token]) - or Genestack API token in the `Genestack-API-Token` header (this token may be obtained from the Genestack UI _Profile_ page). - "500": - content: {} - description: "An internal server error occurred. This indicates an unexpected\ - \ failure in the Genestack system, please file a bug report to support@genestack.com,\ - \ including the error details." - security: - - Access-token: [] - - Genestack-API-Token: [] - summary: Retrieve study metadata objects by querying related attachment files - tags: - - Study integration as User - /api/v1/as-user/integration/link/study/by/file/{id}: - get: - operationId: getStudyByFileAsUser - parameters: - - description: Supply this parameter with the value `term_id` as part of the - query to return extended information including IDs for values and dictionaries. - in: query - name: responseFormat - schema: - $ref: "#/components/schemas/ResponseFormat" - - description: Unique identifier (accession) of the object. - in: path - name: id - required: true - schema: - type: string - - description: |- - The parameter defines amount of metadata attributes to return: - - 1. `minimal_data` - return metadata attributes according to the default template. - 2. `extended_data_included` - return metadata attributes according to applied template, if object doesn’t have applied template default template will be used. This is the default for User endpoints. - 3. `original_data_included` - return all metadata attributes with values and null attributes, if they are present in the applied template. This is the default for Curator endpoints. - in: query - name: returnedMetadataFields - schema: - enum: - - minimal_data - - extended_data_included - - original_data_included - type: string - responses: - "200": - content: - application/json: - schema: - $ref: "#/components/schemas/Study" - description: The request was successful. The returned value is the object. - "400": - content: {} - description: The supplied object ID is invalid. - "401": - content: {} - description: |- - User is not authenticated. Please supply a valid Access Token in the `Authorization` HTTP header (e.g. Authorization: bearer [token]) - or Genestack API token in the `Genestack-API-Token` header (this token may be obtained from the Genestack UI _Profile_ page). - "500": - content: {} - description: "An internal server error occurred. This indicates an unexpected\ - \ failure in the Genestack system, please file a bug report to support@genestack.com,\ - \ including the error details." - security: - - Access-token: [] - - Genestack-API-Token: [] - summary: Retrieve study metadata by querying attachment file ID (accession) - tags: - - Study integration as User - /api/v1/as-user/integration/fulltext/search/studies: - post: - description: |- - Find studies and retrieve their data using full-text search or facet search by metadata of study itself or child object (samples, libraries, preparations, signal groups). Only studies available to that users are returned. - - The endpoint returns: - - a list of studies with their metadata summary; - - a list of filter objects with counts; filter list is the same for all users in an and can be configured in “Study Browser” application via "Configure facets" (by a user with corresponding permission); for each filter object, only the first 5 most popular facets are returned, the facts are sorted by the count value in descending order; only studies available to user are counted. - - Filter attributes for fulltext search: - - `"type": "FULL_TEXT"` - - `"match"` - - `"mode"` - - For details on two latter ones, see the request body model. Only one filter with `"type=": "FULL_TEXT"` can be passed in the request body. - - To filter studies via facets, the filter attributes are necessary: type = SELECT, filterOptionId. For details, use the request body model. filterOptionId can be obtained from the response body when the endpoint is first called without filters. Multiple filters with type = SELECT can be passed in the request body. Filters within the same attribute are automatically used with the OR operator. Filters of different attributes are automatically used with the AND operator. This behaviour can not be changed. - - It is possible to call the endpoint without any filters, then all the studies available to the user are returned. - - The endpoint searches by staging version of the object metadata. - operationId: searchStudiesByFilterAsUser - requestBody: - content: - application/json: - schema: - $ref: "#/components/schemas/SearchStudyRequest" - required: true - responses: - "200": - content: - application/json: - schema: - $ref: "#/components/schemas/FindObjectsResponse" - description: The request was successful. Retrieved studies and filters. - "400": - content: {} - description: Invalid request body - "401": - content: {} - description: User is not authenticated. Please supply a valid Genestack - API token in the `Genestack-API-Token` HTTP header (this token may be - obtained from the Genestack UI _Profile_ page). - "500": - content: {} - description: "An internal server error occurred. This indicates an unexpected\ - \ failure in the Genestack system, please file a bug report to support@genestack.com,\ - \ including the error details." - security: - - Genestack-API-Token: [] - summary: Find and retrieve studies by full-text or facet query - tags: - - Study integration as User - x-codegen-request-body-name: request - /api/v1/as-user/integration/link/variant/by/sample/{id}: - get: - description: |+ - ## Versioning - Specific versions of omics data files (eg. GCT) can be queried via the useVersions parameter. Different versions of an omics data file are associated via their CHAIN_ID metadata value. This CHAIN_ID can be supplied to the useVersions parameter along with the version number or specific omics data file accessions to include them in the query. If nothing is supplied to the useVersions parameter then only the active version (which is usually the last one imported) is queried. This acts as a filter before the rest of the query is carried out. - - Example usage: - useVersions=* (query all versions, including those without CHAIN_IDs) - useVersions=v2 (query the second version. If there is no second version then the data file is not queried) - useVersions=v1,v0 (query the first version and any data files without CHAIN_IDs(v0) ) - useVersions=GSVC002:v3 (for omics data files with a CHAIN_ID of GSCV002 query the third version) - useVersions=GSVC002:GSF00494,GSF000496 (for omics data files with a CHAIN_ID of GSCV002 query only the specific accessions GSF00494 and GSF000496) - - Rules for multiple CHAIN_IDs can be supplied to the parameter using the ; separator. - - ## Paging - For performance reasons this endpoint returns results in "pages" of limited size. In order to retrieve all matching results the client needs to request multiple pages starting from an offset to the first result. You can do this using the pageOffset query parameter. A value of 0 (the default) instructs the server to return the first page of results, 100 would return a page of results starting from the 101st result and so on. To retrieve all results, iterate through pages using `pageOffset` values of `n * pageLimit` until a page returns fewer results than the page limit, which indicates there are no more results. - - operationId: getVariantBySampleAsUser - parameters: - - description: Supply this parameter with the value `term_id` as part of the - query to return extended information including IDs for values and dictionaries. - in: query - name: responseFormat - schema: - $ref: "#/components/schemas/ResponseFormat" - - description: Unique identifier (accession) of the object. - in: path - name: id - required: true - schema: - type: string - - description: Maximum number of results to return. This value must be between - 0 and 2000 (inclusive). - in: query - name: pageLimit - schema: - format: int32 - type: integer - - description: "Show the page {pageOffset+1} results from the start of the results.\ - \ E.g. 100 will show a page of results starting from the 101st result.\ - \ The default value is 0." - in: query - name: pageOffset - schema: - format: int32 - type: integer - - description: |- - Specify which versions of omics data files are used in the query. By default the active version is used. See Versioning above. Syntax: - - \* or `v` or ``:`v` or ``:`` - in: query - name: useVersions - schema: - type: string - - description: |- - The parameter defines amount of metadata attributes to return: - - 1. `minimal_data` - return metadata attributes according to the default template. - 2. `extended_data_included` - return metadata attributes according to applied template, if object doesn’t have applied template default template will be used. This is the default for User endpoints. - 3. `original_data_included` - return all metadata attributes with values and null attributes, if they are present in the applied template. This is the default for Curator endpoints. - in: query - name: returnedMetadataFields - schema: - enum: - - minimal_data - - extended_data_included - - original_data_included - type: string - responses: - "200": - content: - application/json: - schema: - $ref: "#/components/schemas/ListResponse" - text/tab-separated-values: - schema: - $ref: "#/components/schemas/ListResponse" - description: The request was successful. The returned value is a list of - objects. - "400": - content: {} - description: Entities cannot be retrieved. - "401": - content: {} - description: |- - User is not authenticated. Please supply a valid Access Token in the `Authorization` HTTP header (e.g. Authorization: bearer [token]) - or Genestack API token in the `Genestack-API-Token` header (this token may be obtained from the Genestack UI _Profile_ page). - "500": - content: {} - description: "An internal server error occurred. This indicates an unexpected\ - \ failure in the Genestack system, please file a bug report to support@genestack.com,\ - \ including the error details." - security: - - Access-token: [] - - Genestack-API-Token: [] - summary: Retrieve variant run-level data by querying related sample ID (accession) - tags: - - Variant integration as User - /api/v1/as-user/integration/link/variant/group/by/study/{id}: - get: - description: |+ - ## Versioning - Specific versions of omics data files (eg. GCT) can be queried via the useVersions parameter. Different versions of an omics data file are associated via their CHAIN_ID metadata value. This CHAIN_ID can be supplied to the useVersions parameter along with the version number or specific omics data file accessions to include them in the query. If nothing is supplied to the useVersions parameter then only the active version (which is usually the last one imported) is queried. This acts as a filter before the rest of the query is carried out. - - Example usage: - useVersions=* (query all versions, including those without CHAIN_IDs) - useVersions=v2 (query the second version. If there is no second version then the data file is not queried) - useVersions=v1,v0 (query the first version and any data files without CHAIN_IDs(v0) ) - useVersions=GSVC002:v3 (for omics data files with a CHAIN_ID of GSCV002 query the third version) - useVersions=GSVC002:GSF00494,GSF000496 (for omics data files with a CHAIN_ID of GSCV002 query only the specific accessions GSF00494 and GSF000496) - - Rules for multiple CHAIN_IDs can be supplied to the parameter using the ; separator. - - operationId: getVariantGroupsByStudyAsUser - parameters: - - description: Supply this parameter with the value `term_id` as part of the - query to return extended information including IDs for values and dictionaries. - in: query - name: responseFormat - schema: - $ref: "#/components/schemas/ResponseFormat" - - description: Unique identifier (accession) of the object. - in: path - name: id - required: true - schema: - type: string - - description: |- - Specify which versions of omics data files are used in the query. By default the active version is used. See Versioning above. Syntax: - - \* or `v` or ``:`v` or ``:`` - in: query - name: useVersions - schema: - type: string - - description: |- - The parameter defines amount of metadata attributes to return: - - 1. `minimal_data` - return metadata attributes according to the default template. - 2. `extended_data_included` - return metadata attributes according to applied template, if object doesn’t have applied template default template will be used. This is the default for User endpoints. - 3. `original_data_included` - return all metadata attributes with values and null attributes, if they are present in the applied template. This is the default for Curator endpoints. - in: query - name: returnedMetadataFields - schema: - enum: - - minimal_data - - extended_data_included - - original_data_included - type: string - responses: - "200": - content: - application/json: - schema: - items: - $ref: "#/components/schemas/MetadataWithId" - type: array - description: The request was successful. The returned value is the object. - "400": - content: {} - description: The supplied object ID is invalid. - "401": - content: {} - description: |- - User is not authenticated. Please supply a valid Access Token in the `Authorization` HTTP header (e.g. Authorization: bearer [token]) - or Genestack API token in the `Genestack-API-Token` header (this token may be obtained from the Genestack UI _Profile_ page). - "500": - content: {} - description: "An internal server error occurred. This indicates an unexpected\ - \ failure in the Genestack system, please file a bug report to support@genestack.com,\ - \ including the error details." - security: - - Access-token: [] - - Genestack-API-Token: [] - summary: Retrieve group metadata by querying study ID (accession) - tags: - - Variant integration as User - /api/v1/as-user/integration/link/variant/run-to-samples/by/group/{id}: - get: - description: |+ - ## Paging - For performance reasons this endpoint returns results in "pages" of limited size. In order to retrieve all matching results the client needs to request multiple pages starting from an offset to the first result. You can do this using the pageOffset query parameter. A value of 0 (the default) instructs the server to return the first page of results, 100 would return a page of results starting from the 101st result and so on. To retrieve all results, iterate through pages using `pageOffset` values of `n * pageLimit` until a page returns fewer results than the page limit, which indicates there are no more results. - - operationId: getVariantRunToSamplePairsAsUser - parameters: - - description: Unique identifier (accession) of the object. - in: path - name: id - required: true - schema: - type: string - - description: Maximum number of results to return. This value must be between - 0 and 2000 (inclusive). - in: query - name: pageLimit - schema: - format: int32 - type: integer - - description: "Show the page {pageOffset+1} results from the start of the results.\ - \ E.g. 100 will show a page of results starting from the 101st result.\ - \ The default value is 0." - in: query - name: pageOffset - schema: - format: int32 - type: integer - responses: - "200": - content: - application/json: - schema: - $ref: "#/components/schemas/ListResponse" - description: The request was successful. The returned value is a list of - objects. - "400": - content: {} - description: Entities cannot be retrieved. - "401": - content: {} - description: |- - User is not authenticated. Please supply a valid Access Token in the `Authorization` HTTP header (e.g. Authorization: bearer [token]) - or Genestack API token in the `Genestack-API-Token` header (this token may be obtained from the Genestack UI _Profile_ page). - "404": - content: {} - description: No object exists with the given ID. - "500": - content: {} - description: "An internal server error occurred. This indicates an unexpected\ - \ failure in the Genestack system, please file a bug report to support@genestack.com,\ - \ including the error details." - security: - - Access-token: [] - - Genestack-API-Token: [] - summary: "Retrieve run-sample pairs by group id. Pagination is based on unique\ - \ runs, not unique pairs." - tags: - - Variant integration as User - /api/v1/as-user/links: - get: - description: Please make sure that this endpoint should be used only for getting - all links to a specific object. In case you specify both firstId and secondId - an expected answer would be true for existing links and false for no link - between the objects. - operationId: getLinksByParamsAsUser - parameters: - - description: Object ID (accession) (e.g. accession of study) - in: query - name: firstId - required: true - schema: - type: string - - description: Type of the object (e.g. study) - in: query - name: firstType - schema: - type: string - - description: Object ID (accession) (e.g. accession of study) - in: query - name: secondId - schema: - type: string - - description: Type of the object (e.g. study) - in: query - name: secondType - schema: - type: string - - description: Param says to skip that many links before beginning to return - links. - in: query - name: offset - schema: - default: 0 - format: int32 - type: integer - - description: Param says to limit the count of returned links. - in: query - name: limit - schema: - default: 1000 - format: int32 - type: integer - responses: - "200": - content: - application/json: - schema: - $ref: "#/components/schemas/ListResponse" - description: The request was successful. The returned value is a list of - objects. - "400": - content: {} - description: Entities cannot be retrieved. - "401": - content: {} - description: |- - User is not authenticated. Please supply a valid Access Token in the `Authorization` HTTP header (e.g. Authorization: bearer [token]) - or Genestack API token in the `Genestack-API-Token` header (this token may be obtained from the Genestack UI _Profile_ page). - "500": - content: {} - description: "An internal server error occurred. This indicates an unexpected\ - \ failure in the Genestack system, please file a bug report to support@genestack.com,\ - \ including the error details." - security: - - Access-token: [] - - Genestack-API-Token: [] - summary: Finds existing links matching the specified criteria. - tags: - - Linkage as User - /api/v1/as-user/links/get-batch: - post: - description: Please make sure to use that endpoint for batch calls only. You - are not allowed to pass 'mixed' objects. e.g. Studies and Samples at the same - time. Please always specify firstType. - operationId: getLinksByIdsAsUser - requestBody: - content: - application/json: - schema: - $ref: "#/components/schemas/BatchOfIds" - required: false - responses: - "200": - content: - application/json: - schema: - $ref: "#/components/schemas/ListResponse" - description: The request was successful. The returned value is a list of - objects. - "400": - content: {} - description: Entities cannot be retrieved. - "401": - content: {} - description: |- - User is not authenticated. Please supply a valid Access Token in the `Authorization` HTTP header (e.g. Authorization: bearer [token]) - or Genestack API token in the `Genestack-API-Token` header (this token may be obtained from the Genestack UI _Profile_ page). - "500": - content: {} - description: "An internal server error occurred. This indicates an unexpected\ - \ failure in the Genestack system, please file a bug report to support@genestack.com,\ - \ including the error details." - security: - - Access-token: [] - - Genestack-API-Token: [] - summary: "Finds existing links by passing many IDs. \nPagination goes through\ - \ all links matched the criteria." - tags: - - Linkage as User - x-codegen-request-body-name: request - /api/v1/as-user/omics/cells: - get: - description: |- - Retrieve cell objects whose linked data matches all supplied conditions. - - ## Conditions - It is possible to supply conditions for: - 1. Parent studies (full-text or metadata key-value pair) - 2. Samples (full-text or metadata key-value pair) - 3. Libraries (full-text or metadata key-value pair) - 4. Preparations (full-text or metadata key-value pair) - - ## Metadata full-text queries - Single words can be supplied as is; otherwise, use speech marks (`"`) to quote queries that include whitespace. Speech marks and backslash characters in the query need to be escaped with a backslash (`\`). - - ## Metadata filters - Metadata filters are key-value pairs joined by an operator. The `=` operator matches literal values/string. The `!=` operator matches anything except the literal value/string. The `<` or `>` operators match numerical results that are less or greater than the supplied value. Strings containing whitespace need to be quoted with (`"`). - - ## Data queries - Data queries must be a list of key-value pairs, separated by whitespace. The set of valid keys depends on the specific query type, and is documented in the query parameter summary. The values can be simple non-whitespace strings, or strings enclosed by speech marks (`"`). Depending on the key, the value may be be a comma-delimited list of string values. Others require numerical values. - - ## Combinations - Metadata queries/filters for the same parameter can be combined with `&&`, `AND`, `||` and `OR` operators, using white-space to separate out the terms and operators. Parentheses `( )` can be used for complex expressions. - - ## Paging - For performance reasons this endpoint returns results in "pages" of limited size together with a `cursor` tag. To retrieve the next page of results please supply this `cursor` tag to resume the query from your previous result and get the next page. If there are no more results you will just retrieve an empty result. - operationId: omicsSearchCellsAsUser - parameters: - - description: | - Filter by study metadata (key-value metadata pair(s)). E.g. `"Study Source"=ArrayExpress` - in: query - name: studyFilter - schema: - type: string - - description: | - Search for objects via a full-text query over all study metadata fields. E.g. `RNA-Seq of human dendritic cells`. Queries matching dictionary terms are automatically expanded to include synonyms. - in: query - name: studyQuery - schema: - type: string - - description: | - Filter by sample metadata (key-value metadata pair(s)). E.g. `"Species or strain"="Homo sapiens"` - in: query - name: sampleFilter - schema: - type: string - - description: | - Search for objects via a full-text query over all sample metadata fields. E.g. `Clozapine`. Queries matching dictionary terms are automatically expanded to include synonyms. - in: query - name: sampleQuery - schema: - type: string - - description: | - Filter by library metadata (key-value metadata pair(s)). E.g. `"Library Type"=RNA-Seq-1` - in: query - name: libraryFilter - schema: - type: string - - description: | - Search for library objects via a full-text query over all library metadata fields. E.g. `illumina HiSeq500`. Queries matching dictionary terms are automatically expanded to include synonyms. - in: query - name: libraryQuery - schema: - type: string - - description: | - Filter by preparation metadata (key-value metadata pair(s)). E.g. `Digestion=Trypsin` - in: query - name: preparationFilter - schema: - type: string - - description: | - Search for preparation objects via a full-text query over all preparation metadata fields. E.g. `reversed-phase liquid chromatography`. Queries matching dictionary terms are automatically expanded to include synonyms. - in: query - name: preparationQuery - schema: - type: string - - description: |- - If the full-text query term is present in an ODM dictionary, enabling this parameter will modify the query to include child terms of the full-text query. - - For example, the search query "Body fluid" can be expanded to include the term "Blood" (a child term of "Body fluid") so files containing either "Body fluid" or "Blood" in their metadata will be returned in the search results. - - The parent-child relationship is defined by the key "broaders" or "subClassOf" in the dictionary. - - If the full query term is not present in a dictionary then this parameter has no effect. - in: query - name: searchSpecificTerms - schema: - type: boolean - - description: |- - Search for cells by their metadata attributes. The following attributes are supported: - 1. Strings: `barcode`, `batch`, `cellType`, `cluster`, and all custom attributes. - 2. Integers: `nCounts` - 3. Floats: `percentMito` - 4. Float coordinates: `UMAP`, `PCA`. - 5. All other attributes are considered to be custom and stored as string data type. - - To use filters for cell metadata objects use the following query types: - 1. By key=value pair for attributes. Single words can be supplied as is; otherwise, use speech marks (`"`) to quote queries that include whitespace: `cellType=T_cell`, `batch="PBMC batch 01"` - quote values that include spaces, `nCounts=3000`, `custom_attribute="disease"` - custom attribute with string data type. - 2. It is possible to specify a set of possible values, separated by comma: `cellType=Macrophage,Monocyte`. - 3. Utilize range filters to search numeric attributes. Apply `<` (less than), `>` (greater than), and `=` (equal to) symbols to specify the desired ranges as follows: `nCounts > 2000`, `-3 < percentMito < 10`. To retrieve UMAP or PCA values use `umap.1`, `umap.2`, `pca.1`, `pca.2`, e.g. `umap.1 > 0.5`. - 4. Use substring search to get the records where the attribute field contains the provided substring: `cellType =~ "B cell"`. - 5. Combine multiple filters for different feature attributes and measurements using `AND` (`&&`), `OR` (`||`), `NOT` (`!`) logical operators and parentheses: - * `NOT cellType=Erythrocyte` or `cellType!=B_cell,T_cell`: exclude objects with defined values from search. - * `batch=BatchA && percentMito<0.8` or `batch=BatchA AND percentMito<8`: select all objects with BatchA and percentMito less than 0.8. - * `cluster=1 || cluster=2` or `cluster=1 OR cluster=2`: select all objects where cluster 1 or 2. - * `percentMito>0.2 && nCounts>=1000`: select all objects where percentMito is greater than 0.2 and nCounts is more or equal to 1000. - * `batch=BatchA && (cluster=3 || -3 < percentMito < 8)`: combine logical operators in one query. - - in: query - name: cellQuery - schema: - type: string - - description: "Search for objects linked to cell expression data and originally\ - \ uploaded in TSV format via data query, e.g., `feature=ENSG00000230368,ENSG00000188976\ - \ value>=1.50`\n For the case when the original data is represented by multiple\ - \ attributes per feature scenarios, extended filtering syntax is as follows:\ - \ \n1. By feature attribute value for numeric and string attributes: `feature.NAME=1007_s_at`\ - \ or `feature.\"Average Mz\"=2.218`. As in the case of sample metadata queries,\ - \ single words can be supplied as is; otherwise, use speech marks (`\"`)\ - \ to quote queries that include whitespace. \n2. It is possible to specify\ - \ a set of possible values, separated by comma: `feature.NAME=1007_s_at,121_at`.\ - \ \n3. Utilize range filters to search numeric attributes. Apply `<` (less\ - \ than), `>` (greater than), and `=` (equal to) symbols to specify the desired\ - \ ranges as follows: \n`feature.Name_1 > 3`: Select all rows where the feature\ - \ attribute Name_1 values are greater than 3. \n`feature.Name_2 >= 6`: Select\ - \ all rows where the feature attribute Name_2 values are greater than or\ - \ equal to 6. \n`-3 < feature.Name_3 < 3`: Select all rows where the feature\ - \ attribute Name_3 values lie within the interval between -3 and 3. \n4.\ - \ Use substring search to get the records where the attribute field contains\ - \ the provided substring: `feature.attribute1 =~ \"some text\"`. \n5. The\ - \ first column for each original data file is identified as feature accession\ - \ (typically, it contains gene or protein names, accession IDs, etc.). Searching\ - \ by such feature accession would significantly outperform more complex\ - \ queries by combining the other feature attributes. To enable such a search,\ - \ use `feature` without any attribute extension, e.g., `feature=ENSG00000230368,ENSG00000188976`.\n\ - \ \nThe `value` keyword can be used to select rows where the cell - \ measurements has values from a certain range. Examples:\ - \ `value = 3`, `value > 3`, `-3 < value < 3`.\n - \ \nCombine multiple filters for different feature attributes and measurements\ - \ using `AND` (`&&`), `OR` (`||`), `NOT` (`!`) logical operators and parentheses: \n\ - * `NOT feature.Name_1=A`: Select all rows where Name_1 is not A. \n* `feature.Name_1!=A,B,C`:\ - \ Select all rows where Name_1 is not A, B, or C. \n* `feature.Name_1=A\ - \ AND feature.Name_2=B`: Select all rows where Name_1 is A and Name_2 is\ - \ B. \n* `feature.Name_1=A && feature.Name_2=B`: Equivalent to the example\ - \ above. \n* `feature.Name_1=A OR feature.Name_2=B`: Select all rows where\ - \ Name_1 is A or Name_2 is B. \n* `feature.Name_1=A || feature.Name_2=B`:\ - \ Equivalent to the example above. \n* `feature.Name_1=A AND (feature.Name_2=B\ - \ OR value>=1.0)`: Select all rows where Name_1 is A and either Name_2 is\ - \ B or minimal possible measurement value is 1.0." - in: query - name: exQuery - schema: - type: string - - description: "Filter by expression metadata (key-value metadata pair(s)).\ - \ E.g. `\"Genome Version\"=hg19-BROAD`." - in: query - name: exFilter - schema: - type: string - - description: The page tag to resume results from (see paging above). - in: query - name: cursor - schema: - type: string - - description: This parameter determines the number of results to retrieve per page, with the default set at 2000. - in: query - name: pageLimit - schema: - format: int32 - type: integer - responses: - "200": - content: - application/json: - schema: - $ref: "#/components/schemas/OmicsResponse" - description: Omics query result. - "400": - content: { } - description: Invalid data in request. See error message for details. - "401": - content: { } - description: |- - User is not authenticated. Please supply a valid Access Token in the `Authorization` HTTP header (e.g. Authorization: bearer [token]) - or Genestack API token in the `Genestack-API-Token` header (this token may be obtained from the Genestack UI _Profile_ page). - "500": - content: { } - description: "An internal server error occurred. This indicates an unexpected\ - \ failure in the Genestack system, please file a bug report to support@genestack.com,\ - \ including the error details." - security: - - Access-token: [ ] - - Genestack-API-Token: [ ] - summary: Retrieve Cell objects by searching across multiple data types - tags: - - Omics queries as User - /api/v1/as-user/omics/cells/expression/data: - get: - description: |- - Retrieve cell expression objects by searching across multiple metadata types. - - ## Conditions - It is possible to supply conditions for: - 1. Parent studies (full-text or metadata key-value pair) - 2. Samples (full-text or metadata key-value pair) - 3. Libraries (full-text or metadata key-value pair) - 4. Preparations (full-text or metadata key-value pair) - - ## Metadata full-text queries - Single words can be supplied as is; otherwise, use speech marks (`"`) to quote queries that include whitespace. Speech marks and backslash characters in the query need to be escaped with a backslash (`\`). - - ## Metadata filters - Metadata filters are key-value pairs joined by an operator. The `=` operator matches literal values/string. The `!=` operator matches anything except the literal value/string. The `<` or `>` operators match numerical results that are less or greater than the supplied value. Strings containing whitespace need to be quoted with (`"`). - - ## Data queries - Data queries must be a list of key-value pairs, separated by whitespace. The set of valid keys depends on the specific query type, and is documented in the query parameter summary. The values can be simple non-whitespace strings, or strings enclosed by speech marks (`"`). Depending on the key, the value may be be a comma-delimited list of string values. Others require numerical values. - - ## Combinations - Metadata queries/filters for the same parameter can be combined with `&&`, `AND`, `||` and `OR` operators, using white-space to separate out the terms and operators. Parentheses `( )` can be used for complex expressions. - - ## Paging - For performance reasons this endpoint returns results in "pages" of limited size together with a `cursor` tag. To retrieve the next page of results please supply this `cursor` tag to resume the query from your previous result and get the next page. If there are no more results you will just retrieve an empty result. - operationId: omicsSearchCellsExpressionDataAsUser - parameters: - - description: | - Filter by study metadata (key-value metadata pair(s)). E.g. `"Study Source"=ArrayExpress` - in: query - name: studyFilter - schema: - type: string - - description: Search for objects via a full-text query over all study metadata - fields. E.g. `"RNA-Seq of human dendritic cells"`. Queries matching dictionary - terms are automatically expanded to include synonyms. - in: query - name: studyQuery - schema: - type: string - - description: | - Filter by sample metadata (key-value metadata pair(s)). E.g. `"Species or strain"="Homo sapiens"` - in: query - name: sampleFilter - schema: - type: string - - description: Search for objects via a full-text query over all sample metadata - fields. E.g. `Clozapine`. Queries matching dictionary terms are automatically - expanded to include synonyms. - in: query - name: sampleQuery - schema: - type: string - - description: Filter by library metadata (key-value metadata pair(s)). E.g. - `"Library Type"=RNA-Seq-1` - in: query - name: libraryFilter - schema: - type: string - - description: Search for library objects via a full-text query over all library - metadata fields. E.g. `"illumina HiSeq500"`. Queries matching dictionary - terms are automatically expanded to include synonyms. - in: query - name: libraryQuery - schema: - type: string - - description: Filter by preparation metadata (key-value metadata pair(s)). - E.g. `Digestion=Trypsin` - in: query - name: preparationFilter - schema: - type: string - - description: Search for preparation objects via a full-text query over all - preparation metadata fields. E.g. `"reversed-phase liquid chromatography"`. - Queries matching dictionary terms are automatically expanded to include - synonyms. - in: query - name: preparationQuery - schema: - type: string - - description: |- - Search for cells by their metadata attributes. The following attributes are supported: - 1. Strings: `barcode`, `batch`, `cellType`, `cluster`, and all custom attributes. - 2. Integers: `nCounts` - 3. Floats: `percentMito` - 4. Float coordinates: `UMAP`, `PCA`. - 5. All other attributes are considered to be custom and stored as string data type. - - To use filters for cell metadata objects use the following query types: - 1. By key=value pair for attributes. Single words can be supplied as is; otherwise, use speech marks (`"`) to quote queries that include whitespace: `cellType=T_cell`, `batch="PBMC batch 01"` - quote values that include spaces, `nCounts=3000`, `custom_attribute="disease"` - custom attribute with string data type. - 2. It is possible to specify a set of possible values, separated by comma: `cellType=Macrophage,Monocyte`. - 3. Utilize range filters to search numeric attributes. Apply `<` (less than), `>` (greater than), and `=` (equal to) symbols to specify the desired ranges as follows: `nCounts > 2000`, `-3 < percentMito < 10`. To retrieve UMAP or PCA values use `umap.1`, `umap.2`, `pca.1`, `pca.2`, e.g. `umap.1 > 0.5`. - 4. Use substring search to get the records where the attribute field contains the provided substring: `cellType =~ "B cell"`. - 5. Combine multiple filters for different feature attributes and measurements using `AND` (`&&`), `OR` (`||`), `NOT` (`!`) logical operators and parentheses: - * `NOT cellType=Erythrocyte` or `cellType!=B_cell,T_cell`: exclude objects with defined values from search. - * `batch=BatchA && percentMito<0.8` or `batch=BatchA AND percentMito<8`: select all objects with BatchA and percentMito less than 0.8. - * `cluster=1 || cluster=2` or `cluster=1 OR cluster=2`: select all objects where cluster 1 or 2. - * `percentMito>0.2 && nCounts>=1000`: select all objects where percentMito is greater than 0.2 and nCounts is more or equal to 1000. - * `batch=BatchA && (cluster=3 || -3 < percentMito < 8)`: combine logical operators in one query. - in: query - name: cellQuery - schema: - type: string - - description: "Search for objects linked to expression data and originally\ - \ uploaded in TSV or GCT format via data query, e.g., `feature=ENSG00000230368,ENSG00000188976\ - \ value>=1.50`\n For the case when the original data is represented by multiple\ - \ attributes per feature scenarios, extended filtering syntax is as follows:\ - \ \n1. By feature attribute value for numeric and string attributes: `feature.NAME=1007_s_at`\ - \ or `feature.\"Average Mz\"=2.218`. As in the case of sample metadata queries,\ - \ single words can be supplied as is; otherwise, use speech marks (`\"`)\ - \ to quote queries that include whitespace. \n2. It is possible to specify\ - \ a set of possible values, separated by comma: `feature.NAME=1007_s_at,121_at`.\ - \ \n3. Utilize range filters to search numeric attributes. Apply `<` (less\ - \ than), `>` (greater than), and `=` (equal to) symbols to specify the desired\ - \ ranges as follows: \n`feature.Name_1 > 3`: Select all rows where the feature\ - \ attribute Name_1 values are greater than 3. \n`feature.Name_2 >= 6`: Select\ - \ all rows where the feature attribute Name_2 values are greater than or\ - \ equal to 6. \n`-3 < feature.Name_3 < 3`: Select all rows where the feature\ - \ attribute Name_3 values lie within the interval between -3 and 3. \n4.\ - \ Use substring search to get the records where the attribute field contains\ - \ the provided substring: `feature.attribute1 =~ \"some text\"`. \n5. The\ - \ first column for each original data file is identified as feature accession\ - \ (typically, it contains gene or protein names, accession IDs, etc.). Searching\ - \ by such feature accession would significantly outperform more complex\ - \ queries by combining the other feature attributes. To enable such a search,\ - \ use `feature` without any attribute extension, e.g., `feature=ENSG00000230368,ENSG00000188976`.\n\ - \ \nThe `value` keyword can be used to select rows where the sample (library\ - \ or preparation) measurements has values from a certain range. Examples:\ - \ `value = 3`, `value > 3`, `-3 < value < 3`. When the original data contains\ - \ multiple measurements for a single item, such as a sample (library or\ - \ preparation), use the measurement name to specify the exact column type,\ - \ e.g.: \n1. `value.intensity = 3`: Selects all rows where the measurement\ - \ attribute intensity equals 3. \n `value.intensity != 2,null`: Select all\ - \ rows where the measurement attribute intensity is not equal 2 and is not\ - \ an empty value. \n`value.p_value > 3`: Selects all rows where the measurement\ - \ attribute 'p_value' values are greater than 3. \n`-3 < value.FC < 3`:\ - \ Selects all rows where the measurement attribute 'FC' values lie within\ - \ the interval between -3 and 3.\n \n2. Note: The `MinValue` keyword has\ - \ been deprecated and should be replaced with the aforementioned comparisons.\n\ - \ \nCombine multiple filters for different feature attributes and measurements\ - \ using `AND` (`&&`), `OR` (`||`), `NOT` (`!`) logical operators and parentheses: \n\ - * `NOT feature.Name_1=A`: Select all rows where Name_1 is not A. \n* `feature.Name_1!=A,B,C`:\ - \ Select all rows where Name_1 is not A, B, or C. \n* `feature.Name_1=A\ - \ AND feature.Name_2=B`: Select all rows where Name_1 is A and Name_2 is\ - \ B. \n* `feature.Name_1=A && feature.Name_2=B`: Equivalent to the example\ - \ above. \n* `feature.Name_1=A OR feature.Name_2=B`: Select all rows where\ - \ Name_1 is A or Name_2 is B. \n* `feature.Name_1=A || feature.Name_2=B`:\ - \ Equivalent to the example above. \n* `feature.Name_1=A AND (feature.Name_2=B\ - \ OR value>=1.0)`: Select all rows where Name_1 is A and either Name_2 is\ - \ B or minimal possible measurement value is 1.0." - in: query - name: exQuery - schema: - type: string - - description: "Filter by expression metadata (key-value metadata pair(s)).\ - \ E.g. `\"Genome Version\"=hg19-BROAD`." - in: query - name: exFilter - schema: - type: string - - description: |- - If the full-text query term is present in an ODM dictionary, enabling this parameter will modify the query to include child terms of the full-text query. - - For example, the search query "Body fluid" can be expanded to include the term "Blood" (a child term of "Body fluid") so files containing either "Body fluid" or "Blood" in their metadata will be returned in the search results. - - The parent-child relationship is defined by the key "broaders" or "subClassOf" in the dictionary. - - If the full query term is not present in a dictionary then this parameter has no effect. - in: query - name: searchSpecificTerms - schema: - type: boolean - - description: The page tag to resume results from (see paging above). - in: query - name: cursor - schema: - type: string - - description: "This parameter determines the number of results to retrieve\ - \ per page, with the default set at 2000." - in: query - name: pageLimit - schema: - format: int32 - type: integer - responses: - "200": - content: - application/json: - schema: - $ref: "#/components/schemas/OmicsResponse" - description: Omics query result. - "400": - content: { } - description: Invalid data in request. See error message for details. - "401": - content: { } - description: |- - User is not authenticated. Please supply a valid Access Token in the `Authorization` HTTP header (e.g. Authorization: bearer [token]) - or Genestack API token in the `Genestack-API-Token` header (this token may be obtained from the Genestack UI _Profile_ page). - "500": - content: { } - description: "An internal server error occurred. This indicates an unexpected\ - \ failure in the Genestack system, please file a bug report to support@genestack.com,\ - \ including the error details." - security: - - Access-token: [ ] - - Genestack-API-Token: [ ] - summary: Retrieve cell expression objects by searching across multiple metadata types - tags: - - Omics queries as User - /api/v1/as-user/omics/expression/data: - get: - description: "Retrieve any data objects whose linked data matches all supplied\ - \ conditions.This endpoint does not support search by expression linked to Cell\ - \ group. Use /omics/cells/expression/data endpoint for search by Cell expression.\ - \n\nNote: An expression data query must be supplied.\n\n## Conditions\n\ - It is possible to supply conditions for:\n\n1. Samples (full-text or metadata\ - \ key-value pair)\n2. Parent studies (full-text or metadata key-value pair)\n\ - 3. Linked variant objects (list of data key-value pairs)\n4. Linked flow cytometry\ - \ objects (list of data key-value pairs)\n5. Linked any data (except variant\ - \ and flow cytometry) objects (list of data key-value pairs)\n\n## Metadata\ - \ full-text queries\nSingle words can be supplied as is; otherwise, use speech\ - \ marks (`\"`) to quote queries that include whitespace. Speech marks and\ - \ backslash characters in the query need to be escaped with a backslash (`\\\ - `).\n\n## Metadata filters\nMetadata filters are key-value pairs joined by\ - \ an operator. The `=` operator matches literal values/string. The `!=` operator\ - \ matches anything except the literal value/string. The `<` or `>` operators\ - \ match numerical results that are less or greater than the supplied value.\ - \ Strings containing whitespace need to be quoted with (`\"`).\n\n## Data\ - \ queries\nData queries must be a list of key-value pairs, separated by whitespace.\ - \ The set of valid keys depends on the specific query type, and is documented\ - \ in the query parameter summary. The values can be simple non-whitespace\ - \ strings, or strings enclosed by speech marks (`\"`). Depending on the key,\ - \ the value may be be a comma-delimited list of string values. Others require\ - \ numerical values.\n\n## Combinations\nMetadata queries/filters for the same parameter\ - \ can be combined with `&&`, `AND`, `||` and `OR` operators, using white-space\ - \ to separate out the terms and operators. Parentheses `( )` can be used for\ - \ complex expressions.\n\n## Versioning\nSpecific versions of omics data files\ - \ (eg. GCT) can be queried via the useVersions parameter. Different versions\ - \ of an omics data file are associated via their CHAIN_ID metadata value.\ - \ This CHAIN_ID can be supplied to the useVersions parameter along with the\ - \ version number or specific omics data file accessions to include them in\ - \ the query. If nothing is supplied to the useVersions parameter then only\ - \ the active version (which is usually the last one imported) is queried.\ - \ This acts as a filter before the rest of the query is carried out.\n\nExample\ - \ usage:\nuseVersions=* (query all versions, including those without CHAIN_IDs)\n\ - useVersions=v2 (query the second version. If there is no second version then\ - \ the data file is not queried)\nuseVersions=v1,v0 (query the first version\ - \ and any data files without CHAIN_IDs(v0) )\nuseVersions=GSVC002:v3 (for\ - \ omics data files with a CHAIN_ID of GSCV002 query the third version)\nuseVersions=GSVC002:GSF00494,GSF000496\ - \ (for omics data files with a CHAIN_ID of GSCV002 query only the specific\ - \ accessions GSF00494 and GSF000496)\n\nRules for multiple CHAIN_IDs can be\ - \ supplied to the parameter using the ; separator.\n\n## Paging\nFor performance\ - \ reasons this endpoint returns results in \"pages\" of limited size together\ - \ with a `cursor` tag. To retrieve the next page of results please supply\ - \ this `cursor` tag to resume the query from your previous result and get\ - \ the next page. To return all results iterate through pages using cursor \ - \ values until the `resultsExhausted` response field is true.\n\n" - operationId: omicsSearchExpressionDataAsUser - parameters: - - description: Supply this parameter with the value `term_id` as part of the - query to return extended information including IDs for values and dictionaries. - in: query - name: responseFormat - schema: - $ref: "#/components/schemas/ResponseFormat" - - description: | - Filter by study metadata (key-value metadata pair(s)). E.g. `"Study Source"=ArrayExpress` - in: query - name: studyFilter - schema: - type: string - - description: Search for objects via a full-text query over all study metadata - fields. E.g. `"RNA-Seq of human dendritic cells"`. Queries matching dictionary - terms are automatically expanded to include synonyms. - in: query - name: studyQuery - schema: - type: string - - description: | - Filter by sample metadata (key-value metadata pair(s)). E.g. `"Species or strain"="Homo sapiens"` - in: query - name: sampleFilter - schema: - type: string - - description: Search for objects via a full-text query over all sample metadata - fields. E.g. `Clozapine`. Queries matching dictionary terms are automatically - expanded to include synonyms. - in: query - name: sampleQuery - schema: - type: string - - description: Filter by library metadata (key-value metadata pair(s)). E.g. - `"Library Type"=RNA-Seq-1` - in: query - name: libraryFilter - schema: - type: string - - description: Search for library objects via a full-text query over all library - metadata fields. E.g. `"illumina HiSeq500"`. Queries matching dictionary - terms are automatically expanded to include synonyms. - in: query - name: libraryQuery - schema: - type: string - - description: Filter by preparation metadata (key-value metadata pair(s)). - E.g. `Digestion=Trypsin` - in: query - name: preparationFilter - schema: - type: string - - description: Search for preparation objects via a full-text query over all - preparation metadata fields. E.g. `"reversed-phase liquid chromatography"`. - Queries matching dictionary terms are automatically expanded to include - synonyms. - in: query - name: preparationQuery - schema: - type: string - - description: |- - If the full-text query term is present in an ODM dictionary, enabling this parameter will modify the query to include child terms of the full-text query. - - For example, the search query "Body fluid" can be expanded to include the term "Blood" (a child term of "Body fluid") so files containing either "Body fluid" or "Blood" in their metadata will be returned in the search results. - - The parent-child relationship is defined by the key "broaders" or "subClassOf" in the dictionary. - - If the full query term is not present in a dictionary then this parameter has no effect. - in: query - name: searchSpecificTerms - schema: - type: boolean - - description: "Search for objects linked to variant data by SNPs properties. Filtering is currently supported by `filter`, `id`, `region` and `info` keywords, - as well as `exists` keyword for `INFO` field and their logical combinations by means of `not` (`!`), `and` (`&&`), and `or` (`||`) operators with standard boolean precedence. Keyword case is ignored.\n - * `filter` corresponds to the `FILTER` column in the original vcf file. Could be either equals or not equals to `PASS` : `filter = PASS` - or `filter != pass`.\n - * `id` is a string value that corresponds to the `ID` column. Multiple values could be added via a comma. Expression `id = rs3214,rg1234` is equivalent - to `id = rs3214 or id = rg1234`.\n - * `region` corresponds to CHROM and POS columns. Supports querying by the whole chromosome `region = chr1` , by interval within a chromosome - `region = chr1:4567-9876543` by exact position `region = chr1:456789` or by indefinite ranges like `region = x:3456789-*` . Multiple regions could be - separated via comma, e.g. `region = chr1:34567-98767,chr3` is equivalent to `region = chr1:34567-98767 or region = chr3`.\n - * `feature` is the name of the reference gene associated with a specific location in the reference genome which corresponds to the VCF file (variant group) from which the variant information is derived. - By providing the gene name(s), such as `feature=TP53` or `feature=TP53,TGFB`, variants located within the same genomic region as the specified gene(s) will be retrieved.\n - * Filter by vcf `INFO` fields. E.g. to filter all variants annotated in dbSNP add `exists(INFO.KEY)`. Use `!exists(INFO.KEY)` to exclude variants having the key from the search results. - Provide `info.key=value` pair to search for an exact match or `info.key!=value` to exclude it from the search. Due to the limits of precision in floating point numbers, - we use a small range of 0.0000001 to identify close matches. This means any differences smaller than that won't be detected. For more precise results, please use range queries." - in: query - name: vxQuery - schema: - type: string - - description: "Filter by variant metadata (key-value metadata pair(s)). E.g.\ - \ `\"Variant Source\"=dbSNP`." - in: query - name: vxFilter - schema: - type: string - - description: "Search for objects linked to expression data and originally\ - \ uploaded in TSV or GCT format via data query, e.g., `feature=ENSG00000230368,ENSG00000188976\ - \ value>=1.50`\n For the case when the original data is represented by multiple\ - \ attributes per feature scenarios, extended filtering syntax is as follows:\ - \ \n1. By feature attribute value for numeric and string attributes: `feature.NAME=1007_s_at`\ - \ or `feature.\"Average Mz\"=2.218`. As in the case of sample metadata queries,\ - \ single words can be supplied as is; otherwise, use speech marks (`\"`)\ - \ to quote queries that include whitespace. \n2. It is possible to specify\ - \ a set of possible values, separated by comma: `feature.NAME=1007_s_at,121_at`.\ - \ \n3. Utilize range filters to search numeric attributes. Apply `<` (less\ - \ than), `>` (greater than), and `=` (equal to) symbols to specify the desired\ - \ ranges as follows: \n`feature.Name_1 > 3`: Select all rows where the feature\ - \ attribute Name_1 values are greater than 3. \n`feature.Name_2 >= 6`: Select\ - \ all rows where the feature attribute Name_2 values are greater than or\ - \ equal to 6. \n`-3 < feature.Name_3 < 3`: Select all rows where the feature\ - \ attribute Name_3 values lie within the interval between -3 and 3. \n4.\ - \ Use substring search to get the records where the attribute field contains\ - \ the provided substring: `feature.attribute1 =~ \"some text\"`. \n5. The\ - \ first column for each original data file is identified as feature accession\ - \ (typically, it contains gene or protein names, accession IDs, etc.). Searching\ - \ by such feature accession would significantly outperform more complex\ - \ queries by combining the other feature attributes. To enable such a search,\ - \ use `feature` without any attribute extension, e.g., `feature=ENSG00000230368,ENSG00000188976`.\n\ - \ \nThe `value` keyword can be used to select rows where the sample (library\ - \ or preparation) measurements has values from a certain range. Examples:\ - \ `value = 3`, `value > 3`, `-3 < value < 3`. When the original data contains\ - \ multiple measurements for a single item, such as a sample (library or\ - \ preparation), use the measurement name to specify the exact column type,\ - \ e.g.: \n1. `value.intensity = 3`: Selects all rows where the measurement\ - \ attribute intensity equals 3. \n `value.intensity != 2,null`: Select all\ - \ rows where the measurement attribute intensity is not equal 2 and is not\ - \ an empty value. \n`value.p_value > 3`: Selects all rows where the measurement\ - \ attribute 'p_value' values are greater than 3. \n`-3 < value.FC < 3`:\ - \ Selects all rows where the measurement attribute 'FC' values lie within\ - \ the interval between -3 and 3.\n \n2. Note: The `MinValue` keyword has\ - \ been deprecated and should be replaced with the aforementioned comparisons.\n\ - \ \nCombine multiple filters for different feature attributes and measurements\ - \ using `AND` (`&&`), `OR` (`||`), `NOT` (`!`) logical operators and parentheses: \n\ - * `NOT feature.Name_1=A`: Select all rows where Name_1 is not A. \n* `feature.Name_1!=A,B,C`:\ - \ Select all rows where Name_1 is not A, B, or C. \n* `feature.Name_1=A\ - \ AND feature.Name_2=B`: Select all rows where Name_1 is A and Name_2 is\ - \ B. \n* `feature.Name_1=A && feature.Name_2=B`: Equivalent to the example\ - \ above. \n* `feature.Name_1=A OR feature.Name_2=B`: Select all rows where\ - \ Name_1 is A or Name_2 is B. \n* `feature.Name_1=A || feature.Name_2=B`:\ - \ Equivalent to the example above. \n* `feature.Name_1=A AND (feature.Name_2=B\ - \ OR value>=1.0)`: Select all rows where Name_1 is A and either Name_2 is\ - \ B or minimal possible measurement value is 1.0." - in: query - name: exQuery - schema: - type: string - - description: "Filter by expression metadata (key-value metadata pair(s)).\ - \ E.g. `\"Genome Version\"=hg19-BROAD`." - in: query - name: exFilter - schema: - type: string - - description: "Search for objects linked to flow cytometry data via data query\ - \ (key-value pair(s)). E.g. `ReadoutType=Median|Count` `CellPopulation=\"\ - CD45+, live\"` `MinValue=3.5`" - in: query - name: fxQuery - schema: - type: string - - description: "Filter by flow cytometry metadata (key-value metadata pair(s)).\ - \ E.g. `Organ=blood`." - in: query - name: fxFilter - schema: - type: string - - description: |- - Specify which versions of omics data files are used in the query. By default the active version is used. See Versioning above. Syntax: - - \* or `v` or ``:`v` or ``:`` - in: query - name: useVersions - schema: - type: string - - description: |- - The parameter defines amount of metadata attributes to return: - - 1. `minimal_data` - return metadata attributes according to the default template. - 2. `extended_data_included` - return metadata attributes according to applied template, if object doesn’t have applied template default template will be used. This is the default for User endpoints. - 3. `original_data_included` - return all metadata attributes with values and null attributes, if they are present in the applied template. This is the default for Curator endpoints. - in: query - name: returnedMetadataFields - schema: - enum: - - minimal_data - - extended_data_included - - original_data_included - type: string - - description: The page tag to resume results from (see paging above). - in: query - name: cursor - schema: - type: string - - description: "This parameter determines the number of results to retrieve\ - \ per page, with the default set at 2000." - in: query - name: pageLimit - schema: - format: int32 - type: integer - responses: - "200": - content: - application/json: - schema: - $ref: "#/components/schemas/OmicsResponse" - description: Omics query result. - "400": - content: {} - description: Invalid data in request. See error message for details. - "401": - content: {} - description: |- - User is not authenticated. Please supply a valid Access Token in the `Authorization` HTTP header (e.g. Authorization: bearer [token]) - or Genestack API token in the `Genestack-API-Token` header (this token may be obtained from the Genestack UI _Profile_ page). - "500": - content: {} - description: "An internal server error occurred. This indicates an unexpected\ - \ failure in the Genestack system, please file a bug report to support@genestack.com,\ - \ including the error details." - security: - - Access-token: [] - - Genestack-API-Token: [] - summary: Retrieve data objects by searching across multiple data types - tags: - - Omics queries as User - /api/v1/as-user/omics/expression/group: - get: - description: |+ - Retrieve group objects whose linked data matches all supplied conditions. - - ## Conditions - It is possible to supply conditions for: - - 1. Samples (full-text or metadata key-value pair) - 2. Parent studies (full-text or metadata key-value pair) - 3. Linked variant objects (list of data key-value pairs) - 4. Linked flow cytometry objects (list of data key-value pairs) - 5. Linked any data (except variant and flow cytometry) objects (list of data key-value pairs) - - ## Metadata full-text queries - Single words can be supplied as is; otherwise, use speech marks (`"`) to quote queries that include whitespace. Speech marks and backslash characters in the query need to be escaped with a backslash (`\`). - - ## Metadata filters - Metadata filters are key-value pairs joined by an operator. The `=` operator matches literal values/string. The `!=` operator matches anything except the literal value/string. The `<` or `>` operators match numerical results that are less or greater than the supplied value. Strings containing whitespace need to be quoted with (`"`). - - ## Data queries - Data queries must be a list of key-value pairs, separated by whitespace. The set of valid keys depends on the specific query type, and is documented in the query parameter summary. The values can be simple non-whitespace strings, or strings enclosed by speech marks (`"`). Depending on the key, the value may be be a comma-delimited list of string values. Others require numerical values. - - ## Combinations - Metadata queries/filters for the same parameter can be combined with `&&`, `AND`, `||` and `OR` operators, using white-space to separate out the terms and operators. Parentheses `( )` can be used for complex expressions. - - ## Versioning - Specific versions of omics data files (eg. GCT) can be queried via the useVersions parameter. Different versions of an omics data file are associated via their CHAIN_ID metadata value. This CHAIN_ID can be supplied to the useVersions parameter along with the version number or specific omics data file accessions to include them in the query. If nothing is supplied to the useVersions parameter then only the active version (which is usually the last one imported) is queried. This acts as a filter before the rest of the query is carried out. - - Example usage: - useVersions=* (query all versions, including those without CHAIN_IDs) - useVersions=v2 (query the second version. If there is no second version then the data file is not queried) - useVersions=v1,v0 (query the first version and any data files without CHAIN_IDs(v0) ) - useVersions=GSVC002:v3 (for omics data files with a CHAIN_ID of GSCV002 query the third version) - useVersions=GSVC002:GSF00494,GSF000496 (for omics data files with a CHAIN_ID of GSCV002 query only the specific accessions GSF00494 and GSF000496) - - Rules for multiple CHAIN_IDs can be supplied to the parameter using the ; separator. - - ## Paging - For performance reasons this endpoint returns results in "pages" of limited size together with a cursor tag. To retrieve the next page of results please supply this cursor tag to resume the query from your previous result and get the next page. If there are no more results you will just retrieve an empty result. To return all results iterate through pages using cursor values until the `resultsExhausted` response field is true. - - operationId: omicsSearchExpressionGroupsAsUser - parameters: - - description: Supply this parameter with the value `term_id` as part of the - query to return extended information including IDs for values and dictionaries. - in: query - name: responseFormat - schema: - $ref: "#/components/schemas/ResponseFormat" - - description: | - Filter by study metadata (key-value metadata pair(s)). E.g. `"Study Source"=ArrayExpress` - in: query - name: studyFilter - schema: - type: string - - description: Search for objects via a full-text query over all study metadata - fields. E.g. `"RNA-Seq of human dendritic cells"`. Queries matching dictionary - terms are automatically expanded to include synonyms. - in: query - name: studyQuery - schema: - type: string - - description: | - Filter by sample metadata (key-value metadata pair(s)). E.g. `"Species or strain"="Homo sapiens"` - in: query - name: sampleFilter - schema: - type: string - - description: Search for objects via a full-text query over all sample metadata - fields. E.g. `Clozapine`. Queries matching dictionary terms are automatically - expanded to include synonyms. - in: query - name: sampleQuery - schema: - type: string - - description: Filter by library metadata (key-value metadata pair(s)). E.g. - `"Library Type"=RNA-Seq-1` - in: query - name: libraryFilter - schema: - type: string - - description: Search for library objects via a full-text query over all library - metadata fields. E.g. `"illumina HiSeq500"`. Queries matching dictionary - terms are automatically expanded to include synonyms. - in: query - name: libraryQuery - schema: - type: string - - description: Filter by preparation metadata (key-value metadata pair(s)). - E.g. `Digestion=Trypsin` - in: query - name: preparationFilter - schema: - type: string - - description: Search for preparation objects via a full-text query over all - preparation metadata fields. E.g. `"reversed-phase liquid chromatography"`. - Queries matching dictionary terms are automatically expanded to include - synonyms. - in: query - name: preparationQuery - schema: - type: string - - description: |- - If the full-text query term is present in an ODM dictionary, enabling this parameter will modify the query to include child terms of the full-text query. - - For example, the search query "Body fluid" can be expanded to include the term "Blood" (a child term of "Body fluid") so files containing either "Body fluid" or "Blood" in their metadata will be returned in the search results. - - The parent-child relationship is defined by the key "broaders" or "subClassOf" in the dictionary. - - If the full query term is not present in a dictionary then this parameter has no effect. - in: query - name: searchSpecificTerms - schema: - type: boolean - - description: "Search for objects linked to variant data by SNPs properties. Filtering is currently supported by `filter`, `id`, `region` and `info` keywords, - as well as `exists` keyword for `INFO` field and their logical combinations by means of `not` (`!`), `and` (`&&`), and `or` (`||`) operators with standard boolean precedence. Keyword case is ignored.\n - * `filter` corresponds to the `FILTER` column in the original vcf file. Could be either equals or not equals to `PASS` : `filter = PASS` - or `filter != pass`.\n - * `id` is a string value that corresponds to the `ID` column. Multiple values could be added via a comma. Expression `id = rs3214,rg1234` is equivalent - to `id = rs3214 or id = rg1234`.\n - * `region` corresponds to CHROM and POS columns. Supports querying by the whole chromosome `region = chr1` , by interval within a chromosome - `region = chr1:4567-9876543` by exact position `region = chr1:456789` or by indefinite ranges like `region = x:3456789-*` . Multiple regions could be - separated via comma, e.g. `region = chr1:34567-98767,chr3` is equivalent to `region = chr1:34567-98767 or region = chr3`.\n - * `feature` is the name of the reference gene associated with a specific location in the reference genome which corresponds to the VCF file (variant group) from which the variant information is derived. - By providing the gene name(s), such as `feature=TP53` or `feature=TP53,TGFB`, variants located within the same genomic region as the specified gene(s) will be retrieved.\n - * Filter by vcf `INFO` fields. E.g. to filter all variants annotated in dbSNP add `exists(INFO.KEY)`. Use `!exists(INFO.KEY)` to exclude variants having the key from the search results. - Provide `info.key=value` pair to search for an exact match or `info.key!=value` to exclude it from the search. Due to the limits of precision in floating point numbers, - we use a small range of 0.0000001 to identify close matches. This means any differences smaller than that won't be detected. For more precise results, please use range queries." - in: query - name: vxQuery - schema: - type: string - - description: "Filter by variant metadata (key-value metadata pair(s)). E.g.\ - \ `\"Variant Source\"=dbSNP`." - in: query - name: vxFilter - schema: - type: string - - description: "Search for objects linked to expression data and originally\ - \ uploaded in TSV or GCT format via data query, e.g., `feature=ENSG00000230368,ENSG00000188976\ - \ value>=1.50`\n For the case when the original data is represented by multiple\ - \ attributes per feature scenarios, extended filtering syntax is as follows:\ - \ \n1. By feature attribute value for numeric and string attributes: `feature.NAME=1007_s_at`\ - \ or `feature.\"Average Mz\"=2.218`. As in the case of sample metadata queries,\ - \ single words can be supplied as is; otherwise, use speech marks (`\"`)\ - \ to quote queries that include whitespace. \n2. It is possible to specify\ - \ a set of possible values, separated by comma: `feature.NAME=1007_s_at,121_at`.\ - \ \n3. Utilize range filters to search numeric attributes. Apply `<` (less\ - \ than), `>` (greater than), and `=` (equal to) symbols to specify the desired\ - \ ranges as follows: \n`feature.Name_1 > 3`: Select all rows where the feature\ - \ attribute Name_1 values are greater than 3. \n`feature.Name_2 >= 6`: Select\ - \ all rows where the feature attribute Name_2 values are greater than or\ - \ equal to 6. \n`-3 < feature.Name_3 < 3`: Select all rows where the feature\ - \ attribute Name_3 values lie within the interval between -3 and 3. \n4.\ - \ Use substring search to get the records where the attribute field contains\ - \ the provided substring: `feature.attribute1 =~ \"some text\"`. \n5. The\ - \ first column for each original data file is identified as feature accession\ - \ (typically, it contains gene or protein names, accession IDs, etc.). Searching\ - \ by such feature accession would significantly outperform more complex\ - \ queries by combining the other feature attributes. To enable such a search,\ - \ use `feature` without any attribute extension, e.g., `feature=ENSG00000230368,ENSG00000188976`.\n\ - \ \nThe `value` keyword can be used to select rows where the sample (library\ - \ or preparation) measurements has values from a certain range. Examples:\ - \ `value = 3`, `value > 3`, `-3 < value < 3`. When the original data contains\ - \ multiple measurements for a single item, such as a sample (library or\ - \ preparation), use the measurement name to specify the exact column type,\ - \ e.g.: \n1. `value.intensity = 3`: Selects all rows where the measurement\ - \ attribute intensity equals 3. \n `value.intensity != 2,null`: Select all\ - \ rows where the measurement attribute intensity is not equal 2 and is not\ - \ an empty value. \n`value.p_value > 3`: Selects all rows where the measurement\ - \ attribute 'p_value' values are greater than 3. \n`-3 < value.FC < 3`:\ - \ Selects all rows where the measurement attribute 'FC' values lie within\ - \ the interval between -3 and 3.\n \n2. Note: The `MinValue` keyword has\ - \ been deprecated and should be replaced with the aforementioned comparisons.\n\ - \ \nCombine multiple filters for different feature attributes and measurements\ - \ using `AND` (`&&`), `OR` (`||`), `NOT` (`!`) logical operators and parentheses: \n\ - * `NOT feature.Name_1=A`: Select all rows where Name_1 is not A. \n* `feature.Name_1!=A,B,C`:\ - \ Select all rows where Name_1 is not A, B, or C. \n* `feature.Name_1=A\ - \ AND feature.Name_2=B`: Select all rows where Name_1 is A and Name_2 is\ - \ B. \n* `feature.Name_1=A && feature.Name_2=B`: Equivalent to the example\ - \ above. \n* `feature.Name_1=A OR feature.Name_2=B`: Select all rows where\ - \ Name_1 is A or Name_2 is B. \n* `feature.Name_1=A || feature.Name_2=B`:\ - \ Equivalent to the example above. \n* `feature.Name_1=A AND (feature.Name_2=B\ - \ OR value>=1.0)`: Select all rows where Name_1 is A and either Name_2 is\ - \ B or minimal possible measurement value is 1.0." - in: query - name: exQuery - schema: - type: string - - description: "Filter by expression metadata (key-value metadata pair(s)).\ - \ E.g. `\"Genome Version\"=hg19-BROAD`." - in: query - name: exFilter - schema: - type: string - - description: "Search for objects linked to flow cytometry data via data query\ - \ (key-value pair(s)). E.g. `ReadoutType=Median|Count` `CellPopulation=\"\ - CD45+, live\"` `MinValue=3.5`" - in: query - name: fxQuery - schema: - type: string - - description: "Filter by flow cytometry metadata (key-value metadata pair(s)).\ - \ E.g. `Organ=blood`." - in: query - name: fxFilter - schema: - type: string - - description: |- - Specify which versions of omics data files are used in the query. By default the active version is used. See Versioning above. Syntax: - - \* or `v` or ``:`v` or ``:`` - in: query - name: useVersions - schema: - type: string - - description: |- - The parameter defines amount of metadata attributes to return: - - 1. `minimal_data` - return metadata attributes according to the default template. - 2. `extended_data_included` - return metadata attributes according to applied template, if object doesn’t have applied template default template will be used. This is the default for User endpoints. - 3. `original_data_included` - return all metadata attributes with values and null attributes, if they are present in the applied template. This is the default for Curator endpoints. - in: query - name: returnedMetadataFields - schema: - enum: - - minimal_data - - extended_data_included - - original_data_included - type: string - - description: The page tag to resume results from (see paging above). - in: query - name: cursor - schema: - type: string - - description: "This parameter determines the number of results to retrieve\ - \ per page, with the default set at 2000." - in: query - name: pageLimit - schema: - format: int32 - type: integer - responses: - "200": - content: - application/json: - schema: - $ref: "#/components/schemas/OmicsResponse" - description: Omics query result. - "400": - content: {} - description: Invalid data in request. See error message for details. - "401": - content: {} - description: |- - User is not authenticated. Please supply a valid Access Token in the `Authorization` HTTP header (e.g. Authorization: bearer [token]) - or Genestack API token in the `Genestack-API-Token` header (this token may be obtained from the Genestack UI _Profile_ page). - "500": - content: {} - description: "An internal server error occurred. This indicates an unexpected\ - \ failure in the Genestack system, please file a bug report to support@genestack.com,\ - \ including the error details." - security: - - Access-token: [] - - Genestack-API-Token: [] - summary: Retrieve group objects by searching across multiple data types - tags: - - Omics queries as User - /api/v1/as-user/omics/expression/streamed-data: - get: - description: "Stream data from a given group for a tabular file that matches\ - \ a sample/library/preparations query/filter. If no query/filters are supplied\ - \ all expression data is returned. If a metadata filter is specified, this\ - \ endpoint will only return expression data that is associated with a sample\ - \ via the Sample Source ID attribute.\n## Conditions\nIt is possible to supply\ - \ conditions for:\n\n1. Samples (full-text or metadata key-value pair)\n2.\ - \ Libraries (full-text or metadata key-value pair)\n3. Preparations (full-text\ - \ or metadata key-value pair)\n## Metadata full-text queries\nSingle words\ - \ can be supplied as is; otherwise, use speech marks (`\"`) to quote queries\ - \ that include whitespace. Speech marks and backslash characters in the query\ - \ need to be escaped with a backslash (`\\`).\n\n## Metadata filters\nMetadata\ - \ filters are key-value pairs joined by an operator. The `=` operator matches\ - \ literal values/string. The `!=` operator matches anything except the literal\ - \ value/string. The `<` or `>` operators match numerical results that are\ - \ less or greater than the supplied value. Strings containing whitespace need\ - \ to be quoted with (`\"`).\n\n## Combinations\nMetadata queries/filters for\ - \ the same parameter can be combined with `&&`, `AND`, `||` and `OR` operators,\ - \ using white-space to separate out the terms and operators. Parentheses `(\ - \ )` can be used for complex expressions.\n \n\n## Error Handling\n In case\ - \ of unexpected internal error during data retrieval, the last line of the\ - \ body will contain an error message, prefixed by the `#` character \n\n" - operationId: omicsSearchStreamedExpressionDataAsUser - parameters: - - description: | - Filter by sample metadata (key-value metadata pair(s)). E.g. `"Species or strain"="Homo sapiens"` - in: query - name: sampleFilter - schema: - type: string - - description: Search for objects via a full-text query over all sample metadata - fields. E.g. `Clozapine`. Queries matching dictionary terms are automatically - expanded to include synonyms. - in: query - name: sampleQuery - schema: - type: string - - description: Filter by library metadata (key-value metadata pair(s)). E.g. - `"Library Type"=RNA-Seq-1` - in: query - name: libraryFilter - schema: - type: string - - description: Search for library objects via a full-text query over all library - metadata fields. E.g. `"illumina HiSeq500"`. Queries matching dictionary - terms are automatically expanded to include synonyms. - in: query - name: libraryQuery - schema: - type: string - - description: Filter by preparation metadata (key-value metadata pair(s)). - E.g. `Digestion=Trypsin` - in: query - name: preparationFilter - schema: - type: string - - description: Search for preparation objects via a full-text query over all - preparation metadata fields. E.g. `"reversed-phase liquid chromatography"`. - Queries matching dictionary terms are automatically expanded to include - synonyms. - in: query - name: preparationQuery - schema: - type: string - - description: |- - If the full-text query term is present in an ODM dictionary, enabling this parameter will modify the query to include child terms of the full-text query. - - For example, the search query "Body fluid" can be expanded to include the term "Blood" (a child term of "Body fluid") so files containing either "Body fluid" or "Blood" in their metadata will be returned in the search results. - - The parent-child relationship is defined by the key "broaders" or "subClassOf" in the dictionary. - - If the full query term is not present in a dictionary then this parameter has no effect. - in: query - name: searchSpecificTerms - schema: - type: boolean - - description: "Search for objects linked to expression data and originally\ - \ uploaded in TSV or GCT format via data query, e.g., `feature=ENSG00000230368,ENSG00000188976\ - \ value>=1.50`\n For the case when the original data is represented by multiple\ - \ attributes per feature scenarios, extended filtering syntax is as follows:\ - \ \n1. By feature attribute value for numeric and string attributes: `features.NAME=1007_s_at`\ - \ or `features.\"Average Mz\"=2.218`. As in the case of sample metadata\ - \ queries, single words can be supplied as is; otherwise, use speech marks\ - \ (`\"`) to quote queries that include whitespace. \n2. It is possible to\ - \ specify a set of possible values, separated by comma: `features.NAME=1007_s_at,121_at`.\ - \ \n3. Utilize range filters to search numeric attributes. Apply `<` (less\ - \ than), `>` (greater than), and `=` (equal to) symbols to specify the desired\ - \ ranges as follows: \n`features.Name_1 > 3`: Select all rows where the\ - \ feature attribute Name_1 values are greater than 3. \n`features.Name_2\ - \ >= 6`: Select all rows where the feature attribute Name_2 values are greater\ - \ than or equal to 6. \n`-3 < features.Name_3 < 3`: Select all rows where\ - \ the feature attribute Name_3 values lie within the interval between -3\ - \ and 3. \n4. Use substring search to get the records where the attribute\ - \ field contains the provided substring: `features.attribute1 =~ \"some\ - \ text\"`. \n5. The first column for each original data file is identified\ - \ as feature accession (typically, it contains gene or protein names, accession\ - \ IDs, etc.). Searching by such feature accession would significantly outperform\ - \ more complex queries by combining the other feature attributes. To enable\ - \ such a search, use `feature` without any attribute extension, e.g., `feature=ENSG00000230368,ENSG00000188976`.\n\ - \ \nThe `value` keyword can be used to select rows where the sample (library\ - \ or preparation) measurements has values from a certain range. Examples:\ - \ `value = 3`, `value > 3`, `-3 < value < 3`. When the original data contains\ - \ multiple measurements for a single item, such as a sample (library or\ - \ preparation), use the measurement name to specify the exact column type,\ - \ e.g.: \n1. `value.intensity = 3`: Selects all rows where the measurement\ - \ attribute intensity equals 3. \n `value.intensity != 2,null`: Select all\ - \ rows where the measurement attribute intensity is not equal 2 and is not\ - \ an empty value. \n`values.p_value > 3`: Selects all rows where the measurement\ - \ attribute 'p_value' values are greater than 3. \n`-3 < values.FC < 3`:\ - \ Selects all rows where the measurement attribute 'FC' values lie within\ - \ the interval between -3 and 3.\n \n2. Note: The `MinValue` keyword has\ - \ been deprecated and should be replaced with the aforementioned comparisons.\n\ - \ \nCombine multiple filters for different feature attributes and measurements\ - \ using `AND` (`&&`), `OR` (`||`) logical operators and parentheses: \n\ - * `features.Name_1!=A`: Select all rows where Name_1 is not A. \n* `features.Name_1!=A,B,C`:\ - \ Select all rows where Name_1 is not A, B, or C. \n* `features.Name_1=A\ - \ AND features.Name_2=B`: Select all rows where Name_1 is A and Name_2 is\ - \ B. \n* `features.Name_1=A && features.Name_2=B`: Equivalent to the example\ - \ above. \n* `features.Name_1=A OR features.Name_2=B`: Select all rows where\ - \ Name_1 is A or Name_2 is B. \n* `features.Name_1=A || features.Name_2=B`:\ - \ Equivalent to the example above. \n* `features.Name_1=A AND (features.Name_2=B\ - \ OR value>=1.0)`: Select all rows where Name_1 is A and either Name_2 is\ - \ B or minimal possible measurement value is 1.0." - in: query - name: exQuery - schema: - type: string - - description: "Deprecated; use `exQuery` parameter instead. Filters results\ - \ by the feature column (e.g., Gene ID). The feature parameter value must\ - \ match the name of the identifier in the GCT file (under the NAME column).\ - \ Example: `ENSG00000077044`" - explode: true - in: query - name: featureList - schema: - items: - type: string - example: KRAS - type: array - style: form - - description: Accession of the expression group object (GCT) - in: query - name: groupAccession - required: true - schema: - type: string - - description: The number of digits after the decimal point for floating-point - values. The final value is rounded up. Must be non-negative. The default - is 4. - in: query - name: roundDigits - schema: - default: 4 - format: int32 - type: integer - responses: - "200": - content: - text/csv: - schema: - $ref: "#/components/schemas/StreamingOutput" - description: Stream of retrieved Expression data. - "400": - content: {} - description: Invalid data in request. See error message for details. - "401": - content: {} - description: |- - User is not authenticated. Please supply a valid Access Token in the `Authorization` HTTP header (e.g. Authorization: bearer [token]) - or Genestack API token in the `Genestack-API-Token` header (this token may be obtained from the Genestack UI _Profile_ page). - "500": - content: {} - description: "An internal server error occurred. This indicates an unexpected\ - \ failure in the Genestack system, please file a bug report to support@genestack.com,\ - \ including the error details." - security: - - Access-token: [] - - Genestack-API-Token: [] - summary: Stream data from a given tabular file - tags: - - Omics queries as User - /api/v1/as-user/omics/flow-cytometry/data: - get: - description: |+ - Retrieve flow cytometry data objects whose linked data matches all supplied conditions. - - Note: A flow cytometry data query must be supplied. - - ## Conditions - It is possible to supply conditions for: - - 1. Samples (full-text or metadata key-value pair) - 2. Parent studies (full-text or metadata key-value pair) - 3. Linked variant objects (list of data key-value pairs) - 4. Linked flow cytometry objects (list of data key-value pairs) - 5. Linked any data (except variant and flow cytometry) objects (list of data key-value pairs) - - ## Metadata full-text queries - Single words can be supplied as is; otherwise, use speech marks (`"`) to quote queries that include whitespace. Speech marks and backslash characters in the query need to be escaped with a backslash (`\`). - - ## Metadata filters - Metadata filters are key-value pairs joined by an operator. The `=` operator matches literal values/string. The `!=` operator matches anything except the literal value/string. The `<` or `>` operators match numerical results that are less or greater than the supplied value. Strings containing whitespace need to be quoted with (`"`). - - ## Data queries - Data queries must be a list of key-value pairs, separated by whitespace. The set of valid keys depends on the specific query type, and is documented in the query parameter summary. The values can be simple non-whitespace strings, or strings enclosed by speech marks (`"`). Depending on the key, the value may be be a comma-delimited list of string values. Others require numerical values. - - ## Combinations - Metadata queries/filters for the same parameter can be combined with `&&`, `AND`, `||` and `OR` operators, using white-space to separate out the terms and operators. Parentheses `( )` can be used for complex expressions. - - ## Versioning - Specific versions of omics data files (eg. GCT) can be queried via the useVersions parameter. Different versions of an omics data file are associated via their CHAIN_ID metadata value. This CHAIN_ID can be supplied to the useVersions parameter along with the version number or specific omics data file accessions to include them in the query. If nothing is supplied to the useVersions parameter then only the active version (which is usually the last one imported) is queried. This acts as a filter before the rest of the query is carried out. - - Example usage: - useVersions=* (query all versions, including those without CHAIN_IDs) - useVersions=v2 (query the second version. If there is no second version then the data file is not queried) - useVersions=v1,v0 (query the first version and any data files without CHAIN_IDs(v0) ) - useVersions=GSVC002:v3 (for omics data files with a CHAIN_ID of GSCV002 query the third version) - useVersions=GSVC002:GSF00494,GSF000496 (for omics data files with a CHAIN_ID of GSCV002 query only the specific accessions GSF00494 and GSF000496) - - Rules for multiple CHAIN_IDs can be supplied to the parameter using the ; separator. - - ## Paging - For performance reasons this endpoint returns results in "pages" of limited size together with a cursor tag. To retrieve the next page of results please supply this cursor tag to resume the query from your previous result and get the next page. If there are no more results you will just retrieve an empty result. To return all results iterate through pages using cursor values until the `resultsExhausted` response field is true. - - operationId: omicsSearchFlowCytometryDataAsUser - parameters: - - description: Supply this parameter with the value `term_id` as part of the - query to return extended information including IDs for values and dictionaries. - in: query - name: responseFormat - schema: - $ref: "#/components/schemas/ResponseFormat" - - description: | - Filter by study metadata (key-value metadata pair(s)). E.g. `"Study Source"=ArrayExpress` - in: query - name: studyFilter - schema: - type: string - - description: Search for objects via a full-text query over all study metadata - fields. E.g. `"RNA-Seq of human dendritic cells"`. Queries matching dictionary - terms are automatically expanded to include synonyms. - in: query - name: studyQuery - schema: - type: string - - description: | - Filter by sample metadata (key-value metadata pair(s)). E.g. `"Species or strain"="Homo sapiens"` - in: query - name: sampleFilter - schema: - type: string - - description: Search for objects via a full-text query over all sample metadata - fields. E.g. `Clozapine`. Queries matching dictionary terms are automatically - expanded to include synonyms. - in: query - name: sampleQuery - schema: - type: string - - description: Filter by library metadata (key-value metadata pair(s)). E.g. - `"Library Type"=RNA-Seq-1` - in: query - name: libraryFilter - schema: - type: string - - description: Search for library objects via a full-text query over all library - metadata fields. E.g. `"illumina HiSeq500"`. Queries matching dictionary - terms are automatically expanded to include synonyms. - in: query - name: libraryQuery - schema: - type: string - - description: Filter by preparation metadata (key-value metadata pair(s)). - E.g. `Digestion=Trypsin` - in: query - name: preparationFilter - schema: - type: string - - description: Search for preparation objects via a full-text query over all - preparation metadata fields. E.g. `"reversed-phase liquid chromatography"`. - Queries matching dictionary terms are automatically expanded to include - synonyms. - in: query - name: preparationQuery - schema: - type: string - - description: |- - If the full-text query term is present in an ODM dictionary, enabling this parameter will modify the query to include child terms of the full-text query. - - For example, the search query "Body fluid" can be expanded to include the term "Blood" (a child term of "Body fluid") so files containing either "Body fluid" or "Blood" in their metadata will be returned in the search results. - - The parent-child relationship is defined by the key "broaders" or "subClassOf" in the dictionary. - - If the full query term is not present in a dictionary then this parameter has no effect. - in: query - name: searchSpecificTerms - schema: - type: boolean - - description: "Search for objects linked to variant data by SNPs properties. Filtering is currently supported by `filter`, `id`, `region` and `info` keywords, - as well as `exists` keyword for `INFO` field and their logical combinations by means of `not` (`!`), `and` (`&&`), and `or` (`||`) operators with standard boolean precedence. Keyword case is ignored.\n - * `filter` corresponds to the `FILTER` column in the original vcf file. Could be either equals or not equals to `PASS` : `filter = PASS` - or `filter != pass`.\n - * `id` is a string value that corresponds to the `ID` column. Multiple values could be added via a comma. Expression `id = rs3214,rg1234` is equivalent - to `id = rs3214 or id = rg1234`.\n - * `region` corresponds to CHROM and POS columns. Supports querying by the whole chromosome `region = chr1` , by interval within a chromosome - `region = chr1:4567-9876543` by exact position `region = chr1:456789` or by indefinite ranges like `region = x:3456789-*` . Multiple regions could be - separated via comma, e.g. `region = chr1:34567-98767,chr3` is equivalent to `region = chr1:34567-98767 or region = chr3`.\n - * `feature` is the name of the reference gene associated with a specific location in the reference genome which corresponds to the VCF file (variant group) from which the variant information is derived. - By providing the gene name(s), such as `feature=TP53` or `feature=TP53,TGFB`, variants located within the same genomic region as the specified gene(s) will be retrieved.\n - * Filter by vcf `INFO` fields. E.g. to filter all variants annotated in dbSNP add `exists(INFO.KEY)`. Use `!exists(INFO.KEY)` to exclude variants having the key from the search results. - Provide `info.key=value` pair to search for an exact match or `info.key!=value` to exclude it from the search. Due to the limits of precision in floating point numbers, - we use a small range of 0.0000001 to identify close matches. This means any differences smaller than that won't be detected. For more precise results, please use range queries." - in: query - name: vxQuery - schema: - type: string - - description: "Filter by variant metadata (key-value metadata pair(s)). E.g.\ - \ `\"Variant Source\"=dbSNP`." - in: query - name: vxFilter - schema: - type: string - - description: "Search for objects linked to expression data and originally\ - \ uploaded in TSV or GCT format via data query, e.g., `feature=ENSG00000230368,ENSG00000188976\ - \ value>=1.50`\n For the case when the original data is represented by multiple\ - \ attributes per feature scenarios, extended filtering syntax is as follows:\ - \ \n1. By feature attribute value for numeric and string attributes: `feature.NAME=1007_s_at`\ - \ or `feature.\"Average Mz\"=2.218`. As in the case of sample metadata queries,\ - \ single words can be supplied as is; otherwise, use speech marks (`\"`)\ - \ to quote queries that include whitespace. \n2. It is possible to specify\ - \ a set of possible values, separated by comma: `feature.NAME=1007_s_at,121_at`.\ - \ \n3. Utilize range filters to search numeric attributes. Apply `<` (less\ - \ than), `>` (greater than), and `=` (equal to) symbols to specify the desired\ - \ ranges as follows: \n`feature.Name_1 > 3`: Select all rows where the feature\ - \ attribute Name_1 values are greater than 3. \n`feature.Name_2 >= 6`: Select\ - \ all rows where the feature attribute Name_2 values are greater than or\ - \ equal to 6. \n`-3 < feature.Name_3 < 3`: Select all rows where the feature\ - \ attribute Name_3 values lie within the interval between -3 and 3. \n4.\ - \ Use substring search to get the records where the attribute field contains\ - \ the provided substring: `feature.attribute1 =~ \"some text\"`. \n5. The\ - \ first column for each original data file is identified as feature accession\ - \ (typically, it contains gene or protein names, accession IDs, etc.). Searching\ - \ by such feature accession would significantly outperform more complex\ - \ queries by combining the other feature attributes. To enable such a search,\ - \ use `feature` without any attribute extension, e.g., `feature=ENSG00000230368,ENSG00000188976`.\n\ - \ \nThe `value` keyword can be used to select rows where the sample (library\ - \ or preparation) measurements has values from a certain range. Examples:\ - \ `value = 3`, `value > 3`, `-3 < value < 3`. When the original data contains\ - \ multiple measurements for a single item, such as a sample (library or\ - \ preparation), use the measurement name to specify the exact column type,\ - \ e.g.: \n1. `value.intensity = 3`: Selects all rows where the measurement\ - \ attribute intensity equals 3. \n `value.intensity != 2,null`: Select all\ - \ rows where the measurement attribute intensity is not equal 2 and is not\ - \ an empty value. \n`value.p_value > 3`: Selects all rows where the measurement\ - \ attribute 'p_value' values are greater than 3. \n`-3 < value.FC < 3`:\ - \ Selects all rows where the measurement attribute 'FC' values lie within\ - \ the interval between -3 and 3.\n \n2. Note: The `MinValue` keyword has\ - \ been deprecated and should be replaced with the aforementioned comparisons.\n\ - \ \nCombine multiple filters for different feature attributes and measurements\ - \ using `AND` (`&&`), `OR` (`||`), `NOT` (`!`) logical operators and parentheses: \n\ - * `NOT feature.Name_1=A`: Select all rows where Name_1 is not A. \n* `feature.Name_1!=A,B,C`:\ - \ Select all rows where Name_1 is not A, B, or C. \n* `feature.Name_1=A\ - \ AND feature.Name_2=B`: Select all rows where Name_1 is A and Name_2 is\ - \ B. \n* `feature.Name_1=A && feature.Name_2=B`: Equivalent to the example\ - \ above. \n* `feature.Name_1=A OR feature.Name_2=B`: Select all rows where\ - \ Name_1 is A or Name_2 is B. \n* `feature.Name_1=A || feature.Name_2=B`:\ - \ Equivalent to the example above. \n* `feature.Name_1=A AND (feature.Name_2=B\ - \ OR value>=1.0)`: Select all rows where Name_1 is A and either Name_2 is\ - \ B or minimal possible measurement value is 1.0." - in: query - name: exQuery - schema: - type: string - - description: "Filter by expression metadata (key-value metadata pair(s)).\ - \ E.g. `\"Genome Version\"=hg19-BROAD`." - in: query - name: exFilter - schema: - type: string - - description: "Search for objects linked to flow cytometry data via data query\ - \ (key-value pair(s)). E.g. `ReadoutType=Median|Count` `CellPopulation=\"\ - CD45+, live\"` `MinValue=3.5`" - in: query - name: fxQuery - schema: - type: string - - description: "Filter by flow cytometry metadata (key-value metadata pair(s)).\ - \ E.g. `Organ=blood`." - in: query - name: fxFilter - schema: - type: string - - description: |- - Specify which versions of omics data files are used in the query. By default the active version is used. See Versioning above. Syntax: - - \* or `v` or ``:`v` or ``:`` - in: query - name: useVersions - schema: - type: string - - description: |- - The parameter defines amount of metadata attributes to return: - - 1. `minimal_data` - return metadata attributes according to the default template. - 2. `extended_data_included` - return metadata attributes according to applied template, if object doesn’t have applied template default template will be used. This is the default for User endpoints. - 3. `original_data_included` - return all metadata attributes with values and null attributes, if they are present in the applied template. This is the default for Curator endpoints. - in: query - name: returnedMetadataFields - schema: - enum: - - minimal_data - - extended_data_included - - original_data_included - type: string - - description: The page tag to resume results from (see paging above). - in: query - name: cursor - schema: - type: string - - description: "This parameter determines the number of results to retrieve\ - \ per page, with the default set at 2000." - in: query - name: pageLimit - schema: - format: int32 - type: integer - responses: - "200": - content: - application/json: - schema: - $ref: "#/components/schemas/OmicsResponse" - description: Omics query result. - "400": - content: {} - description: Invalid data in request. See error message for details. - "401": - content: {} - description: |- - User is not authenticated. Please supply a valid Access Token in the `Authorization` HTTP header (e.g. Authorization: bearer [token]) - or Genestack API token in the `Genestack-API-Token` header (this token may be obtained from the Genestack UI _Profile_ page). - "500": - content: {} - description: "An internal server error occurred. This indicates an unexpected\ - \ failure in the Genestack system, please file a bug report to support@genestack.com,\ - \ including the error details." - security: - - Access-token: [] - - Genestack-API-Token: [] - summary: Retrieve flow cytometry data objects by searching across multiple data - types - tags: - - Omics queries as User - /api/v1/as-user/omics/flow-cytometry/group: - get: - description: |+ - Retrieve group objects whose linked data matches all supplied conditions. - - ## Conditions - It is possible to supply conditions for: - - 1. Samples (full-text or metadata key-value pair) - 2. Parent studies (full-text or metadata key-value pair) - 3. Linked variant objects (list of data key-value pairs) - 4. Linked flow cytometry objects (list of data key-value pairs) - 5. Linked any data (except variant and flow cytometry) objects (list of data key-value pairs) - - ## Metadata full-text queries - Single words can be supplied as is; otherwise, use speech marks (`"`) to quote queries that include whitespace. Speech marks and backslash characters in the query need to be escaped with a backslash (`\`). - - ## Metadata filters - Metadata filters are key-value pairs joined by an operator. The `=` operator matches literal values/string. The `!=` operator matches anything except the literal value/string. The `<` or `>` operators match numerical results that are less or greater than the supplied value. Strings containing whitespace need to be quoted with (`"`). - - ## Data queries - Data queries must be a list of key-value pairs, separated by whitespace. The set of valid keys depends on the specific query type, and is documented in the query parameter summary. The values can be simple non-whitespace strings, or strings enclosed by speech marks (`"`). Depending on the key, the value may be be a comma-delimited list of string values. Others require numerical values. - - ## Combinations - Metadata queries/filters for the same parameter can be combined with `&&`, `AND`, `||` and `OR` operators, using white-space to separate out the terms and operators. Parentheses `( )` can be used for complex expressions. - - ## Versioning - Specific versions of omics data files (eg. GCT) can be queried via the useVersions parameter. Different versions of an omics data file are associated via their CHAIN_ID metadata value. This CHAIN_ID can be supplied to the useVersions parameter along with the version number or specific omics data file accessions to include them in the query. If nothing is supplied to the useVersions parameter then only the active version (which is usually the last one imported) is queried. This acts as a filter before the rest of the query is carried out. - - Example usage: - useVersions=* (query all versions, including those without CHAIN_IDs) - useVersions=v2 (query the second version. If there is no second version then the data file is not queried) - useVersions=v1,v0 (query the first version and any data files without CHAIN_IDs(v0) ) - useVersions=GSVC002:v3 (for omics data files with a CHAIN_ID of GSCV002 query the third version) - useVersions=GSVC002:GSF00494,GSF000496 (for omics data files with a CHAIN_ID of GSCV002 query only the specific accessions GSF00494 and GSF000496) - - Rules for multiple CHAIN_IDs can be supplied to the parameter using the ; separator. - - ## Paging - For performance reasons this endpoint returns results in "pages" of limited size together with a cursor tag. To retrieve the next page of results please supply this cursor tag to resume the query from your previous result and get the next page. If there are no more results you will just retrieve an empty result. To return all results iterate through pages using cursor values until the `resultsExhausted` response field is true. - - operationId: omicsSearchFlowCytometryGroupsAsUser - parameters: - - description: Supply this parameter with the value `term_id` as part of the - query to return extended information including IDs for values and dictionaries. - in: query - name: responseFormat - schema: - $ref: "#/components/schemas/ResponseFormat" - - description: | - Filter by study metadata (key-value metadata pair(s)). E.g. `"Study Source"=ArrayExpress` - in: query - name: studyFilter - schema: - type: string - - description: Search for objects via a full-text query over all study metadata - fields. E.g. `"RNA-Seq of human dendritic cells"`. Queries matching dictionary - terms are automatically expanded to include synonyms. - in: query - name: studyQuery - schema: - type: string - - description: | - Filter by sample metadata (key-value metadata pair(s)). E.g. `"Species or strain"="Homo sapiens"` - in: query - name: sampleFilter - schema: - type: string - - description: Search for objects via a full-text query over all sample metadata - fields. E.g. `Clozapine`. Queries matching dictionary terms are automatically - expanded to include synonyms. - in: query - name: sampleQuery - schema: - type: string - - description: Filter by library metadata (key-value metadata pair(s)). E.g. - `"Library Type"=RNA-Seq-1` - in: query - name: libraryFilter - schema: - type: string - - description: Search for library objects via a full-text query over all library - metadata fields. E.g. `"illumina HiSeq500"`. Queries matching dictionary - terms are automatically expanded to include synonyms. - in: query - name: libraryQuery - schema: - type: string - - description: Filter by preparation metadata (key-value metadata pair(s)). - E.g. `Digestion=Trypsin` - in: query - name: preparationFilter - schema: - type: string - - description: Search for preparation objects via a full-text query over all - preparation metadata fields. E.g. `"reversed-phase liquid chromatography"`. - Queries matching dictionary terms are automatically expanded to include - synonyms. - in: query - name: preparationQuery - schema: - type: string - - description: |- - If the full-text query term is present in an ODM dictionary, enabling this parameter will modify the query to include child terms of the full-text query. - - For example, the search query "Body fluid" can be expanded to include the term "Blood" (a child term of "Body fluid") so files containing either "Body fluid" or "Blood" in their metadata will be returned in the search results. - - The parent-child relationship is defined by the key "broaders" or "subClassOf" in the dictionary. - - If the full query term is not present in a dictionary then this parameter has no effect. - in: query - name: searchSpecificTerms - schema: - type: boolean - - description: "Search for objects linked to variant data by SNPs properties. Filtering is currently supported by `filter`, `id`, `region` and `info` keywords, - as well as `exists` keyword for `INFO` field and their logical combinations by means of `not` (`!`), `and` (`&&`), and `or` (`||`) operators with standard boolean precedence. Keyword case is ignored.\n - * `filter` corresponds to the `FILTER` column in the original vcf file. Could be either equals or not equals to `PASS` : `filter = PASS` - or `filter != pass`.\n - * `id` is a string value that corresponds to the `ID` column. Multiple values could be added via a comma. Expression `id = rs3214,rg1234` is equivalent - to `id = rs3214 or id = rg1234`.\n - * `region` corresponds to CHROM and POS columns. Supports querying by the whole chromosome `region = chr1` , by interval within a chromosome - `region = chr1:4567-9876543` by exact position `region = chr1:456789` or by indefinite ranges like `region = x:3456789-*` . Multiple regions could be - separated via comma, e.g. `region = chr1:34567-98767,chr3` is equivalent to `region = chr1:34567-98767 or region = chr3`.\n - * `feature` is the name of the reference gene associated with a specific location in the reference genome which corresponds to the VCF file (variant group) from which the variant information is derived. - By providing the gene name(s), such as `feature=TP53` or `feature=TP53,TGFB`, variants located within the same genomic region as the specified gene(s) will be retrieved.\n - * Filter by vcf `INFO` fields. E.g. to filter all variants annotated in dbSNP add `exists(INFO.KEY)`. Use `!exists(INFO.KEY)` to exclude variants having the key from the search results. - Provide `info.key=value` pair to search for an exact match or `info.key!=value` to exclude it from the search. Due to the limits of precision in floating point numbers, - we use a small range of 0.0000001 to identify close matches. This means any differences smaller than that won't be detected. For more precise results, please use range queries." - in: query - name: vxQuery - schema: - type: string - - description: "Filter by variant metadata (key-value metadata pair(s)). E.g.\ - \ `\"Variant Source\"=dbSNP`." - in: query - name: vxFilter - schema: - type: string - - description: "Search for objects linked to expression data and originally\ - \ uploaded in TSV or GCT format via data query, e.g., `feature=ENSG00000230368,ENSG00000188976\ - \ value>=1.50`\n For the case when the original data is represented by multiple\ - \ attributes per feature scenarios, extended filtering syntax is as follows:\ - \ \n1. By feature attribute value for numeric and string attributes: `feature.NAME=1007_s_at`\ - \ or `feature.\"Average Mz\"=2.218`. As in the case of sample metadata queries,\ - \ single words can be supplied as is; otherwise, use speech marks (`\"`)\ - \ to quote queries that include whitespace. \n2. It is possible to specify\ - \ a set of possible values, separated by comma: `feature.NAME=1007_s_at,121_at`.\ - \ \n3. Utilize range filters to search numeric attributes. Apply `<` (less\ - \ than), `>` (greater than), and `=` (equal to) symbols to specify the desired\ - \ ranges as follows: \n`feature.Name_1 > 3`: Select all rows where the feature\ - \ attribute Name_1 values are greater than 3. \n`feature.Name_2 >= 6`: Select\ - \ all rows where the feature attribute Name_2 values are greater than or\ - \ equal to 6. \n`-3 < feature.Name_3 < 3`: Select all rows where the feature\ - \ attribute Name_3 values lie within the interval between -3 and 3. \n4.\ - \ Use substring search to get the records where the attribute field contains\ - \ the provided substring: `feature.attribute1 =~ \"some text\"`. \n5. The\ - \ first column for each original data file is identified as feature accession\ - \ (typically, it contains gene or protein names, accession IDs, etc.). Searching\ - \ by such feature accession would significantly outperform more complex\ - \ queries by combining the other feature attributes. To enable such a search,\ - \ use `feature` without any attribute extension, e.g., `feature=ENSG00000230368,ENSG00000188976`.\n\ - \ \nThe `value` keyword can be used to select rows where the sample (library\ - \ or preparation) measurements has values from a certain range. Examples:\ - \ `value = 3`, `value > 3`, `-3 < value < 3`. When the original data contains\ - \ multiple measurements for a single item, such as a sample (library or\ - \ preparation), use the measurement name to specify the exact column type,\ - \ e.g.: \n1. `value.intensity = 3`: Selects all rows where the measurement\ - \ attribute intensity equals 3. \n `value.intensity != 2,null`: Select all\ - \ rows where the measurement attribute intensity is not equal 2 and is not\ - \ an empty value. \n`value.p_value > 3`: Selects all rows where the measurement\ - \ attribute 'p_value' values are greater than 3. \n`-3 < value.FC < 3`:\ - \ Selects all rows where the measurement attribute 'FC' values lie within\ - \ the interval between -3 and 3.\n \n2. Note: The `MinValue` keyword has\ - \ been deprecated and should be replaced with the aforementioned comparisons.\n\ - \ \nCombine multiple filters for different feature attributes and measurements\ - \ using `AND` (`&&`), `OR` (`||`), `NOT` (`!`) logical operators and parentheses: \n\ - * `NOT feature.Name_1=A`: Select all rows where Name_1 is not A. \n* `feature.Name_1!=A,B,C`:\ - \ Select all rows where Name_1 is not A, B, or C. \n* `feature.Name_1=A\ - \ AND feature.Name_2=B`: Select all rows where Name_1 is A and Name_2 is\ - \ B. \n* `feature.Name_1=A && feature.Name_2=B`: Equivalent to the example\ - \ above. \n* `feature.Name_1=A OR feature.Name_2=B`: Select all rows where\ - \ Name_1 is A or Name_2 is B. \n* `feature.Name_1=A || feature.Name_2=B`:\ - \ Equivalent to the example above. \n* `feature.Name_1=A AND (feature.Name_2=B\ - \ OR value>=1.0)`: Select all rows where Name_1 is A and either Name_2 is\ - \ B or minimal possible measurement value is 1.0." - in: query - name: exQuery - schema: - type: string - - description: "Filter by expression metadata (key-value metadata pair(s)).\ - \ E.g. `\"Genome Version\"=hg19-BROAD`." - in: query - name: exFilter - schema: - type: string - - description: "Search for objects linked to flow cytometry data via data query\ - \ (key-value pair(s)). E.g. `ReadoutType=Median|Count` `CellPopulation=\"\ - CD45+, live\"` `MinValue=3.5`" - in: query - name: fxQuery - schema: - type: string - - description: "Filter by flow cytometry metadata (key-value metadata pair(s)).\ - \ E.g. `Organ=blood`." - in: query - name: fxFilter - schema: - type: string - - description: |- - Specify which versions of omics data files are used in the query. By default the active version is used. See Versioning above. Syntax: - - \* or `v` or ``:`v` or ``:`` - in: query - name: useVersions - schema: - type: string - - description: |- - The parameter defines amount of metadata attributes to return: - - 1. `minimal_data` - return metadata attributes according to the default template. - 2. `extended_data_included` - return metadata attributes according to applied template, if object doesn’t have applied template default template will be used. This is the default for User endpoints. - 3. `original_data_included` - return all metadata attributes with values and null attributes, if they are present in the applied template. This is the default for Curator endpoints. - in: query - name: returnedMetadataFields - schema: - enum: - - minimal_data - - extended_data_included - - original_data_included - type: string - - description: The page tag to resume results from (see paging above). - in: query - name: cursor - schema: - type: string - - description: "This parameter determines the number of results to retrieve\ - \ per page, with the default set at 2000." - in: query - name: pageLimit - schema: - format: int32 - type: integer - responses: - "200": - content: - application/json: - schema: - $ref: "#/components/schemas/OmicsResponse" - description: Omics query result. - "400": - content: {} - description: Invalid data in request. See error message for details. - "401": - content: {} - description: |- - User is not authenticated. Please supply a valid Access Token in the `Authorization` HTTP header (e.g. Authorization: bearer [token]) - or Genestack API token in the `Genestack-API-Token` header (this token may be obtained from the Genestack UI _Profile_ page). - "500": - content: {} - description: "An internal server error occurred. This indicates an unexpected\ - \ failure in the Genestack system, please file a bug report to support@genestack.com,\ - \ including the error details." - security: - - Access-token: [] - - Genestack-API-Token: [] - summary: Retrieve group objects by searching across multiple data types - tags: - - Omics queries as User - /api/v1/as-user/omics/samples: - get: - description: |+ - Retrieve sample metadata objects whose linked data matches all supplied conditions. - - ## Conditions - It is possible to supply conditions for: - - 1. Samples (full-text or metadata key-value pair) - 2. Parent studies (full-text or metadata key-value pair) - 3. Linked variant objects (list of data key-value pairs) - 4. Linked flow cytometry objects (list of data key-value pairs) - 5. Linked any data (except variant and flow cytometry) objects (list of data key-value pairs) - - ## Metadata full-text queries - Single words can be supplied as is; otherwise, use speech marks (`"`) to quote queries that include whitespace. Speech marks and backslash characters in the query need to be escaped with a backslash (`\`). - - ## Metadata filters - Metadata filters are key-value pairs joined by an operator. The `=` operator matches literal values/string. The `!=` operator matches anything except the literal value/string. The `<` or `>` operators match numerical results that are less or greater than the supplied value. Strings containing whitespace need to be quoted with (`"`). - - ## Data queries - Data queries must be a list of key-value pairs, separated by whitespace. The set of valid keys depends on the specific query type, and is documented in the query parameter summary. The values can be simple non-whitespace strings, or strings enclosed by speech marks (`"`). Depending on the key, the value may be be a comma-delimited list of string values. Others require numerical values. - - ## Combinations - Metadata queries/filters for the same parameter can be combined with `&&`, `AND`, `||` and `OR` operators, using white-space to separate out the terms and operators. Parentheses `( )` can be used for complex expressions. - - ## Versioning - Specific versions of omics data files (eg. GCT) can be queried via the useVersions parameter. Different versions of an omics data file are associated via their CHAIN_ID metadata value. This CHAIN_ID can be supplied to the useVersions parameter along with the version number or specific omics data file accessions to include them in the query. If nothing is supplied to the useVersions parameter then only the active version (which is usually the last one imported) is queried. This acts as a filter before the rest of the query is carried out. - - Example usage: - useVersions=* (query all versions, including those without CHAIN_IDs) - useVersions=v2 (query the second version. If there is no second version then the data file is not queried) - useVersions=v1,v0 (query the first version and any data files without CHAIN_IDs(v0) ) - useVersions=GSVC002:v3 (for omics data files with a CHAIN_ID of GSCV002 query the third version) - useVersions=GSVC002:GSF00494,GSF000496 (for omics data files with a CHAIN_ID of GSCV002 query only the specific accessions GSF00494 and GSF000496) - - Rules for multiple CHAIN_IDs can be supplied to the parameter using the ; separator. - - ## Paging - For performance reasons this endpoint returns results in "pages" of limited size together with a cursor tag. To retrieve the next page of results please supply this cursor tag to resume the query from your previous result and get the next page. If there are no more results you will just retrieve an empty result. To return all results iterate through pages using cursor values until the `resultsExhausted` response field is true. - - operationId: omicsSearchSamplesAsUser - parameters: - - description: Supply this parameter with the value `term_id` as part of the - query to return extended information including IDs for values and dictionaries. - in: query - name: responseFormat - schema: - $ref: "#/components/schemas/ResponseFormat" - - description: | - Filter by study metadata (key-value metadata pair(s)). E.g. `"Study Source"=ArrayExpress` - in: query - name: studyFilter - schema: - type: string - - description: Search for objects via a full-text query over all study metadata - fields. E.g. `"RNA-Seq of human dendritic cells"`. Queries matching dictionary - terms are automatically expanded to include synonyms. - in: query - name: studyQuery - schema: - type: string - - description: | - Filter by sample metadata (key-value metadata pair(s)). E.g. `"Species or strain"="Homo sapiens"` - in: query - name: sampleFilter - schema: - type: string - - description: Search for objects via a full-text query over all sample metadata - fields. E.g. `Clozapine`. Queries matching dictionary terms are automatically - expanded to include synonyms. - in: query - name: sampleQuery - schema: - type: string - - description: Filter by library metadata (key-value metadata pair(s)). E.g. - `"Library Type"=RNA-Seq-1` - in: query - name: libraryFilter - schema: - type: string - - description: Search for library objects via a full-text query over all library - metadata fields. E.g. `"illumina HiSeq500"`. Queries matching dictionary - terms are automatically expanded to include synonyms. - in: query - name: libraryQuery - schema: - type: string - - description: Filter by preparation metadata (key-value metadata pair(s)). - E.g. `Digestion=Trypsin` - in: query - name: preparationFilter - schema: - type: string - - description: Search for preparation objects via a full-text query over all - preparation metadata fields. E.g. `"reversed-phase liquid chromatography"`. - Queries matching dictionary terms are automatically expanded to include - synonyms. - in: query - name: preparationQuery - schema: - type: string - - description: |- - If the full-text query term is present in an ODM dictionary, enabling this parameter will modify the query to include child terms of the full-text query. - - For example, the search query "Body fluid" can be expanded to include the term "Blood" (a child term of "Body fluid") so files containing either "Body fluid" or "Blood" in their metadata will be returned in the search results. - - The parent-child relationship is defined by the key "broaders" or "subClassOf" in the dictionary. - - If the full query term is not present in a dictionary then this parameter has no effect. - in: query - name: searchSpecificTerms - schema: - type: boolean - - description: "Search for objects linked to variant data by SNPs properties. Filtering is currently supported by `filter`, `id`, `region` and `info` keywords, - as well as `exists` keyword for `INFO` field and their logical combinations by means of `not` (`!`), `and` (`&&`), and `or` (`||`) operators with standard boolean precedence. Keyword case is ignored.\n - * `filter` corresponds to the `FILTER` column in the original vcf file. Could be either equals or not equals to `PASS` : `filter = PASS` - or `filter != pass`.\n - * `id` is a string value that corresponds to the `ID` column. Multiple values could be added via a comma. Expression `id = rs3214,rg1234` is equivalent - to `id = rs3214 or id = rg1234`.\n - * `region` corresponds to CHROM and POS columns. Supports querying by the whole chromosome `region = chr1` , by interval within a chromosome - `region = chr1:4567-9876543` by exact position `region = chr1:456789` or by indefinite ranges like `region = x:3456789-*` . Multiple regions could be - separated via comma, e.g. `region = chr1:34567-98767,chr3` is equivalent to `region = chr1:34567-98767 or region = chr3`.\n - * `feature` is the name of the reference gene associated with a specific location in the reference genome which corresponds to the VCF file (variant group) from which the variant information is derived. - By providing the gene name(s), such as `feature=TP53` or `feature=TP53,TGFB`, variants located within the same genomic region as the specified gene(s) will be retrieved.\n - * Filter by vcf `INFO` fields. E.g. to filter all variants annotated in dbSNP add `exists(INFO.KEY)`. Use `!exists(INFO.KEY)` to exclude variants having the key from the search results. - Provide `info.key=value` pair to search for an exact match or `info.key!=value` to exclude it from the search. Due to the limits of precision in floating point numbers, - we use a small range of 0.0000001 to identify close matches. This means any differences smaller than that won't be detected. For more precise results, please use range queries." - in: query - name: vxQuery - schema: - type: string - - description: "Filter by variant metadata (key-value metadata pair(s)). E.g.\ - \ `\"Variant Source\"=dbSNP`." - in: query - name: vxFilter - schema: - type: string - - description: "Search for objects linked to expression data and originally\ - \ uploaded in TSV or GCT format via data query, e.g., `feature=ENSG00000230368,ENSG00000188976\ - \ value>=1.50`\n For the case when the original data is represented by multiple\ - \ attributes per feature scenarios, extended filtering syntax is as follows:\ - \ \n1. By feature attribute value for numeric and string attributes: `feature.NAME=1007_s_at`\ - \ or `feature.\"Average Mz\"=2.218`. As in the case of sample metadata queries,\ - \ single words can be supplied as is; otherwise, use speech marks (`\"`)\ - \ to quote queries that include whitespace. \n2. It is possible to specify\ - \ a set of possible values, separated by comma: `feature.NAME=1007_s_at,121_at`.\ - \ \n3. Utilize range filters to search numeric attributes. Apply `<` (less\ - \ than), `>` (greater than), and `=` (equal to) symbols to specify the desired\ - \ ranges as follows: \n`feature.Name_1 > 3`: Select all rows where the feature\ - \ attribute Name_1 values are greater than 3. \n`feature.Name_2 >= 6`: Select\ - \ all rows where the feature attribute Name_2 values are greater than or\ - \ equal to 6. \n`-3 < feature.Name_3 < 3`: Select all rows where the feature\ - \ attribute Name_3 values lie within the interval between -3 and 3. \n4.\ - \ Use substring search to get the records where the attribute field contains\ - \ the provided substring: `feature.attribute1 =~ \"some text\"`. \n5. The\ - \ first column for each original data file is identified as feature accession\ - \ (typically, it contains gene or protein names, accession IDs, etc.). Searching\ - \ by such feature accession would significantly outperform more complex\ - \ queries by combining the other feature attributes. To enable such a search,\ - \ use `feature` without any attribute extension, e.g., `feature=ENSG00000230368,ENSG00000188976`.\n\ - \ \nThe `value` keyword can be used to select rows where the sample (library\ - \ or preparation) measurements has values from a certain range. Examples:\ - \ `value = 3`, `value > 3`, `-3 < value < 3`. When the original data contains\ - \ multiple measurements for a single item, such as a sample (library or\ - \ preparation), use the measurement name to specify the exact column type,\ - \ e.g.: \n1. `value.intensity = 3`: Selects all rows where the measurement\ - \ attribute intensity equals 3. \n `value.intensity != 2,null`: Select all\ - \ rows where the measurement attribute intensity is not equal 2 and is not\ - \ an empty value. \n`value.p_value > 3`: Selects all rows where the measurement\ - \ attribute 'p_value' values are greater than 3. \n`-3 < value.FC < 3`:\ - \ Selects all rows where the measurement attribute 'FC' values lie within\ - \ the interval between -3 and 3.\n \n2. Note: The `MinValue` keyword has\ - \ been deprecated and should be replaced with the aforementioned comparisons.\n\ - \ \nCombine multiple filters for different feature attributes and measurements\ - \ using `AND` (`&&`), `OR` (`||`), `NOT` (`!`) logical operators and parentheses: \n\ - * `NOT feature.Name_1=A`: Select all rows where Name_1 is not A. \n* `feature.Name_1!=A,B,C`:\ - \ Select all rows where Name_1 is not A, B, or C. \n* `feature.Name_1=A\ - \ AND feature.Name_2=B`: Select all rows where Name_1 is A and Name_2 is\ - \ B. \n* `feature.Name_1=A && feature.Name_2=B`: Equivalent to the example\ - \ above. \n* `feature.Name_1=A OR feature.Name_2=B`: Select all rows where\ - \ Name_1 is A or Name_2 is B. \n* `feature.Name_1=A || feature.Name_2=B`:\ - \ Equivalent to the example above. \n* `feature.Name_1=A AND (feature.Name_2=B\ - \ OR value>=1.0)`: Select all rows where Name_1 is A and either Name_2 is\ - \ B or minimal possible measurement value is 1.0." - in: query - name: exQuery - schema: - type: string - - description: "Filter by expression metadata (key-value metadata pair(s)).\ - \ E.g. `\"Genome Version\"=hg19-BROAD`." - in: query - name: exFilter - schema: - type: string - - description: "Search for objects linked to flow cytometry data via data query\ - \ (key-value pair(s)). E.g. `ReadoutType=Median|Count` `CellPopulation=\"\ - CD45+, live\"` `MinValue=3.5`" - in: query - name: fxQuery - schema: - type: string - - description: "Filter by flow cytometry metadata (key-value metadata pair(s)).\ - \ E.g. `Organ=blood`." - in: query - name: fxFilter - schema: - type: string - - description: |- - Specify which versions of omics data files are used in the query. By default the active version is used. See Versioning above. Syntax: - - \* or `v` or ``:`v` or ``:`` - in: query - name: useVersions - schema: - type: string - - description: |- - The parameter defines amount of metadata attributes to return: - - 1. `minimal_data` - return metadata attributes according to the default template. - 2. `extended_data_included` - return metadata attributes according to applied template, if object doesn’t have applied template default template will be used. This is the default for User endpoints. - 3. `original_data_included` - return all metadata attributes with values and null attributes, if they are present in the applied template. This is the default for Curator endpoints. - in: query - name: returnedMetadataFields - schema: - enum: - - minimal_data - - extended_data_included - - original_data_included - type: string - - description: The page tag to resume results from (see paging above). - in: query - name: cursor - schema: - type: string - - description: "This parameter determines the number of results to retrieve\ - \ per page, with the default set at 2000." - in: query - name: pageLimit - schema: - format: int32 - type: integer - responses: - "200": - content: - application/json: - schema: - $ref: "#/components/schemas/OmicsResponse" - description: Omics query result. - "400": - content: {} - description: Invalid data in request. See error message for details. - "401": - content: {} - description: |- - User is not authenticated. Please supply a valid Access Token in the `Authorization` HTTP header (e.g. Authorization: bearer [token]) - or Genestack API token in the `Genestack-API-Token` header (this token may be obtained from the Genestack UI _Profile_ page). - "500": - content: {} - description: "An internal server error occurred. This indicates an unexpected\ - \ failure in the Genestack system, please file a bug report to support@genestack.com,\ - \ including the error details." - security: - - Access-token: [] - - Genestack-API-Token: [] - summary: Retrieve sample metadata objects by searching across multiple data - types - tags: - - Omics queries as User - /api/v1/as-user/omics/variant/data: - get: - description: |+ - Retrieve variant data objects whose linked data matches all supplied conditions. - - Note: A variant data query must be supplied. - - ## Conditions - It is possible to supply conditions for: - - 1. Samples (full-text or metadata key-value pair) - 2. Parent studies (full-text or metadata key-value pair) - 3. Linked variant objects (list of data key-value pairs) - 4. Linked expression objects (list of data key-value pairs) - 5. Linked any data (except variant and flow cytometry) objects (list of data key-value pairs) - - ## Metadata full-text queries - Single words can be supplied as is; otherwise, use speech marks (`"`) to quote queries that include whitespace. Speech marks and backslash characters in the query need to be escaped with a backslash (`\`). - - ## Metadata filters - Metadata filters are key-value pairs joined by an operator. The `=` operator matches literal values/string. The `!=` operator matches anything except the literal value/string. The `<` or `>` operators match numerical results that are less or greater than the supplied value. Strings containing whitespace need to be quoted with (`"`). - - ## Data queries - Data queries must be a list of key-value pairs, separated by whitespace. The set of valid keys depends on the specific query type, and is documented in the query parameter summary. The values can be simple non-whitespace strings, or strings enclosed by speech marks (`"`). Depending on the key, the value may be be a comma-delimited list of string values. Others require numerical values. - - ## Combinations - Metadata queries/filters for the same parameter can be combined with `&&`, `AND`, `||` and `OR` operators, using white-space to separate out the terms and operators. Parentheses `( )` can be used for complex expressions. - - ## Versioning - Specific versions of omics data files (eg. GCT) can be queried via the useVersions parameter. Different versions of an omics data file are associated via their CHAIN_ID metadata value. This CHAIN_ID can be supplied to the useVersions parameter along with the version number or specific omics data file accessions to include them in the query. If nothing is supplied to the useVersions parameter then only the active version (which is usually the last one imported) is queried. This acts as a filter before the rest of the query is carried out. - - Example usage: - useVersions=* (query all versions, including those without CHAIN_IDs) - useVersions=v2 (query the second version. If there is no second version then the data file is not queried) - useVersions=v1,v0 (query the first version and any data files without CHAIN_IDs(v0) ) - useVersions=GSVC002:v3 (for omics data files with a CHAIN_ID of GSCV002 query the third version) - useVersions=GSVC002:GSF00494,GSF000496 (for omics data files with a CHAIN_ID of GSCV002 query only the specific accessions GSF00494 and GSF000496) - - Rules for multiple CHAIN_IDs can be supplied to the parameter using the ; separator. - - ## Paging - For performance reasons this endpoint returns results in "pages" of limited size together with a cursor tag. To retrieve the next page of results please supply this cursor tag to resume the query from your previous result and get the next page. If there are no more results you will just retrieve an empty result. To return all results iterate through pages using cursor values until the `resultsExhausted` response field is true. - - operationId: omicsSearchVariantDataAsUser - parameters: - - description: Supply this parameter with the value `term_id` as part of the - query to return extended information including IDs for values and dictionaries. - in: query - name: responseFormat - schema: - $ref: "#/components/schemas/ResponseFormat" - - description: | - Filter by study metadata (key-value metadata pair(s)). E.g. `"Study Source"=ArrayExpress` - in: query - name: studyFilter - schema: - type: string - - description: Search for objects via a full-text query over all study metadata - fields. E.g. `"RNA-Seq of human dendritic cells"`. Queries matching dictionary - terms are automatically expanded to include synonyms. - in: query - name: studyQuery - schema: - type: string - - description: | - Filter by sample metadata (key-value metadata pair(s)). E.g. `"Species or strain"="Homo sapiens"` - in: query - name: sampleFilter - schema: - type: string - - description: Search for objects via a full-text query over all sample metadata - fields. E.g. `Clozapine`. Queries matching dictionary terms are automatically - expanded to include synonyms. - in: query - name: sampleQuery - schema: - type: string - - description: Filter by library metadata (key-value metadata pair(s)). E.g. - `"Library Type"=RNA-Seq-1` - in: query - name: libraryFilter - schema: - type: string - - description: Search for library objects via a full-text query over all library - metadata fields. E.g. `"illumina HiSeq500"`. Queries matching dictionary - terms are automatically expanded to include synonyms. - in: query - name: libraryQuery - schema: - type: string - - description: Filter by preparation metadata (key-value metadata pair(s)). - E.g. `Digestion=Trypsin` - in: query - name: preparationFilter - schema: - type: string - - description: Search for preparation objects via a full-text query over all - preparation metadata fields. E.g. `"reversed-phase liquid chromatography"`. - Queries matching dictionary terms are automatically expanded to include - synonyms. - in: query - name: preparationQuery - schema: - type: string - - description: |- - If the full-text query term is present in an ODM dictionary, enabling this parameter will modify the query to include child terms of the full-text query. - - For example, the search query "Body fluid" can be expanded to include the term "Blood" (a child term of "Body fluid") so files containing either "Body fluid" or "Blood" in their metadata will be returned in the search results. - - The parent-child relationship is defined by the key "broaders" or "subClassOf" in the dictionary. - - If the full query term is not present in a dictionary then this parameter has no effect. - in: query - name: searchSpecificTerms - schema: - type: boolean - - description: "Search for objects linked to variant data by SNPs properties. Filtering is currently supported by `filter`, `id`, `region` and `info` keywords, - as well as `exists` keyword for `INFO` field and their logical combinations by means of `not` (`!`), `and` (`&&`), and `or` (`||`) operators with standard boolean precedence. Keyword case is ignored.\n - * `filter` corresponds to the `FILTER` column in the original vcf file. Could be either equals or not equals to `PASS` : `filter = PASS` - or `filter != pass`.\n - * `id` is a string value that corresponds to the `ID` column. Multiple values could be added via a comma. Expression `id = rs3214,rg1234` is equivalent - to `id = rs3214 or id = rg1234`.\n - * `region` corresponds to CHROM and POS columns. Supports querying by the whole chromosome `region = chr1` , by interval within a chromosome - `region = chr1:4567-9876543` by exact position `region = chr1:456789` or by indefinite ranges like `region = x:3456789-*` . Multiple regions could be - separated via comma, e.g. `region = chr1:34567-98767,chr3` is equivalent to `region = chr1:34567-98767 or region = chr3`.\n - * `feature` is the name of the reference gene associated with a specific location in the reference genome which corresponds to the VCF file (variant group) from which the variant information is derived. - By providing the gene name(s), such as `feature=TP53` or `feature=TP53,TGFB`, variants located within the same genomic region as the specified gene(s) will be retrieved.\n - * Filter by vcf `INFO` fields. E.g. to filter all variants annotated in dbSNP add `exists(INFO.KEY)`. Use `!exists(INFO.KEY)` to exclude variants having the key from the search results. - Provide `info.key=value` pair to search for an exact match or `info.key!=value` to exclude it from the search. Due to the limits of precision in floating point numbers, - we use a small range of 0.0000001 to identify close matches. This means any differences smaller than that won't be detected. For more precise results, please use range queries." - in: query - name: vxQuery - schema: - type: string - - description: "Filter by variant metadata (key-value metadata pair(s)). E.g.\ - \ `\"Variant Source\"=dbSNP`." - in: query - name: vxFilter - schema: - type: string - - description: "Search for objects linked to expression data and originally\ - \ uploaded in TSV or GCT format via data query, e.g., `feature=ENSG00000230368,ENSG00000188976\ - \ value>=1.50`\n For the case when the original data is represented by multiple\ - \ attributes per feature scenarios, extended filtering syntax is as follows:\ - \ \n1. By feature attribute value for numeric and string attributes: `feature.NAME=1007_s_at`\ - \ or `feature.\"Average Mz\"=2.218`. As in the case of sample metadata queries,\ - \ single words can be supplied as is; otherwise, use speech marks (`\"`)\ - \ to quote queries that include whitespace. \n2. It is possible to specify\ - \ a set of possible values, separated by comma: `feature.NAME=1007_s_at,121_at`.\ - \ \n3. Utilize range filters to search numeric attributes. Apply `<` (less\ - \ than), `>` (greater than), and `=` (equal to) symbols to specify the desired\ - \ ranges as follows: \n`feature.Name_1 > 3`: Select all rows where the feature\ - \ attribute Name_1 values are greater than 3. \n`feature.Name_2 >= 6`: Select\ - \ all rows where the feature attribute Name_2 values are greater than or\ - \ equal to 6. \n`-3 < feature.Name_3 < 3`: Select all rows where the feature\ - \ attribute Name_3 values lie within the interval between -3 and 3. \n4.\ - \ Use substring search to get the records where the attribute field contains\ - \ the provided substring: `feature.attribute1 =~ \"some text\"`. \n5. The\ - \ first column for each original data file is identified as feature accession\ - \ (typically, it contains gene or protein names, accession IDs, etc.). Searching\ - \ by such feature accession would significantly outperform more complex\ - \ queries by combining the other feature attributes. To enable such a search,\ - \ use `feature` without any attribute extension, e.g., `feature=ENSG00000230368,ENSG00000188976`.\n\ - \ \nThe `value` keyword can be used to select rows where the sample (library\ - \ or preparation) measurements has values from a certain range. Examples:\ - \ `value = 3`, `value > 3`, `-3 < value < 3`. When the original data contains\ - \ multiple measurements for a single item, such as a sample (library or\ - \ preparation), use the measurement name to specify the exact column type,\ - \ e.g.: \n1. `value.intensity = 3`: Selects all rows where the measurement\ - \ attribute intensity equals 3. \n `value.intensity != 2,null`: Select all\ - \ rows where the measurement attribute intensity is not equal 2 and is not\ - \ an empty value. \n`value.p_value > 3`: Selects all rows where the measurement\ - \ attribute 'p_value' values are greater than 3. \n`-3 < value.FC < 3`:\ - \ Selects all rows where the measurement attribute 'FC' values lie within\ - \ the interval between -3 and 3.\n \n2. Note: The `MinValue` keyword has\ - \ been deprecated and should be replaced with the aforementioned comparisons.\n\ - \ \nCombine multiple filters for different feature attributes and measurements\ - \ using `AND` (`&&`), `OR` (`||`), `NOT` (`!`) logical operators and parentheses: \n\ - * `NOT feature.Name_1=A`: Select all rows where Name_1 is not A. \n* `feature.Name_1!=A,B,C`:\ - \ Select all rows where Name_1 is not A, B, or C. \n* `feature.Name_1=A\ - \ AND feature.Name_2=B`: Select all rows where Name_1 is A and Name_2 is\ - \ B. \n* `feature.Name_1=A && feature.Name_2=B`: Equivalent to the example\ - \ above. \n* `feature.Name_1=A OR feature.Name_2=B`: Select all rows where\ - \ Name_1 is A or Name_2 is B. \n* `feature.Name_1=A || feature.Name_2=B`:\ - \ Equivalent to the example above. \n* `feature.Name_1=A AND (feature.Name_2=B\ - \ OR value>=1.0)`: Select all rows where Name_1 is A and either Name_2 is\ - \ B or minimal possible measurement value is 1.0." - in: query - name: exQuery - schema: - type: string - - description: "Filter by expression metadata (key-value metadata pair(s)).\ - \ E.g. `\"Genome Version\"=hg19-BROAD`." - in: query - name: exFilter - schema: - type: string - - description: "Search for objects linked to flow cytometry data via data query\ - \ (key-value pair(s)). E.g. `ReadoutType=Median|Count` `CellPopulation=\"\ - CD45+, live\"` `MinValue=3.5`" - in: query - name: fxQuery - schema: - type: string - - description: "Filter by flow cytometry metadata (key-value metadata pair(s)).\ - \ E.g. `Organ=blood`." - in: query - name: fxFilter - schema: - type: string - - description: |- - Specify which versions of omics data files are used in the query. By default the active version is used. See Versioning above. Syntax: - - \* or `v` or ``:`v` or ``:`` - in: query - name: useVersions - schema: - type: string - - description: |- - The parameter defines amount of metadata attributes to return: - - 1. `minimal_data` - return metadata attributes according to the default template. - 2. `extended_data_included` - return metadata attributes according to applied template, if object doesn’t have applied template default template will be used. This is the default for User endpoints. - 3. `original_data_included` - return all metadata attributes with values and null attributes, if they are present in the applied template. This is the default for Curator endpoints. - in: query - name: returnedMetadataFields - schema: - enum: - - minimal_data - - extended_data_included - - original_data_included - type: string - - description: The page tag to resume results from (see paging above). - in: query - name: cursor - schema: - type: string - - description: "This parameter determines the number of results to retrieve\ - \ per page, with the default set at 2000." - in: query - name: pageLimit - schema: - format: int32 - type: integer - responses: - "200": - content: - application/json: - schema: - $ref: "#/components/schemas/OmicsResponse" - description: Omics query result. - "400": - content: {} - description: Invalid data in request. See error message for details. - "401": - content: {} - description: |- - User is not authenticated. Please supply a valid Access Token in the `Authorization` HTTP header (e.g. Authorization: bearer [token]) - or Genestack API token in the `Genestack-API-Token` header (this token may be obtained from the Genestack UI _Profile_ page). - "500": - content: {} - description: "An internal server error occurred. This indicates an unexpected\ - \ failure in the Genestack system, please file a bug report to support@genestack.com,\ - \ including the error details." - security: - - Access-token: [] - - Genestack-API-Token: [] - summary: Retrieve variant data objects by searching across multiple data types - tags: - - Omics queries as User - /api/v1/as-user/omics/variant/group: - get: - description: |+ - Retrieve group objects whose linked data matches all supplied conditions. - - ## Conditions - It is possible to supply conditions for: - - 1. Samples (full-text or metadata key-value pair) - 2. Parent studies (full-text or metadata key-value pair) - 3. Linked variant objects (list of data key-value pairs) - 4. Linked flow cytometry objects (list of data key-value pairs) - 5. Linked any data (except variant and flow cytometry) objects (list of data key-value pairs) - - ## Metadata full-text queries - Single words can be supplied as is; otherwise, use speech marks (`"`) to quote queries that include whitespace. Speech marks and backslash characters in the query need to be escaped with a backslash (`\`). - - ## Metadata filters - Metadata filters are key-value pairs joined by an operator. The `=` operator matches literal values/string. The `!=` operator matches anything except the literal value/string. The `<` or `>` operators match numerical results that are less or greater than the supplied value. Strings containing whitespace need to be quoted with (`"`). - - ## Data queries - Data queries must be a list of key-value pairs, separated by whitespace. The set of valid keys depends on the specific query type, and is documented in the query parameter summary. The values can be simple non-whitespace strings, or strings enclosed by speech marks (`"`). Depending on the key, the value may be be a comma-delimited list of string values. Others require numerical values. - - ## Combinations - Metadata queries/filters for the same parameter can be combined with `&&`, `AND`, `||` and `OR` operators, using white-space to separate out the terms and operators. Parentheses `( )` can be used for complex expressions. - - ## Versioning - Specific versions of omics data files (eg. GCT) can be queried via the useVersions parameter. Different versions of an omics data file are associated via their CHAIN_ID metadata value. This CHAIN_ID can be supplied to the useVersions parameter along with the version number or specific omics data file accessions to include them in the query. If nothing is supplied to the useVersions parameter then only the active version (which is usually the last one imported) is queried. This acts as a filter before the rest of the query is carried out. - - Example usage: - useVersions=* (query all versions, including those without CHAIN_IDs) - useVersions=v2 (query the second version. If there is no second version then the data file is not queried) - useVersions=v1,v0 (query the first version and any data files without CHAIN_IDs(v0) ) - useVersions=GSVC002:v3 (for omics data files with a CHAIN_ID of GSCV002 query the third version) - useVersions=GSVC002:GSF00494,GSF000496 (for omics data files with a CHAIN_ID of GSCV002 query only the specific accessions GSF00494 and GSF000496) - - Rules for multiple CHAIN_IDs can be supplied to the parameter using the ; separator. - - ## Paging - For performance reasons this endpoint returns results in "pages" of limited size together with a cursor tag. To retrieve the next page of results please supply this cursor tag to resume the query from your previous result and get the next page. If there are no more results you will just retrieve an empty result. To return all results iterate through pages using cursor values until the `resultsExhausted` response field is true. - - operationId: omicsSearchVariantGroupsAsUser - parameters: - - description: Supply this parameter with the value `term_id` as part of the - query to return extended information including IDs for values and dictionaries. - in: query - name: responseFormat - schema: - $ref: "#/components/schemas/ResponseFormat" - - description: | - Filter by study metadata (key-value metadata pair(s)). E.g. `"Study Source"=ArrayExpress` - in: query - name: studyFilter - schema: - type: string - - description: Search for objects via a full-text query over all study metadata - fields. E.g. `"RNA-Seq of human dendritic cells"`. Queries matching dictionary - terms are automatically expanded to include synonyms. - in: query - name: studyQuery - schema: - type: string - - description: | - Filter by sample metadata (key-value metadata pair(s)). E.g. `"Species or strain"="Homo sapiens"` - in: query - name: sampleFilter - schema: - type: string - - description: Search for objects via a full-text query over all sample metadata - fields. E.g. `Clozapine`. Queries matching dictionary terms are automatically - expanded to include synonyms. - in: query - name: sampleQuery - schema: - type: string - - description: Filter by library metadata (key-value metadata pair(s)). E.g. - `"Library Type"=RNA-Seq-1` - in: query - name: libraryFilter - schema: - type: string - - description: Search for library objects via a full-text query over all library - metadata fields. E.g. `"illumina HiSeq500"`. Queries matching dictionary - terms are automatically expanded to include synonyms. - in: query - name: libraryQuery - schema: - type: string - - description: Filter by preparation metadata (key-value metadata pair(s)). - E.g. `Digestion=Trypsin` - in: query - name: preparationFilter - schema: - type: string - - description: Search for preparation objects via a full-text query over all - preparation metadata fields. E.g. `"reversed-phase liquid chromatography"`. - Queries matching dictionary terms are automatically expanded to include - synonyms. - in: query - name: preparationQuery - schema: - type: string - - description: |- - If the full-text query term is present in an ODM dictionary, enabling this parameter will modify the query to include child terms of the full-text query. - - For example, the search query "Body fluid" can be expanded to include the term "Blood" (a child term of "Body fluid") so files containing either "Body fluid" or "Blood" in their metadata will be returned in the search results. - - The parent-child relationship is defined by the key "broaders" or "subClassOf" in the dictionary. - - If the full query term is not present in a dictionary then this parameter has no effect. - in: query - name: searchSpecificTerms - schema: - type: boolean - - description: "Search for objects linked to variant data by SNPs properties. Filtering is currently supported by `filter`, `id`, `region` and `info` keywords, - as well as `exists` keyword for `INFO` field and their logical combinations by means of `not` (`!`), `and` (`&&`), and `or` (`||`) operators with standard boolean precedence. Keyword case is ignored.\n - * `filter` corresponds to the `FILTER` column in the original vcf file. Could be either equals or not equals to `PASS` : `filter = PASS` - or `filter != pass`.\n - * `id` is a string value that corresponds to the `ID` column. Multiple values could be added via a comma. Expression `id = rs3214,rg1234` is equivalent - to `id = rs3214 or id = rg1234`.\n - * `region` corresponds to CHROM and POS columns. Supports querying by the whole chromosome `region = chr1` , by interval within a chromosome - `region = chr1:4567-9876543` by exact position `region = chr1:456789` or by indefinite ranges like `region = x:3456789-*` . Multiple regions could be - separated via comma, e.g. `region = chr1:34567-98767,chr3` is equivalent to `region = chr1:34567-98767 or region = chr3`.\n - * `feature` is the name of the reference gene associated with a specific location in the reference genome which corresponds to the VCF file (variant group) from which the variant information is derived. - By providing the gene name(s), such as `feature=TP53` or `feature=TP53,TGFB`, variants located within the same genomic region as the specified gene(s) will be retrieved.\n - * Filter by vcf `INFO` fields. E.g. to filter all variants annotated in dbSNP add `exists(INFO.KEY)`. Use `!exists(INFO.KEY)` to exclude variants having the key from the search results. - Provide `info.key=value` pair to search for an exact match or `info.key!=value` to exclude it from the search. Due to the limits of precision in floating point numbers, - we use a small range of 0.0000001 to identify close matches. This means any differences smaller than that won't be detected. For more precise results, please use range queries." - in: query - name: vxQuery - schema: - type: string - - description: "Filter by variant metadata (key-value metadata pair(s)). E.g.\ - \ `\"Variant Source\"=dbSNP`." - in: query - name: vxFilter - schema: - type: string - - description: "Search for objects linked to expression data and originally\ - \ uploaded in TSV or GCT format via data query, e.g., `feature=ENSG00000230368,ENSG00000188976\ - \ value>=1.50`\n For the case when the original data is represented by multiple\ - \ attributes per feature scenarios, extended filtering syntax is as follows:\ - \ \n1. By feature attribute value for numeric and string attributes: `feature.NAME=1007_s_at`\ - \ or `feature.\"Average Mz\"=2.218`. As in the case of sample metadata queries,\ - \ single words can be supplied as is; otherwise, use speech marks (`\"`)\ - \ to quote queries that include whitespace. \n2. It is possible to specify\ - \ a set of possible values, separated by comma: `feature.NAME=1007_s_at,121_at`.\ - \ \n3. Utilize range filters to search numeric attributes. Apply `<` (less\ - \ than), `>` (greater than), and `=` (equal to) symbols to specify the desired\ - \ ranges as follows: \n`feature.Name_1 > 3`: Select all rows where the feature\ - \ attribute Name_1 values are greater than 3. \n`feature.Name_2 >= 6`: Select\ - \ all rows where the feature attribute Name_2 values are greater than or\ - \ equal to 6. \n`-3 < feature.Name_3 < 3`: Select all rows where the feature\ - \ attribute Name_3 values lie within the interval between -3 and 3. \n4.\ - \ Use substring search to get the records where the attribute field contains\ - \ the provided substring: `feature.attribute1 =~ \"some text\"`. \n5. The\ - \ first column for each original data file is identified as feature accession\ - \ (typically, it contains gene or protein names, accession IDs, etc.). Searching\ - \ by such feature accession would significantly outperform more complex\ - \ queries by combining the other feature attributes. To enable such a search,\ - \ use `feature` without any attribute extension, e.g., `feature=ENSG00000230368,ENSG00000188976`.\n\ - \ \nThe `value` keyword can be used to select rows where the sample (library\ - \ or preparation) measurements has values from a certain range. Examples:\ - \ `value = 3`, `value > 3`, `-3 < value < 3`. When the original data contains\ - \ multiple measurements for a single item, such as a sample (library or\ - \ preparation), use the measurement name to specify the exact column type,\ - \ e.g.: \n1. `value.intensity = 3`: Selects all rows where the measurement\ - \ attribute intensity equals 3. \n `value.intensity != 2,null`: Select all\ - \ rows where the measurement attribute intensity is not equal 2 and is not\ - \ an empty value. \n`value.p_value > 3`: Selects all rows where the measurement\ - \ attribute 'p_value' values are greater than 3. \n`-3 < value.FC < 3`:\ - \ Selects all rows where the measurement attribute 'FC' values lie within\ - \ the interval between -3 and 3.\n \n2. Note: The `MinValue` keyword has\ - \ been deprecated and should be replaced with the aforementioned comparisons.\n\ - \ \nCombine multiple filters for different feature attributes and measurements\ - \ using `AND` (`&&`), `OR` (`||`), `NOT` (`!`) logical operators and parentheses: \n\ - * `NOT feature.Name_1=A`: Select all rows where Name_1 is not A. \n* `feature.Name_1!=A,B,C`:\ - \ Select all rows where Name_1 is not A, B, or C. \n* `feature.Name_1=A\ - \ AND feature.Name_2=B`: Select all rows where Name_1 is A and Name_2 is\ - \ B. \n* `feature.Name_1=A && feature.Name_2=B`: Equivalent to the example\ - \ above. \n* `feature.Name_1=A OR feature.Name_2=B`: Select all rows where\ - \ Name_1 is A or Name_2 is B. \n* `feature.Name_1=A || feature.Name_2=B`:\ - \ Equivalent to the example above. \n* `feature.Name_1=A AND (feature.Name_2=B\ - \ OR value>=1.0)`: Select all rows where Name_1 is A and either Name_2 is\ - \ B or minimal possible measurement value is 1.0." - in: query - name: exQuery - schema: - type: string - - description: "Filter by expression metadata (key-value metadata pair(s)).\ - \ E.g. `\"Genome Version\"=hg19-BROAD`." - in: query - name: exFilter - schema: - type: string - - description: "Search for objects linked to flow cytometry data via data query\ - \ (key-value pair(s)). E.g. `ReadoutType=Median|Count` `CellPopulation=\"\ - CD45+, live\"` `MinValue=3.5`" - in: query - name: fxQuery - schema: - type: string - - description: "Filter by flow cytometry metadata (key-value metadata pair(s)).\ - \ E.g. `Organ=blood`." - in: query - name: fxFilter - schema: - type: string - - description: "Unique identifier (accession) of Reference Genome object." - in: query - name: referenceGenomeId - schema: - type: string - - description: |- - Specify which versions of omics data files are used in the query. By default the active version is used. See Versioning above. Syntax: - - \* or `v` or ``:`v` or ``:`` - in: query - name: useVersions - schema: - type: string - - description: |- - The parameter defines amount of metadata attributes to return: - - 1. `minimal_data` - return metadata attributes according to the default template. - 2. `extended_data_included` - return metadata attributes according to applied template, if object doesn’t have applied template default template will be used. This is the default for User endpoints. - 3. `original_data_included` - return all metadata attributes with values and null attributes, if they are present in the applied template. This is the default for Curator endpoints. - in: query - name: returnedMetadataFields - schema: - enum: - - minimal_data - - extended_data_included - - original_data_included - type: string - - description: The page tag to resume results from (see paging above). - in: query - name: cursor - schema: - type: string - - description: "This parameter determines the number of results to retrieve\ - \ per page, with the default set at 2000." - in: query - name: pageLimit - schema: - format: int32 - type: integer - responses: - "200": - content: - application/json: - schema: - $ref: "#/components/schemas/OmicsResponse" - description: Omics query result. - "400": - content: {} - description: Invalid data in request. See error message for details. - "401": - content: {} - description: |- - User is not authenticated. Please supply a valid Access Token in the `Authorization` HTTP header (e.g. Authorization: bearer [token]) - or Genestack API token in the `Genestack-API-Token` header (this token may be obtained from the Genestack UI _Profile_ page). - "500": - content: {} - description: "An internal server error occurred. This indicates an unexpected\ - \ failure in the Genestack system, please file a bug report to support@genestack.com,\ - \ including the error details." - security: - - Access-token: [] - - Genestack-API-Token: [] - summary: Retrieve group objects by searching across multiple data types - tags: - - Omics queries as User - /api/v1/as-user/omics/variant/streamed-data: - get: - description: |+ - Stream data from a given group for a VCF file that matches a sample query/filter. If no query/filters are supplied all variant data is returned. If a metadata filter is specified, this endpoint will only return variant data that is associated with a sample via metadata attribute. - - ## Conditions - It is possible to supply conditions for Samples (full-text or metadata key-value pair) - - ## Metadata full-text queries - Single words can be supplied as is; otherwise, use speech marks (`"`) to quote queries that include whitespace. Speech marks and backslash characters in the query need to be escaped with a backslash (`\`). - - ## Metadata filters - Metadata filters are key-value pairs joined by an operator. The `=` operator matches literal values/string. The `!=` operator matches anything except the literal value/string. The `<` or `>` operators match numerical results that are less or greater than the supplied value. Strings containing whitespace need to be quoted with (`"`). - - ## Combinations - Metadata queries/filters for the same parameter can be combined with `&&`, `AND`, `||` and `OR` operators, using white-space to separate out the terms and operators. Parentheses `( )` can be used for complex expressions. - - operationId: omicsSearchStreamedVariantDataAsUser - parameters: - - description: | - Filter by sample metadata (key-value metadata pair(s)). E.g. `"Species or strain"="Homo sapiens"` - in: query - name: sampleFilter - schema: - type: string - - description: Search for objects via a full-text query over all sample metadata - fields. E.g. `Clozapine`. Queries matching dictionary terms are automatically - expanded to include synonyms. - in: query - name: sampleQuery - schema: - type: string - - description: |- - If the full-text query term is present in an ODM dictionary, enabling this parameter will modify the query to include child terms of the full-text query. - - For example, the search query "Body fluid" can be expanded to include the term "Blood" (a child term of "Body fluid") so files containing either "Body fluid" or "Blood" in their metadata will be returned in the search results. - - The parent-child relationship is defined by the key "broaders" or "subClassOf" in the dictionary. - - If the full query term is not present in a dictionary then this parameter has no effect. - in: query - name: searchSpecificTerms - schema: - type: boolean - - description: "Search for objects linked to expression data and originally\ - \ uploaded in TSV or GCT format via data query, e.g., `feature=ENSG00000230368,ENSG00000188976\ - \ value>=1.50`\n For the case when the original data is represented by multiple\ - \ attributes per feature scenarios, extended filtering syntax is as follows:\ - \ \n1. By feature attribute value for numeric and string attributes: `features.NAME=1007_s_at`\ - \ or `features.\"Average Mz\"=2.218`. As in the case of sample metadata\ - \ queries, single words can be supplied as is; otherwise, use speech marks\ - \ (`\"`) to quote queries that include whitespace. \n2. It is possible to\ - \ specify a set of possible values, separated by comma: `features.NAME=1007_s_at,121_at`.\ - \ \n3. Utilize range filters to search numeric attributes. Apply `<` (less\ - \ than), `>` (greater than), and `=` (equal to) symbols to specify the desired\ - \ ranges as follows: \n`features.Name_1 > 3`: Select all rows where the\ - \ feature attribute Name_1 values are greater than 3. \n`features.Name_2\ - \ >= 6`: Select all rows where the feature attribute Name_2 values are greater\ - \ than or equal to 6. \n`-3 < features.Name_3 < 3`: Select all rows where\ - \ the feature attribute Name_3 values lie within the interval between -3\ - \ and 3. \n4. Use substring search to get the records where the attribute\ - \ field contains the provided substring: `features.attribute1 =~ \"some\ - \ text\"`. \n5. The first column for each original data file is identified\ - \ as feature accession (typically, it contains gene or protein names, accession\ - \ IDs, etc.). Searching by such feature accession would significantly outperform\ - \ more complex queries by combining the other feature attributes. To enable\ - \ such a search, use `feature` without any attribute extension, e.g., `feature=ENSG00000230368,ENSG00000188976`.\n\ - \ \nThe `value` keyword can be used to select rows where the sample (library\ - \ or preparation) measurements has values from a certain range. Examples:\ - \ `value = 3`, `value > 3`, `-3 < value < 3`. When the original data contains\ - \ multiple measurements for a single item, such as a sample (library or\ - \ preparation), use the measurement name to specify the exact column type,\ - \ e.g.: \n1. `value.intensity = 3`: Selects all rows where the measurement\ - \ attribute intensity equals 3. \n `value.intensity != 2,null`: Select all\ - \ rows where the measurement attribute intensity is not equal 2 and is not\ - \ an empty value. \n`values.p_value > 3`: Selects all rows where the measurement\ - \ attribute 'p_value' values are greater than 3. \n`-3 < values.FC < 3`:\ - \ Selects all rows where the measurement attribute 'FC' values lie within\ - \ the interval between -3 and 3.\n \n2. Note: The `MinValue` keyword has\ - \ been deprecated and should be replaced with the aforementioned comparisons.\n\ - \ \nCombine multiple filters for different feature attributes and measurements\ - \ using `AND` (`&&`), `OR` (`||`) logical operators and parentheses: \n\ - * `features.Name_1!=A`: Select all rows where Name_1 is not A. \n* `features.Name_1!=A,B,C`:\ - \ Select all rows where Name_1 is not A, B, or C. \n* `features.Name_1=A\ - \ AND features.Name_2=B`: Select all rows where Name_1 is A and Name_2 is\ - \ B. \n* `features.Name_1=A && features.Name_2=B`: Equivalent to the example\ - \ above. \n* `features.Name_1=A OR features.Name_2=B`: Select all rows where\ - \ Name_1 is A or Name_2 is B. \n* `features.Name_1=A || features.Name_2=B`:\ - \ Equivalent to the example above. \n* `features.Name_1=A AND (features.Name_2=B\ - \ OR value>=1.0)`: Select all rows where Name_1 is A and either Name_2 is\ - \ B or minimal possible measurement value is 1.0." - in: query - name: exQuery - schema: - type: string - - description: "Search for objects linked to variant data by SNPs properties. Filtering is currently supported by `filter`, `id`, `region` and `info` keywords, - as well as `exists` keyword for `INFO` field and their logical combinations by means of `not` (`!`), `and` (`&&`), and `or` (`||`) operators with standard boolean precedence. Keyword case is ignored.\n - * `filter` corresponds to the `FILTER` column in the original vcf file. Could be either equals or not equals to `PASS` : `filter = PASS` - or `filter != pass`.\n - * `id` is a string value that corresponds to the `ID` column. Multiple values could be added via a comma. Expression `id = rs3214,rg1234` is equivalent - to `id = rs3214 or id = rg1234`.\n - * `region` corresponds to CHROM and POS columns. Supports querying by the whole chromosome `region = chr1` , by interval within a chromosome - `region = chr1:4567-9876543` by exact position `region = chr1:456789` or by indefinite ranges like `region = x:3456789-*` . Multiple regions could be - separated via comma, e.g. `region = chr1:34567-98767,chr3` is equivalent to `region = chr1:34567-98767 or region = chr3`.\n - * `feature` is the name of the reference gene associated with a specific location in the reference genome which corresponds to the VCF file (variant group) from which the variant information is derived. - By providing the gene name(s), such as `feature=TP53` or `feature=TP53,TGFB`, variants located within the same genomic region as the specified gene(s) will be retrieved.\n - * Filter by vcf `INFO` fields. E.g. to filter all variants annotated in dbSNP add `exists(INFO.KEY)`. Use `!exists(INFO.KEY)` to exclude variants having the key from the search results. - Provide `info.key=value` pair to search for an exact match or `info.key!=value` to exclude it from the search. Due to the limits of precision in floating point numbers, - we use a small range of 0.0000001 to identify close matches. This means any differences smaller than that won't be detected. For more precise results, please use range queries." - in: query - name: vxQuery - schema: - type: string - - description: Accession of the variant group object (VCF) - in: query - name: groupAccession - required: true - schema: - type: string - responses: - "200": - content: - text/tab-separated-values: - schema: - $ref: "#/components/schemas/StreamingOutput" - description: Stream of retrieved Variant data. - "400": - content: { } - description: Invalid data in request. See error message for details. - "401": - content: { } - description: |- - User is not authenticated. Please supply a valid Access Token in the `Authorization` HTTP header (e.g. Authorization: bearer [token]) - or Genestack API token in the `Genestack-API-Token` header (this token may be obtained from the Genestack UI _Profile_ page). - "500": - content: { } - description: "An internal server error occurred. This indicates an unexpected\ - \ failure in the Genestack system, please file a bug report to support@genestack.com,\ - \ including the error details." - security: - - Access-token: [ ] - - Genestack-API-Token: [ ] - summary: Stream data from a given VCF file - tags: - - Omics queries as User - /api/v1/as-user/omics/cells/analytics/cell-ratio: - post: - operationId: cellRatioAsUser - summary: "[BETA] Compute cell ratio statistics across groups or metadata attributes in single-cell data." - tags: - - "[BETA] Analytics omics queries as User" - description: |+ - This endpoint calculates cell ratio statistics based on single-cell metadata. - - It allows quantifying the proportion of cells that meet specific criteria (`countSelected`, e.g. expression threshold, cell type, or cluster) - relative to a defined reference group or the total cell population (`countAvailable`) defined by study, samples, library, or preparation metadata. - - `countAvailable` parameter returns all cells specified in study, sample, library, or preparation queries and filters. - In case `exQuery` is selected, only cells linked to cell expression will be counted in `countSelected` parameter. - - The endpoint supports filtering by study, sample, library, or preparation metadata and filtering by cell expression or cell metadata fields. - - Request and response parameters are subject to change as this feature is in BETA. - requestBody: - content: - application/json: - schema: - $ref: "#/components/schemas/CRRequest" - required: true - responses: - "200": - content: - application/json: - schema: - $ref: "#/components/schemas/CRResponse" - description: Cell ratio result - "400": - content: { } - description: Entities cannot be retrieved. - "401": - content: { } - description: |- - User is not authenticated. Please supply a valid Access Token in the `Authorization` HTTP header (e.g. Authorization: bearer [token]) - or Genestack API token in the `Genestack-API-Token` header (this token may be obtained from the Genestack UI _Profile_ page). - "500": - content: { } - description: "An internal server error occurred. This indicates an unexpected\ - \ failure in the Genestack system, please file a bug report to support@genestack.com,\ - \ including the error details." - security: - - Access-token: [ ] - - Genestack-API-Token: [ ] - /api/v1/as-user/omics/cells/analytics/differential-expression: - post: - operationId: differentialExpressionAsUser - summary: "[BETA] Perform differential gene expression analytics between case and control cell groups" - tags: - - "[BETA] Analytics omics queries as User" - # The descriptions below are also duplicated in the schema description, make sure to keep them in sync. - description: |+ - This endpoint computes differential gene expression between two specified cell groups (case vs control) within single-cell data. - - Consult `/omics` search endpoints to find description of parameters within the cell groups. - The response includes per-gene metrics that characterize expression differences between the two groups: - - `Gene name` - gene identifier. - - `Case cell count` - number of cells expressing the gene in the case group. - - `Control cell count` - number of cells expressing the gene in the control group. - - `Average expression (case)` - mean expression level across case cells. - - `Average expression (control)` - mean expression level across control cells. - - `Expression difference` - numerical difference between average expressions. - - `Fold change` - ratio of average expressions between case and control groups. - - `U statistic` - Mann–Whitney U test statistic that measures the difference between Case and Control groups. - - `p-value` - the probability of observing results as extreme as (or more extreme than) those obtained, assuming that the null hypothesis is true. - - Results are sorted by absolute value of fold change in descending order, allowing easy identification of the most differentially expressed genes. - - Request and response parameters are subject to change as this feature is in BETA. - requestBody: - content: - application/json: - schema: - $ref: "#/components/schemas/DERequest" - required: true - responses: - "200": - content: - application/json: - schema: - $ref: "#/components/schemas/DEResponse" - description: Differential expression result - "400": - content: { } - description: Entities cannot be retrieved. - "401": - content: { } - description: |- - User is not authenticated. Please supply a valid Access Token in the `Authorization` HTTP header (e.g. Authorization: bearer [token]) - or Genestack API token in the `Genestack-API-Token` header (this token may be obtained from the Genestack UI _Profile_ page). - "500": - content: { } - description: "An internal server error occurred. This indicates an unexpected\ - \ failure in the Genestack system, please file a bug report to support@genestack.com,\ - \ including the error details." - security: - - Access-token: [ ] - - Genestack-API-Token: [ ] - /api/v1/as-user/omics/cells/analytics/gene-summary: - post: - operationId: geneSummaryAsUser - summary: "[BETA] Compute and retrieve descriptive statistics and visual summaries for single-cell data." - tags: - - "[BETA] Analytics omics queries as User" - description: |+ - This endpoint provides descriptive statistical metrics for gene expression across single-cell datasets. - It aggregates and summarizes expression data for each gene to help assess variability, distribution, - and intensity of expression within the population of cells. - - The computed metrics include: - - `Gene name` - gene identifier. - - `Cell count` - number of cells with measurable expression for each gene. - - `Mean expression value` - - `Median expression value` - - `Quantiles` - configurable expression percentiles. - - `Histogram (density)` - binned distribution of expression levels for visualization. - - `Standard deviation` - dispersion of expression values. - - `Minimum and maximum values` - range of expression across cells. - - Results are sorted by gene name. - - Request and response parameters are subject to change as this feature is in BETA. - requestBody: - required: true - content: - application/json: - schema: - $ref: "#/components/schemas/GSRequest" - responses: - "200": - description: Gene summary result - content: - application/json: - schema: - $ref: "#/components/schemas/GSResponse" - "400": - content: { } - description: Invalid data in the request. See the error message for details. - "401": - content: { } - description: |+ - User is not authenticated. Please supply a valid Access Token in the `Authorization` - HTTP header (e.g. Authorization: bearer [token]) or Genestack API token in the `Genestack-API-Token` - header (this token may be obtained from the Genestack UI _Profile_ page). - "500": - content: { } - description: |+ - An internal server error occurred. This indicates an unexpected - failure in the Genestack system, please file a bug report to support@genestack.com, - including the error details." - security: - - Access-token: [ ] - - Genestack-API-Token: [ ] - /api/v1/as-user/integration/link/files/by/study/{id}: - get: - operationId: getFilesByStudyAsUser - parameters: - - description: Unique identifier (accession) of the object. - in: path - name: id - required: true - schema: - type: string - - description: Select `true` in order to include file structure (contents) for .h5, .h5ad, .zip, .gz to the response. - in: query - name: includeContents - required: false - schema: - default: false - type: boolean - responses: - "200": - content: - application/json: - schema: - items: - $ref: "#/components/schemas/AFile" - type: array - text/tab-separated-values: - schema: - items: - $ref: "#/components/schemas/AFile" - type: array - description: The request was successful. The returned value is a list of objects. - "400": - content: { } - description: Invalid data in the request. See the error message for details. - "401": - content: { } - description: |- - User is not authenticated. Please supply a valid Access Token in the `Authorization` HTTP header (e.g. Authorization: bearer [token]) - or Genestack API token in the `Genestack-API-Token` header (this token may be obtained from the Genestack UI _Profile_ page). - "404": - content: { } - description: Object with provided accession could not be found in ODM. - "500": - content: { } - description: "An internal server error occurred. This indicates an unexpected\ - \ failure in the Genestack system, please file a bug report to support@genestack.com,\ - \ including the error details." - security: - - Access-token: [ ] - - Genestack-API-Token: [ ] - summary: Retrieve file's metadata by study ID - tags: - - Files integration as User -components: - schemas: - BatchOfIds: - $ref: "./schemas/integration/BatchOfIds.yaml" - DataItem: - $ref: "./schemas/integration/DataItem.yaml" - DataPresentation: - $ref: "./schemas/integration/DataPresentation.yaml" - IMetadata: - $ref: "./schemas/integration/IMetadata.yaml" - IntegrationHelper: - $ref: "./schemas/common/IntegrationHelper.yaml" - Library: - $ref: "./schemas/library/Library.yaml" - ListResponse: - $ref: "./schemas/common/ListResponse.yaml" - MetaResponse: - $ref: "./schemas/common/MetaResponse.yaml" - MetadataContent: - $ref: "./schemas/common/MetadataContent.yaml" - MetadataPresentation: - $ref: "./schemas/integration/MetadataPresentation.yaml" - MetadataWithId: - $ref: "./schemas/common/MetadataWithId.yaml" - OmicsResponse: - $ref: "./schemas/integration/OmicsResponse.yaml" - OmicsResponseDataPresentation: - $ref: "./schemas/integration/OmicsResponseDataPresentation.yaml" - OmicsResponseMetadataPresentation: - $ref: "./schemas/integration/OmicsResponseMetadataPresentation.yaml" - OmicsResponseMetadataWithId: - $ref: "./schemas/integration/OmicsResponseMetadataWithId.yaml" - PaginationInfo: - $ref: "./schemas/common/PaginationInfo.yaml" - Preparation: - $ref: "./schemas/preparation/Preparation.yaml" - Relationships: - $ref: "./schemas/integration/Relationships.yaml" - SourceTypePair: - $ref: "./schemas/integration/SourceTypePair.yaml" - StreamingOutput: - $ref: "./schemas/integration/StreamingOutput.yaml" - Study: - $ref: "./schemas/study/Study.yaml" - SearchStudyRequest: - $ref: "./schemas/integration/SearchStudyRequest.yaml" - AppliedFilter: - $ref: "./schemas/integration/AppliedFilter.yaml" - PageRequest: - $ref: "./schemas/integration/PageRequest.yaml" - FindObjectsResponse: - $ref: "./schemas/integration/FindObjectsResponse.yaml" - ObjectsPage: - $ref: "./schemas/integration/ObjectsPage.yaml" - ResponseFormat: - $ref: "./schemas/common/ResponseFormat.yaml" - StudySearchInfo: - $ref: "./schemas/integration/StudySearchInfo.yaml" - MetainfoKeyForSummary: - $ref: "./schemas/integration/MetainfoKeyForSummary.yaml" - FilterOptionGroup: - $ref: "./schemas/integration/FilterOptionGroup.yaml" - FilterOption: - $ref: "./schemas/integration/FilterOption.yaml" - AFile: - $ref: "./schemas/afile/AFile.yaml" - DERequest: - $ref: "./schemas/cell/DERequest.yaml" - DEResponse: - $ref: "./schemas/cell/DEResponse.yaml" - GSRequest: - $ref: "./schemas/cell/GSRequest.yaml" - GSResponse: - $ref: "./schemas/cell/GSResponse.yaml" - CRRequest: - $ref: "./schemas/cell/CRRequest.yaml" - CRResponse: - $ref: "./schemas/cell/CRResponse.yaml" - securitySchemes: - Access-token: - in: header - name: Authorization - type: apiKey - Genestack-API-Token: - in: header - name: Genestack-API-Token - type: apiKey diff --git a/openapi/v1/integration{Role}.yaml b/openapi/v1/integration{Role}.yaml index a9bfab1d..8bd78d36 100644 --- a/openapi/v1/integration{Role}.yaml +++ b/openapi/v1/integration{Role}.yaml @@ -1,7 +1,7 @@ openapi: 3.1.0 info: description: |- - ##{Role=Curator} + ##{Role=User} This swagger page describes the integrationUser APIs for ODM. These are typically used to find and retrieve study, sample and processed (signal) data and metadata for a given query. ## end {Role=User} Before carrying out any API calls you will need an API token. API tokens can be obtained under your profile within the Genestack software. @@ -27,8 +27,8 @@ tags: - name: Omics queries as {Role} - name: Preparation integration as {Role} - name: Sample integration as {Role} -- name: Study integration as {Role} #{Role=Curator} -- name: Validation summary as Curator +- name: Study integration as {Role} +- name: Validation summary as Curator #{Role=Curator} - name: Variant integration as {Role} paths: /api/v1/as-{role}/data-types: @@ -225,7 +225,7 @@ paths: ## Paging For performance reasons this endpoint returns results in "pages" of limited size. In order to retrieve all matching results the client needs to request multiple pages starting from an offset to the first result. You can do this using the pageOffset query parameter. A value of 0 (the default) instructs the server to return the first page of results, 100 would return a page of results starting from the 101st result and so on. To retrieve all results, iterate through pages using `pageOffset` values of `n * pageLimit` until a page returns fewer results than the page limit, which indicates there are no more results. - operationId: getExpressionByPreparation + operationId: getExpressionByPreparationAs{Role} parameters: - description: Supply this parameter with the value `term_id` as part of the query to return extended information including IDs for values and dictionaries. @@ -306,7 +306,7 @@ paths: summary: Retrieve expression run-level data by querying related preparation ID (accession) tags: - - Expression integration as {role} + - Expression integration as {Role} /api/v1/as-{role}/integration/link/expression/by/sample/{id}: get: description: |+ @@ -1815,7 +1815,7 @@ paths: - Library integration as {Role} /api/v1/as-{role}/integration/link/library/by/sample/{id}: get: - operationId: getLibraryBySampleAsCurator + operationId: getLibraryBySampleAs{Role} parameters: - description: Supply this parameter with the value `term_id` as part of the query to return extended information including IDs for values and dictionaries. @@ -4264,7 +4264,9 @@ paths: tags: - Study integration as Curator x-codegen-request-body-name: request +## end {Role=Curator} /api/v1/as-curator/links: +## {Role=Curator} delete: description: "This method should be used in case you want to delete the links\ \ of an object. Please, keep in mind that deleting a link between Study and\ @@ -5453,7 +5455,7 @@ paths: \ )` can be used for complex expressions.\n \n\n## Error Handling\n In case\ \ of unexpected internal error during data retrieval, the last line of the\ \ body will contain an error message, prefixed by the `#` character \n\n" - ##{Role=User} + ## end {Role=User} ##{Role=Curator} Stream data from a given group for a tabular file that matches a sample/library/preparations query/filter. If no query/filters are supplied all expression data is returned. If a metadata filter is specified, this endpoint will only return expression data that is associated with a sample via the Sample Source ID attribute. ## Conditions From df4eb7160708665a6100f5153c1fa5d5c5c26eb1 Mon Sep 17 00:00:00 2001 From: oleg parkhomenko Date: Sat, 15 Nov 2025 00:09:39 +0400 Subject: [PATCH 3/9] flow cytometry template --- build.gradle.kts | 8 +- openapi/v1/flowCytometryUser.yaml | 688 ------------------ ...yCurator.yaml => flowCytometry{Role}.yaml} | 60 +- 3 files changed, 36 insertions(+), 720 deletions(-) delete mode 100644 openapi/v1/flowCytometryUser.yaml rename openapi/v1/{flowCytometryCurator.yaml => flowCytometry{Role}.yaml} (95%) diff --git a/build.gradle.kts b/build.gradle.kts index dbee1d20..a78bc486 100644 --- a/build.gradle.kts +++ b/build.gradle.kts @@ -29,10 +29,10 @@ val mergedFileName = "odmApi.yaml" val mergedFilePath = "${sourceDirectory}/${mergedFileName}" fun specFiles(selectTemplates: Boolean = false) = KotlinPath(sourceDirectory) - .listDirectoryEntries("*.yaml") - .filter { (!selectTemplates).xor(it.name.contains("{Role}")) } - .sorted() - .map { layout.projectDirectory.file("${sourceDirectory}/${it.name}") } + .listDirectoryEntries("*.yaml") + .filter { (!selectTemplates).xor(it.name.contains("{Role}")) } + .sorted() + .map { layout.projectDirectory.file("${sourceDirectory}/${it.name}") } tasks { val templateSpecs by registering(TemplateSpecification::class) { diff --git a/openapi/v1/flowCytometryUser.yaml b/openapi/v1/flowCytometryUser.yaml deleted file mode 100644 index 20ec634d..00000000 --- a/openapi/v1/flowCytometryUser.yaml +++ /dev/null @@ -1,688 +0,0 @@ -openapi: 3.1.0 -info: - description: |- - This swagger page describes the flowCytometryUser API endpoints for ODM. These are typically used to find and retrieve flow cytometry data and metadata. - The APIs can be used for gated flow cytometry data in FACS format. For flow cytometry data in FCS format use expression endpoints. - - Before carrying out any API calls you will need an API token. API tokens can be obtained under your profile within the Genestack software. - - To try out calls in this swagger page: - - 1. Click the 'Authorize' button below to enter your API token - 2. Scroll to the 'Parameters' section for the method you wish to try out and click the 'Try it out' button - 3. Enter parameter values that you wish to try - 4. Scroll to the bottom of the Parameters section and click the 'Execute' bar that appears - - The server response will be in the section that follows. - title: ODM API - version: default-released -tags: -- name: Flow Cytometry SPoT as User -paths: - /api/v1/as-user/flow-cytometries: - get: - description: |+ - Retrieve all flow cytometry data and metadata objects that match a query. - - ## Metadata full-text queries - Single words can be supplied as is, otherwise use speech marks (`"`) to quote queries that include whitespace. Speech marks and backslash characters in the query need to be escaped with a backslash (`\`). - - ## Metadata filters - Metadata filters are key-value pairs joined by an operator. The `=` operator matches literal values/string. The `!=` operator matches anything except the literal value/string. The `<` or `>` operators match numerical results that are less or greater than the supplied value. Strings containing whitespace need to be quoted with (`"`). - - ## Combinations - Metadata queries/filters for the same parameter can be combined with `&&`, `AND`, `||` and `OR` operators, using white-space to separate out the terms and operators. Parentheses `( )` can be used for complex expressions. - - ## Versioning - Specific versions of omics data files (eg. GCT) can be queried via the useVersions parameter. Different versions of an omics data file are associated via their CHAIN_ID metadata value. This CHAIN_ID can be supplied to the useVersions parameter along with the version number or specific omics data file accessions to include them in the query. If nothing is supplied to the useVersions parameter then only the active version (which is usually the last one imported) is queried. This acts as a filter before the rest of the query is carried out. - - Example usage: - useVersions=* (query all versions, including those without CHAIN_IDs) - useVersions=v2 (query the second version. If there is no second version then the data file is not queried) - useVersions=v1,v0 (query the first version and any data files without CHAIN_IDs(v0) ) - useVersions=GSVC002:v3 (for omics data files with a CHAIN_ID of GSCV002 query the third version) - useVersions=GSVC002:GSF00494,GSF000496 (for omics data files with a CHAIN_ID of GSCV002 query only the specific accessions GSF00494 and GSF000496) - - Rules for multiple CHAIN_IDs can be supplied to the parameter using the ; separator. - - ## Paging - For performance reasons this endpoint returns results in "pages" of limited size together with a `cursor` tag. To retrieve the next page of results please supply this `cursor` tag to resume the query from your previous result and get the next page. If there are no more results you will just retrieve an empty result. - - operationId: getFlowCytometryDataAsUser - parameters: - - description: Supply this parameter with the value `term_id` as part of the - query to return extended information including IDs for values and dictionaries. - in: query - name: responseFormat - schema: - $ref: "#/components/schemas/ResponseFormat" - - description: Filter by flow cytometry metadata (key-value metadata pair(s)). - E.g. `Organ=blood`. - in: query - name: filter - schema: - type: string - - description: Search for flow cytometry objects via a full text query over - all flow cytometry metadata. Queries matching dictionary terms are automatically - expanded to include synonyms. - in: query - name: query - schema: - type: string - - description: |- - If the full-text query term is present in an ODM dictionary, enabling this parameter will modify the query to include child terms of the full-text query. - - For example, the search query "Body fluid" can be expanded to include the term "Blood" (a child term of "Body fluid") so files containing either "Body fluid" or "Blood" in their metadata will be returned in the search results. - - The parent-child relationship is defined by the key "broaders" or "subClassOf" in the dictionary. - - If the full query term is not present in a dictionary then this parameter has no effect. - in: query - name: searchSpecificTerms - schema: - type: boolean - - description: Autogenerated numeric ID that identifies a set of rows related to one run and is used to link - data from the run to a sample. Multiple values can be provided as a list. - in: query - name: runFilter - schema: - $ref: "#/components/schemas/RunFilter" - style: form - - description: Sample name from the file which allows retrieval of all the rows related to the sample. Multiple values can be provided as a list. - explode: true - in: query - name: runSourceFilter - schema: - items: - type: string - example: Run Source ID - type: array - style: form - - description: "Required value of \"Readout type\" column. E.g.: `Count`, `Median`" - in: query - name: readoutType - schema: - type: string - - description: |- - Value of "Cell Population" column. E.g.: `"total cells"`, `CD45+,live/CD45+`, `CD3+`. - - Note that if this value contains special characters like `/` which is used as a URI path separator, such characters should be escaped manually before sending request. For example, `/` should be escaped as `%2F`. - in: query - name: population - schema: - type: string - - description: "Marker value. E.g.: `PD1`, `BV786`" - in: query - name: marker - schema: - type: string - - description: Minimum threshold (inclusive) for returned expression values. - in: query - name: minValue - schema: - type: number - - description: |- - Specify which versions of omics data files are used in the query. By default the active version is used. See Versioning above. Syntax: - - \* or `v` or ``:`v` or ``:`` - in: query - name: useVersions - schema: - type: string - - description: |- - The parameter defines amount of metadata attributes to return: - - 1. `minimal_data` - return metadata attributes according to the default template. - 2. `extended_data_included` - return metadata attributes according to applied template, if object doesn’t have applied template, default template will be used. This is the default for User endpoints. - 3. `original_data_included` - return all metadata attributes with values and null attributes, if they are present in the applied template. This is the default for Curator endpoints. - in: query - name: returnedMetadataFields - schema: - enum: - - minimal_data - - extended_data_included - - original_data_included - type: string - - description: Maximum number of results to return per page (see Paging above). - This value must be between 0 and 2000 (inclusive). The default is 2000. - in: query - name: pageLimit - schema: - format: int32 - type: integer - - description: The page tag to resume results from (see paging above). - in: query - name: cursor - schema: - type: string - responses: - "200": - content: - application/json: - schema: - $ref: "#/components/schemas/FlowCytometryResponse" - description: Retrieved Flow Cytometry data. - "400": - content: {} - description: Flow Cytometry data cannot be retrieved. - "401": - content: {} - description: |- - User is not authenticated. Please supply a valid Access Token in the `Authorization` HTTP header (e.g. Authorization: bearer [token]) - or Genestack API token in the `Genestack-API-Token` header (this token may be obtained from the Genestack UI _Profile_ page). - "404": - content: {} - description: No object exists with the given ID. - "500": - content: {} - description: "An internal server error occurred. This indicates an unexpected\ - \ failure in the Genestack system, please file a bug report to support@genestack.com,\ - \ including the error details." - security: - - Access-token: [] - - Genestack-API-Token: [] - summary: Retrieve multiple flow cytometry data and metadata objects - tags: - - Flow Cytometry SPoT as User - /api/v1/as-user/flow-cytometries/group: - get: - description: |- - Retrieve all group metadata objects that match a query. - - ## Metadata full-text queries - Single words can be supplied as is, otherwise use speech marks (`"`) to quote queries that include whitespace. Speech marks and backslash characters in the query need to be escaped with a backslash (`\`). - - ## Metadata filters - Metadata filters are key-value pairs joined by an operator. The `=` operator matches literal values/string. The `!=` operator matches anything except the literal value/string. The `<` or `>` operators match numerical results that are less or greater than the supplied value. Strings containing whitespace need to be quoted with (`"`). - - ## Combinations - Metadata queries/filters for the same parameter can be combined with `&&`, `AND`, `||` and `OR` operators, using white-space to separate out the terms and operators. Parentheses `( )` can be used for complex expressions. - - ## Versioning - Specific versions of omics data files (eg. GCT) can be queried via the useVersions parameter. Different versions of an omics data file are associated via their CHAIN_ID metadata value. This CHAIN_ID can be supplied to the useVersions parameter along with the version number or specific omics data file accessions to include them in the query. If nothing is supplied to the useVersions parameter then only the active version (which is usually the last one imported) is queried. This acts as a filter before the rest of the query is carried out. - - Example usage: - useVersions=* (query all versions, including those without CHAIN_IDs) - useVersions=v2 (query the second version. If there is no second version then the data file is not queried) - useVersions=v1,v0 (query the first version and any data files without CHAIN_IDs(v0) ) - useVersions=GSVC002:v3 (for omics data files with a CHAIN_ID of GSCV002 query the third version) - useVersions=GSVC002:GSF00494,GSF000496 (for omics data files with a CHAIN_ID of GSCV002 query only the specific accessions GSF00494 and GSF000496) - - Rules for multiple CHAIN_IDs can be supplied to the parameter using the ; separator. - - ## Paging - For performance reasons this endpoint returns results in "pages" of limited size. In order to retrieve all matching results the client needs to request multiple pages starting from an offset to the first result. You can do this using the pageOffset query parameter. A value of 0 (the default) instructs the server to return the first page of results, 100 would return a page of results starting from the 101st result and so on. To retrieve all results, iterate through pages using `pageOffset` values of `n * pageLimit` until a page returns fewer results than the page limit, which indicates there are no more results. - - ## List operation - - This endpoint can be called with no `query` parameter. Doing so returns a list of all data objects. - operationId: searchFlowCytometryGroupsAsUser - parameters: - - description: Supply this parameter with the value `term_id` as part of the - query to return extended information including IDs for values and dictionaries. - in: query - name: responseFormat - schema: - $ref: "#/components/schemas/ResponseFormat" - - description: Filter by flow cytometry metadata (key-value metadata pair(s)). - E.g. `Organ=blood`. - in: query - name: filter - schema: - type: string - - description: Search for flow cytometry objects via a full text query over - all flow cytometry metadata. Queries matching dictionary terms are automatically - expanded to include synonyms. - in: query - name: query - schema: - type: string - - description: |- - If the full-text query term is present in an ODM dictionary, enabling this parameter will modify the query to include child terms of the full-text query. - - For example, the search query "Body fluid" can be expanded to include the term "Blood" (a child term of "Body fluid") so files containing either "Body fluid" or "Blood" in their metadata will be returned in the search results. - - The parent-child relationship is defined by the key "broaders" or "subClassOf" in the dictionary. - - If the full query term is not present in a dictionary then this parameter has no effect. - in: query - name: searchSpecificTerms - schema: - type: boolean - - description: |- - Specify which versions of omics data files are used in the query. By default the active version is used. See Versioning above. Syntax: - - \* or `v` or ``:`v` or ``:`` - in: query - name: useVersions - schema: - type: string - - description: |- - The parameter defines amount of metadata attributes to return: - - 1. `minimal_data` - return metadata attributes according to the default template. - 2. `extended_data_included` - return metadata attributes according to applied template, if object doesn’t have applied template, default template will be used. This is the default for User endpoints. - 3. `original_data_included` - return all metadata attributes with values and null attributes, if they are present in the applied template. This is the default for Curator endpoints. - in: query - name: returnedMetadataFields - schema: - enum: - - minimal_data - - extended_data_included - - original_data_included - type: string - - description: "Show the page {pageOffset+1} results from the start of the results.\ - \ E.g. 100 will show a page of results starting from the 101st result.\ - \ The default value is 0." - in: query - name: pageOffset - schema: - format: int32 - type: integer - - description: Maximum number of results to return per page (see Paging above). - This value must be between 0 and 2000 (inclusive). The default is 2000. - in: query - name: pageLimit - schema: - format: int32 - type: integer - responses: - "200": - content: - application/json: - schema: - $ref: "#/components/schemas/ListResponse" - description: The request was successful. The returned value is a list of - objects. - "400": - content: {} - description: The supplied object ID is invalid. - "401": - content: {} - description: |- - User is not authenticated. Please supply a valid Access Token in the `Authorization` HTTP header (e.g. Authorization: bearer [token]) - or Genestack API token in the `Genestack-API-Token` header (this token may be obtained from the Genestack UI _Profile_ page). - "404": - content: {} - description: No object exists with the given ID. - "500": - content: {} - description: "An internal server error occurred. This indicates an unexpected\ - \ failure in the Genestack system, please file a bug report to support@genestack.com,\ - \ including the error details." - security: - - Access-token: [] - - Genestack-API-Token: [] - summary: Retrieve groups that match a query - tags: - - Flow Cytometry SPoT as User - /api/v1/as-user/flow-cytometries/group/by/run/{id}: - get: - operationId: getFlowCytometryGroupByRunAsUser - parameters: - - description: Supply this parameter with the value `term_id` as part of the - query to return extended information including IDs for values and dictionaries. - in: query - name: responseFormat - schema: - $ref: "#/components/schemas/ResponseFormat" - - description: Unique identifier (accession) of the object. - in: path - name: id - required: true - schema: - type: string - - description: |- - The parameter defines amount of metadata attributes to return: - - 1. `minimal_data` - return metadata attributes according to the default template. - 2. `extended_data_included` - return metadata attributes according to applied template, if object doesn’t have applied template, default template will be used. This is the default for User endpoints. - 3. `original_data_included` - return all metadata attributes with values and null attributes, if they are present in the applied template. This is the default for Curator endpoints. - in: query - name: returnedMetadataFields - schema: - enum: - - minimal_data - - extended_data_included - - original_data_included - type: string - responses: - "200": - content: - application/json: - schema: - $ref: "#/components/schemas/MetadataWithId" - description: The request was successful. The returned value is the object. - "400": - content: {} - description: The supplied object ID is invalid. - "401": - content: {} - description: |- - User is not authenticated. Please supply a valid Access Token in the `Authorization` HTTP header (e.g. Authorization: bearer [token]) - or Genestack API token in the `Genestack-API-Token` header (this token may be obtained from the Genestack UI _Profile_ page). - "404": - content: {} - description: No object exists with the given ID. - "500": - content: {} - description: "An internal server error occurred. This indicates an unexpected\ - \ failure in the Genestack system, please file a bug report to support@genestack.com,\ - \ including the error details." - security: - - Access-token: [] - - Genestack-API-Token: [] - summary: Retrieve a single group object by run ID (accession) - tags: - - Flow Cytometry SPoT as User - /api/v1/as-user/flow-cytometries/group/{id}: - get: - operationId: getFlowCytometryGroupAsUser - parameters: - - description: Supply this parameter with the value `term_id` as part of the - query to return extended information including IDs for values and dictionaries. - in: query - name: responseFormat - schema: - $ref: "#/components/schemas/ResponseFormat" - - description: Unique identifier (accession) of the object. - in: path - name: id - required: true - schema: - type: string - - description: |- - The parameter defines amount of metadata attributes to return: - - 1. `minimal_data` - return metadata attributes according to the default template. - 2. `extended_data_included` - return metadata attributes according to applied template, if object doesn’t have applied template, default template will be used. This is the default for User endpoints. - 3. `original_data_included` - return all metadata attributes with values and null attributes, if they are present in the applied template. This is the default for Curator endpoints. - in: query - name: returnedMetadataFields - schema: - enum: - - minimal_data - - extended_data_included - - original_data_included - type: string - responses: - "200": - content: - application/json: - schema: - $ref: "#/components/schemas/MetadataWithId" - description: The request was successful. The returned value is the object. - "400": - content: {} - description: The supplied object ID is invalid. - "401": - content: {} - description: |- - User is not authenticated. Please supply a valid Access Token in the `Authorization` HTTP header (e.g. Authorization: bearer [token]) - or Genestack API token in the `Genestack-API-Token` header (this token may be obtained from the Genestack UI _Profile_ page). - "404": - content: {} - description: No object exists with the given ID. - "500": - content: {} - description: "An internal server error occurred. This indicates an unexpected\ - \ failure in the Genestack system, please file a bug report to support@genestack.com,\ - \ including the error details." - security: - - Access-token: [] - - Genestack-API-Token: [] - summary: Retrieve a single group object by ID (accession) - tags: - - Flow Cytometry SPoT as User - /api/v1/as-user/flow-cytometries/runs/by/group/{id}: - get: - description: |+ - ## Paging - For performance reasons this endpoint returns results in "pages" of limited size together with a `cursor` tag. To retrieve the next page of results please supply this `cursor` tag to resume the query from your previous result and get the next page. If there are no more results you will just retrieve an empty result. - - operationId: searchFlowCytometryRunsAsUser - parameters: - - description: Unique identifier (accession) of the object. - in: path - name: id - required: true - schema: - type: string - - description: The page tag to resume results from (see paging above). - in: query - name: cursor - schema: - type: string - - description: Maximum number of results to return per page (see Paging above). - This value must be between 0 and 2000 (inclusive). The default is 2000. - in: query - name: pageLimit - schema: - format: int32 - type: integer - responses: - "200": - content: - application/json: - schema: - $ref: "#/components/schemas/RunsResponse" - description: The request was successful. The returned value is the object. - "400": - content: {} - description: The supplied object ID is invalid. - "401": - content: {} - description: |- - User is not authenticated. Please supply a valid Access Token in the `Authorization` HTTP header (e.g. Authorization: bearer [token]) - or Genestack API token in the `Genestack-API-Token` header (this token may be obtained from the Genestack UI _Profile_ page). - "404": - content: {} - description: No object exists with the given ID. - "500": - content: {} - description: "An internal server error occurred. This indicates an unexpected\ - \ failure in the Genestack system, please file a bug report to support@genestack.com,\ - \ including the error details." - security: - - Access-token: [] - - Genestack-API-Token: [] - summary: Retrieve run objects related to the given group - tags: - - Flow Cytometry SPoT as User - /api/v1/as-user/flow-cytometries/{id}: - get: - operationId: getFlowCytometryAsUser - parameters: - - description: Supply this parameter with the value `term_id` as part of the - query to return extended information including IDs for values and dictionaries. - in: query - name: responseFormat - schema: - $ref: "#/components/schemas/ResponseFormat" - - description: Unique identifier (accession) of the object. - in: path - name: id - required: true - schema: - type: string - - description: |- - The parameter defines amount of metadata attributes to return: - - 1. `minimal_data` - return metadata attributes according to the default template. - 2. `extended_data_included` - return metadata attributes according to applied template, if object doesn’t have applied template, default template will be used. This is the default for User endpoints. - 3. `original_data_included` - return all metadata attributes with values and null attributes, if they are present in the applied template. This is the default for Curator endpoints. - in: query - name: returnedMetadataFields - schema: - enum: - - minimal_data - - extended_data_included - - original_data_included - type: string - responses: - "200": - content: - application/json: - schema: - $ref: "#/components/schemas/FlowCytometryItem" - description: The request was successful. The returned value is the object. - "400": - content: {} - description: The supplied object ID is invalid. - "401": - content: {} - description: |- - User is not authenticated. Please supply a valid Access Token in the `Authorization` HTTP header (e.g. Authorization: bearer [token]) - or Genestack API token in the `Genestack-API-Token` header (this token may be obtained from the Genestack UI _Profile_ page). - "404": - content: {} - description: No object exists with the given ID. - "500": - content: {} - description: "An internal server error occurred. This indicates an unexpected\ - \ failure in the Genestack system, please file a bug report to support@genestack.com,\ - \ including the error details." - security: - - Access-token: [] - - Genestack-API-Token: [] - summary: Retrieve a single sample flow cytometry by ID (accession) - tags: - - Flow Cytometry SPoT as User - /api/v1/as-user/flow-cytometries/{id}/versions: - get: - operationId: getFlowCytometryVersionsAsUser - parameters: - - description: Unique identifier (accession) of the object. - in: path - name: id - required: true - schema: - type: string - responses: - "200": - content: - application/json: - schema: - items: - $ref: "#/components/schemas/CommitInfo" - type: array - description: The request was successful. The returned value is the list - of object versions. - "401": - content: {} - description: |- - User is not authenticated. Please supply a valid Access Token in the `Authorization` HTTP header (e.g. Authorization: bearer [token]) - or Genestack API token in the `Genestack-API-Token` header (this token may be obtained from the Genestack UI _Profile_ page). - "500": - content: {} - description: "An internal server error occurred. This indicates an unexpected\ - \ failure in the Genestack system, please file a bug report to support@genestack.com,\ - \ including the error details." - security: - - Access-token: [] - - Genestack-API-Token: [] - summary: Retrieve a list of object versions by ID - tags: - - Flow Cytometry SPoT as User - /api/v1/as-user/flow-cytometries/{id}/versions/{version}: - get: - operationId: getFlowCytometryByVersionAsUser - parameters: - - description: Supply this parameter with the value `term_id` as part of the - query to return extended information including IDs for values and dictionaries. - in: query - name: responseFormat - schema: - $ref: "#/components/schemas/ResponseFormat" - - description: Unique identifier (accession) of the object. - in: path - name: id - required: true - schema: - type: string - - description: Unique version of the object. - in: path - name: version - required: true - schema: - type: string - - description: |- - The parameter defines amount of metadata attributes to return: - - 1. `minimal_data` - return metadata attributes according to the default template. - 2. `extended_data_included` - return metadata attributes according to applied template, if object doesn’t have applied template, default template will be used. This is the default for User endpoints. - 3. `original_data_included` - return all metadata attributes with values and null attributes, if they are present in the applied template. This is the default for Curator endpoints. - in: query - name: returnedMetadataFields - schema: - enum: - - minimal_data - - extended_data_included - - original_data_included - type: string - responses: - "200": - content: - application/json: - schema: - $ref: "#/components/schemas/SignalRun" - description: The request was successful. The returned value is the object. - "400": - content: {} - description: The supplied object ID is invalid. - "401": - content: {} - description: |- - User is not authenticated. Please supply a valid Access Token in the `Authorization` HTTP header (e.g. Authorization: bearer [token]) - or Genestack API token in the `Genestack-API-Token` header (this token may be obtained from the Genestack UI _Profile_ page). - "404": - content: {} - description: No object exists with the given ID. - "500": - content: {} - description: "An internal server error occurred. This indicates an unexpected\ - \ failure in the Genestack system, please file a bug report to support@genestack.com,\ - \ including the error details." - security: - - Access-token: [] - - Genestack-API-Token: [] - summary: Retrieve a single sample flow cytometry by ID (accession) - tags: - - Flow Cytometry SPoT as User -components: - schemas: - CommitInfo: - $ref: "./schemas/common/CommitInfo.yaml" - FlowCytometryItem: - $ref: "./schemas/flow-cytometry/FlowCytometryItem.yaml" - FlowCytometryResponse: - $ref: "./schemas/flow-cytometry/FlowCytometryResponse.yaml" - IntegrationHelper: - $ref: "./schemas/common/IntegrationHelper.yaml" - ListResponse: - $ref: "./schemas/common/ListResponse.yaml" - MetaResponse: - $ref: "./schemas/common/MetaResponse.yaml" - MetadataContent: - $ref: "./schemas/common/MetadataContent.yaml" - MetadataWithId: - $ref: "./schemas/common/MetadataWithId.yaml" - PaginationInfo: - $ref: "./schemas/common/PaginationInfo.yaml" - ResponseFormat: - $ref: "./schemas/common/ResponseFormat.yaml" - RunFilter: - $ref: "./schemas/common/RunFilter.yaml" - RunsResponse: - $ref: "./schemas/common/RunsResponse.yaml" - SignalRun: - $ref: "./schemas/common/SignalRun.yaml" - securitySchemes: - Access-token: - in: header - name: Authorization - type: apiKey - Genestack-API-Token: - in: header - name: Genestack-API-Token - type: apiKey diff --git a/openapi/v1/flowCytometryCurator.yaml b/openapi/v1/flowCytometry{Role}.yaml similarity index 95% rename from openapi/v1/flowCytometryCurator.yaml rename to openapi/v1/flowCytometry{Role}.yaml index 813788db..08492952 100644 --- a/openapi/v1/flowCytometryCurator.yaml +++ b/openapi/v1/flowCytometry{Role}.yaml @@ -1,7 +1,9 @@ openapi: 3.1.0 info: description: |- - This swagger page describes the flowCytometryCurator API endpoints for ODM. These are typically used to find and retrieve flow cytometry data and metadata as well as update metadata. + This swagger page describes the flowCytometry{Role} API endpoints for ODM. + These are typically used to find and retrieve flow cytometry data and metadata. #{Role=User} + These are typically used to find and retrieve flow cytometry data and metadata as well as update metadata. #{Role=Curator} The APIs can be used for gated flow cytometry data in FACS format. For flow cytometry data in FCS format use expression endpoints. Before carrying out any API calls you will need an API token. API tokens can be obtained under your profile within the Genestack software. @@ -17,9 +19,9 @@ info: title: ODM API version: default-released tags: -- name: Flow Cytometry SPoT as Curator +- name: Flow Cytometry SPoT as {Role} paths: - /api/v1/as-curator/flow-cytometries: + /api/v1/as-{role}/flow-cytometries: get: description: |+ Retrieve all flow cytometry data and metadata objects that match a query. @@ -48,7 +50,7 @@ paths: ## Paging For performance reasons this endpoint returns results in "pages" of limited size together with a `cursor` tag. To retrieve the next page of results please supply this `cursor` tag to resume the query from your previous result and get the next page. If there are no more results you will just retrieve an empty result. - operationId: getFlowCytometryDataAsCurator + operationId: getFlowCytometryDataAs{Role} parameters: - description: Supply this parameter with the value `term_id` as part of the query to return extended information including IDs for values and dictionaries. @@ -183,8 +185,8 @@ paths: - Genestack-API-Token: [] summary: Retrieve multiple flow cytometry data and metadata objects tags: - - Flow Cytometry SPoT as Curator - /api/v1/as-curator/flow-cytometries/group: + - Flow Cytometry SPoT as {Role} + /api/v1/as-{role}/flow-cytometries/group: get: description: |- Retrieve all group metadata objects that match a query. @@ -216,7 +218,7 @@ paths: ## List operation This endpoint can be called with no `query` parameter. Doing so returns a list of all data objects. - operationId: searchFlowCytometryGroupsAsCurator + operationId: searchFlowCytometryGroupsAs{Role} parameters: - description: Supply this parameter with the value `term_id` as part of the query to return extended information including IDs for values and dictionaries. @@ -315,10 +317,10 @@ paths: - Genestack-API-Token: [] summary: Retrieve groups that match a query tags: - - Flow Cytometry SPoT as Curator - /api/v1/as-curator/flow-cytometries/group/by/run/{id}: + - Flow Cytometry SPoT as {Role} + /api/v1/as-{role}/flow-cytometries/group/by/run/{id}: get: - operationId: getFlowCytometryGroupByRunAsCurator + operationId: getFlowCytometryGroupByRunAs{Role} parameters: - description: Supply this parameter with the value `term_id` as part of the query to return extended information including IDs for values and dictionaries. @@ -374,10 +376,10 @@ paths: - Genestack-API-Token: [] summary: Retrieve a single group object by run ID (accession) tags: - - Flow Cytometry SPoT as Curator - /api/v1/as-curator/flow-cytometries/group/{id}: + - Flow Cytometry SPoT as {Role} + /api/v1/as-{role}/flow-cytometries/group/{id}: get: - operationId: getFlowCytometryGroupAsCurator + operationId: getFlowCytometryGroupAs{Role} parameters: - description: Supply this parameter with the value `term_id` as part of the query to return extended information including IDs for values and dictionaries. @@ -433,14 +435,14 @@ paths: - Genestack-API-Token: [] summary: Retrieve a single group object by ID (accession) tags: - - Flow Cytometry SPoT as Curator - /api/v1/as-curator/flow-cytometries/runs/by/group/{id}: + - Flow Cytometry SPoT as {Role} + /api/v1/as-{role}/flow-cytometries/runs/by/group/{id}: get: description: |+ ## Paging For performance reasons this endpoint returns results in "pages" of limited size together with a `cursor` tag. To retrieve the next page of results please supply this `cursor` tag to resume the query from your previous result and get the next page. If there are no more results you will just retrieve an empty result. - operationId: searchFlowCytometryRunsAsCurator + operationId: searchFlowCytometryRunsAs{Role} parameters: - description: Unique identifier (accession) of the object. in: path @@ -488,10 +490,10 @@ paths: - Genestack-API-Token: [] summary: Retrieve run objects related to the given group tags: - - Flow Cytometry SPoT as Curator - /api/v1/as-curator/flow-cytometries/{id}: + - Flow Cytometry SPoT as {Role} + /api/v1/as-{role}/flow-cytometries/{id}: get: - operationId: getFlowCytometryAsCurator + operationId: getFlowCytometryAs{Role} parameters: - description: Supply this parameter with the value `term_id` as part of the query to return extended information including IDs for values and dictionaries. @@ -547,7 +549,8 @@ paths: - Genestack-API-Token: [] summary: Retrieve a single sample flow cytometry by ID (accession) tags: - - Flow Cytometry SPoT as Curator + - Flow Cytometry SPoT as {Role} +##{Role=Curator} patch: description: |- ## Basic operation @@ -558,7 +561,7 @@ paths: ## Attribute values The attribute values are intelligently parsed as booleans, integers, etc. - operationId: updateFlowCytometryAsCurator + operationId: updateFlowCytometryAs{Role} parameters: - description: Unique identifier (accession) of the object. in: path @@ -602,11 +605,12 @@ paths: - Genestack-API-Token: [] summary: Update object metadata tags: - - Flow Cytometry SPoT as Curator + - Flow Cytometry SPoT as {Role} x-codegen-request-body-name: body - /api/v1/as-curator/flow-cytometries/{id}/versions: +## end {Role=Curator} + /api/v1/as-{role}/flow-cytometries/{id}/versions: get: - operationId: getFlowCytometryVersionsAsCurator + operationId: getFlowCytometryVersionsAs{Role} parameters: - description: Unique identifier (accession) of the object. in: path @@ -639,10 +643,10 @@ paths: - Genestack-API-Token: [] summary: Retrieve a list of object versions by ID tags: - - Flow Cytometry SPoT as Curator - /api/v1/as-curator/flow-cytometries/{id}/versions/{version}: + - Flow Cytometry SPoT as {Role} + /api/v1/as-{role}/flow-cytometries/{id}/versions/{version}: get: - operationId: getFlowCytometryByVersionAsCurator + operationId: getFlowCytometryByVersionAs{Role} parameters: - description: Supply this parameter with the value `term_id` as part of the query to return extended information including IDs for values and dictionaries. @@ -704,7 +708,7 @@ paths: - Genestack-API-Token: [] summary: Retrieve a single sample flow cytometry by ID (accession) tags: - - Flow Cytometry SPoT as Curator + - Flow Cytometry SPoT as {Role} components: schemas: CommitInfo: From f8d7d7eaf297d33192122d3f73bf8d0f7eca9a88 Mon Sep 17 00:00:00 2001 From: oleg parkhomenko Date: Sat, 15 Nov 2025 00:29:32 +0400 Subject: [PATCH 4/9] template the rest --- openapi/v1/cellCurator.yaml | 120 --- openapi/v1/{cellUser.yaml => cell{Role}.yaml} | 14 +- openapi/v1/expressionUser.yaml | 682 ----------------- ...sionCurator.yaml => expression{Role}.yaml} | 54 +- openapi/v1/fileUser.yaml | 246 ------ .../v1/{fileCurator.yaml => file{Role}.yaml} | 25 +- openapi/v1/libraryUser.yaml | 413 ---------- ...libraryCurator.yaml => library{Role}.yaml} | 42 +- openapi/v1/preparationUser.yaml | 414 ---------- ...ionCurator.yaml => preparation{Role}.yaml} | 42 +- openapi/v1/sampleUser.yaml | 339 --------- .../{sampleCurator.yaml => sample{Role}.yaml} | 36 +- openapi/v1/studyUser.yaml | 340 --------- .../{studyCurator.yaml => study{Role}.yaml} | 36 +- openapi/v1/variantUser.yaml | 714 ------------------ ...variantCurator.yaml => variant{Role}.yaml} | 52 +- 16 files changed, 160 insertions(+), 3409 deletions(-) delete mode 100644 openapi/v1/cellCurator.yaml rename openapi/v1/{cellUser.yaml => cell{Role}.yaml} (94%) delete mode 100644 openapi/v1/expressionUser.yaml rename openapi/v1/{expressionCurator.yaml => expression{Role}.yaml} (96%) delete mode 100644 openapi/v1/fileUser.yaml rename openapi/v1/{fileCurator.yaml => file{Role}.yaml} (95%) delete mode 100644 openapi/v1/libraryUser.yaml rename openapi/v1/{libraryCurator.yaml => library{Role}.yaml} (95%) delete mode 100644 openapi/v1/preparationUser.yaml rename openapi/v1/{preparationCurator.yaml => preparation{Role}.yaml} (95%) delete mode 100644 openapi/v1/sampleUser.yaml rename openapi/v1/{sampleCurator.yaml => sample{Role}.yaml} (95%) delete mode 100644 openapi/v1/studyUser.yaml rename openapi/v1/{studyCurator.yaml => study{Role}.yaml} (95%) delete mode 100644 openapi/v1/variantUser.yaml rename openapi/v1/{variantCurator.yaml => variant{Role}.yaml} (96%) diff --git a/openapi/v1/cellCurator.yaml b/openapi/v1/cellCurator.yaml deleted file mode 100644 index 127461f5..00000000 --- a/openapi/v1/cellCurator.yaml +++ /dev/null @@ -1,120 +0,0 @@ -openapi: 3.1.0 -info: - description: |- - This swagger page describes the APIs for retrieving cells. - title: ODM API - version: default-released -tags: - - name: Cells as Curator -paths: - /api/v1/as-curator/cells/{id}: - get: - operationId: getCellByIdAsCurator - parameters: - - description: Unique cell identifier. Consists of a cell group accession and a cell barcode, separated by a hyphen, e.g. `GSF123456-AAACCTGAGCGCTCCA-1`. - in: path - name: id - required: true - schema: - type: string - responses: - "200": - content: - application/json: - schema: - $ref: "#/components/schemas/Cell" - description: The request was successful. The returned value is the object. - "400": - content: { } - description: Invalid data in the request. See the error message for details. - "401": - content: { } - description: |- - User is not authenticated. Please supply a valid Access Token in the `Authorization` HTTP header (e.g. Authorization: bearer [token]) - or Genestack API token in the `Genestack-API-Token` header (this token may be obtained from the Genestack UI _Profile_ page). - "404": - content: { } - description: Object with provided ID could not be found in ODM. - "500": - content: { } - description: "An internal server error occurred. This indicates an unexpected\ - \ failure in the Genestack system, please file a bug report to support@genestack.com,\ - \ including the error details." - security: - - Access-token: [ ] - - Genestack-API-Token: [ ] - summary: Retrieve a cell by ID - tags: - - Cells as Curator - /api/v1/as-curator/cells/by/group/{id}: - get: - description: |+ - ## Paging - For performance reasons this endpoint returns results in "pages" of limited size together with a `cursor` tag. - To retrieve the next page of results please supply this `cursor` tag to resume the query from your previous result and get the next page. - If there are no more results you will just retrieve an empty result. - operationId: getCellsByGroupAsCurator - parameters: - - description: Unique identifier (accession) of the cell group. - in: path - name: id - required: true - schema: - type: string - - description: Maximum number of results to return per page (see Paging above). - This value must be between 0 and 10000 (inclusive). The default is 2000. - in: query - name: pageLimit - schema: - format: int32 - type: integer - - description: The page tag to resume results from (see Paging above). Cell ID is currently used as a cursor. - in: query - name: cursor - schema: - type: string - responses: - "200": - content: - application/json: - schema: - $ref: "#/components/schemas/CellListResponse" - description: The request was successful. The returned value is a list of - objects. - "400": - content: { } - description: Cell data cannot be retrieved. - "401": - content: { } - description: |- - User is not authenticated. Please supply a valid Access Token in the `Authorization` HTTP header (e.g. Authorization: bearer [token]) - or Genestack API token in the `Genestack-API-Token` header (this token may be obtained from the Genestack UI _Profile_ page). - "404": - content: { } - description: No object exists with the given ID. - "500": - content: { } - description: "An internal server error occurred. This indicates an unexpected\ - \ failure in the Genestack system, please file a bug report to support@genestack.com,\ - \ including the error details." - security: - - Access-token: [ ] - - Genestack-API-Token: [ ] - summary: Retrieve cells from a given group - tags: - - Cells as Curator -components: - schemas: - Cell: - $ref: "./schemas/cell/Cell.yaml" - CellListResponse: - $ref: "./schemas/cell/CellListResponse.yaml" - securitySchemes: - Access-token: - in: header - name: Authorization - type: apiKey - Genestack-API-Token: - in: header - name: Genestack-API-Token - type: apiKey diff --git a/openapi/v1/cellUser.yaml b/openapi/v1/cell{Role}.yaml similarity index 94% rename from openapi/v1/cellUser.yaml rename to openapi/v1/cell{Role}.yaml index 9af2eb80..ea290efb 100644 --- a/openapi/v1/cellUser.yaml +++ b/openapi/v1/cell{Role}.yaml @@ -5,11 +5,11 @@ info: title: ODM API version: default-released tags: - - name: Cells as User + - name: Cells as {Role} paths: - /api/v1/as-user/cells/{id}: + /api/v1/as-{role}/cells/{id}: get: - operationId: getCellByIdAsUser + operationId: getCellByIdAs{Role} parameters: - description: Unique cell identifier. Consists of a cell group accession and a cell barcode, separated by a hyphen, e.g. `GSF123456-AAACCTGAGCGCTCCA-1`. in: path @@ -45,15 +45,15 @@ paths: - Genestack-API-Token: [ ] summary: Retrieve a cell by ID tags: - - Cells as User - /api/v1/as-user/cells/by/group/{id}: + - Cells as {Role} + /api/v1/as-{role}/cells/by/group/{id}: get: description: |+ ## Paging For performance reasons this endpoint returns results in "pages" of limited size together with a `cursor` tag. To retrieve the next page of results please supply this `cursor` tag to resume the query from your previous result and get the next page. If there are no more results you will just retrieve an empty result. - operationId: getCellsByGroupAsUser + operationId: getCellsByGroupAs{Role} parameters: - description: Unique identifier (accession) of the cell group. in: path @@ -102,7 +102,7 @@ paths: - Genestack-API-Token: [ ] summary: Retrieve cells from a given group tags: - - Cells as User + - Cells as {Role} components: schemas: Cell: diff --git a/openapi/v1/expressionUser.yaml b/openapi/v1/expressionUser.yaml deleted file mode 100644 index b7f4e3b4..00000000 --- a/openapi/v1/expressionUser.yaml +++ /dev/null @@ -1,682 +0,0 @@ -openapi: 3.1.0 -info: - description: |- - This swagger page describes the expressionUser API endpoints for ODM. These are typically used to find and retrieve any tabular data (not only expression data) except Gene Variant or Flow Cytometry. - - Before carrying out any API calls you will need an API token. API tokens can be obtained under your profile within the Genestack software. - - To try out calls in this swagger page: - - 1. Click the 'Authorize' button below to enter your API token - 2. Scroll to the 'Parameters' section for the method you wish to try out and click the 'Try it out' button - 3. Enter parameter values that you wish to try - 4. Scroll to the bottom of the Parameters section and click the 'Execute' bar that appears - - - The server response will be in the section that follows. - title: ODM API - version: default-released -tags: -- name: Expression SPoT as User -paths: - /api/v1/as-user/expressions: - get: - description: |+ - Retrieve all expression data and metadata objects that match a query. - - ## Metadata full-text queries - Single words can be supplied as is, otherwise use speech marks (`"`) to quote queries that include whitespace. Speech marks and backslash characters in the query need to be escaped with a backslash (`\`). - - ## Metadata filters - Metadata filters are key-value pairs joined by an operator. The `=` operator matches literal values/string. The `!=` operator matches anything except the literal value/string. The `<` or `>` operators match numerical results that are less or greater than the supplied value. Strings containing whitespace need to be quoted with (`"`). - - ## Combinations - Metadata queries/filters for the same parameter can be combined with `&&`, `AND`, `||` and `OR` operators, using white-space to separate out the terms and operators. Parentheses `( )` can be used for complex expressions. - - ## Versioning - Specific versions of omics data files (eg. GCT) can be queried via the useVersions parameter. Different versions of an omics data file are associated via their CHAIN_ID metadata value. This CHAIN_ID can be supplied to the useVersions parameter along with the version number or specific omics data file accessions to include them in the query. If nothing is supplied to the useVersions parameter then only the active version (which is usually the last one imported) is queried. This acts as a filter before the rest of the query is carried out. - - Example usage: - useVersions=* (query all versions, including those without CHAIN_IDs) - useVersions=v2 (query the second version. If there is no second version then the data file is not queried) - useVersions=v1,v0 (query the first version and any data files without CHAIN_IDs(v0) ) - useVersions=GSVC002:v3 (for omics data files with a CHAIN_ID of GSCV002 query the third version) - useVersions=GSVC002:GSF00494,GSF000496 (for omics data files with a CHAIN_ID of GSCV002 query only the specific accessions GSF00494 and GSF000496) - - Rules for multiple CHAIN_IDs can be supplied to the parameter using the ; separator. - - ## Paging - For performance reasons this endpoint returns results in "pages" of limited size together with a `cursor` tag. To retrieve the next page of results please supply this `cursor` tag to resume the query from your previous result and get the next page. If there are no more results you will just retrieve an empty result. - - operationId: getExpressionDataAsUser - parameters: - - description: Supply this parameter with the value `term_id` as part of the - query to return extended information including IDs for values and dictionaries. - in: query - name: responseFormat - schema: - $ref: "#/components/schemas/ResponseFormat" - - description: Filter by expression metadata (key-value metadata pair(s)). E.g. - `"Normalization Method"=TPM`. - in: query - name: filter - schema: - type: string - - description: Search for expression objects via a full text query over all - expression metadata. E.g. `TPM`. Queries matching dictionary terms are automatically - expanded to include synonyms. - in: query - name: query - schema: - type: string - - description: |- - If the full-text query term is present in an ODM dictionary, enabling this parameter will modify the query to include child terms of the full-text query. - - For example, the search query "Body fluid" can be expanded to include the term "Blood" (a child term of "Body fluid") so files containing either "Body fluid" or "Blood" in their metadata will be returned in the search results. - - The parent-child relationship is defined by the key "broaders" or "subClassOf" in the dictionary. - - If the full query term is not present in a dictionary then this parameter has no effect. - in: query - name: searchSpecificTerms - schema: - type: boolean - - description: Autogenerated numeric ID that corresponds to the column and is used to link data from the same - run to a sample, library or preparation. Multiple values can be provided as a list. - in: query - name: runFilter - schema: - $ref: "#/components/schemas/RunFilter" - style: form - - description: Column name from the file to which all data for a sample, library or preparation is related. Multiple values can be provided as a list to retrieve data from multiple columns. - explode: true - in: query - name: runSourceFilter - schema: - items: - type: string - example: Run Source ID - type: array - style: form - - description: Minimum threshold (inclusive) for returned expression values. - in: query - name: minExpressionLevel - schema: - format: double - type: number - - description: "List of features to return. These features must match exactly\ - \ the probe IDs in the GCT file. Example: `1552269_at`" - explode: true - in: query - name: featureList - schema: - items: - type: string - example: KRAS - type: array - style: form - - description: |- - Specify which versions of omics data files are used in the query. By default the active version is used. See Versioning above. Syntax: - - \* or `v` or ``:`v` or ``:`` - in: query - name: useVersions - schema: - type: string - - description: |- - The parameter defines amount of metadata attributes to return: - - 1. `minimal_data` - return metadata attributes according to the default template. - 2. `extended_data_included` - return metadata attributes according to applied template, if object doesn’t have applied template, default template will be used. This is the default for User endpoints. - 3. `original_data_included` - return all metadata attributes with values and null attributes, if they are present in the applied template. This is the default for Curator endpoints. - in: query - name: returnedMetadataFields - schema: - enum: - - minimal_data - - extended_data_included - - original_data_included - type: string - - description: Maximum number of results to return per page (see Paging above). - This value must be between 0 and 2000 (inclusive). The default is 2000. - in: query - name: pageLimit - schema: - format: int32 - type: integer - - description: The page tag to resume results from (see paging above). - in: query - name: cursor - schema: - type: string - responses: - "200": - content: - application/json: - schema: - $ref: "#/components/schemas/ExpressionResponse" - description: Retrieved Expression data. - "400": - content: {} - description: Expression data cannot be retrieved. - "401": - content: {} - description: |- - User is not authenticated. Please supply a valid Access Token in the `Authorization` HTTP header (e.g. Authorization: bearer [token]) - or Genestack API token in the `Genestack-API-Token` header (this token may be obtained from the Genestack UI _Profile_ page). - "404": - content: {} - description: No object exists with the given ID. - "500": - content: {} - description: "An internal server error occurred. This indicates an unexpected\ - \ failure in the Genestack system, please file a bug report to support@genestack.com,\ - \ including the error details." - security: - - Access-token: [] - - Genestack-API-Token: [] - summary: Retrieve multiple expression data and metadata objects - tags: - - Expression SPoT as User - /api/v1/as-user/expressions/group: - get: - description: |- - Retrieve all group metadata objects that match a query. - - ## Metadata full-text queries - Single words can be supplied as is, otherwise use speech marks (`"`) to quote queries that include whitespace. Speech marks and backslash characters in the query need to be escaped with a backslash (`\`). - - ## Metadata filters - Metadata filters are key-value pairs joined by an operator. The `=` operator matches literal values/string. The `!=` operator matches anything except the literal value/string. The `<` or `>` operators match numerical results that are less or greater than the supplied value. Strings containing whitespace need to be quoted with (`"`). - - ## Combinations - Metadata queries/filters for the same parameter can be combined with `&&`, `AND`, `||` and `OR` operators, using white-space to separate out the terms and operators. Parentheses `( )` can be used for complex expressions. - - ## Versioning - Specific versions of omics data files (eg. GCT) can be queried via the useVersions parameter. Different versions of an omics data file are associated via their CHAIN_ID metadata value. This CHAIN_ID can be supplied to the useVersions parameter along with the version number or specific omics data file accessions to include them in the query. If nothing is supplied to the useVersions parameter then only the active version (which is usually the last one imported) is queried. This acts as a filter before the rest of the query is carried out. - - Example usage: - useVersions=* (query all versions, including those without CHAIN_IDs) - useVersions=v2 (query the second version. If there is no second version then the data file is not queried) - useVersions=v1,v0 (query the first version and any data files without CHAIN_IDs(v0) ) - useVersions=GSVC002:v3 (for omics data files with a CHAIN_ID of GSCV002 query the third version) - useVersions=GSVC002:GSF00494,GSF000496 (for omics data files with a CHAIN_ID of GSCV002 query only the specific accessions GSF00494 and GSF000496) - - Rules for multiple CHAIN_IDs can be supplied to the parameter using the ; separator. - - ## Paging - For performance reasons this endpoint returns results in "pages" of limited size. In order to retrieve all matching results the client needs to request multiple pages starting from an offset to the first result. You can do this using the pageOffset query parameter. A value of 0 (the default) instructs the server to return the first page of results, 100 would return a page of results starting from the 101st result and so on. To retrieve all results, iterate through pages using `pageOffset` values of `n * pageLimit` until a page returns fewer results than the page limit, which indicates there are no more results. - - ## List operation - - This endpoint can be called with no `query` parameter. Doing so returns a list of all data objects. - operationId: searchExpressionGroupsAsUser - parameters: - - description: Supply this parameter with the value `term_id` as part of the - query to return extended information including IDs for values and dictionaries. - in: query - name: responseFormat - schema: - $ref: "#/components/schemas/ResponseFormat" - - description: Filter by expression metadata (key-value metadata pair(s)). E.g. - `"Normalization Method"=TPM`. - in: query - name: filter - schema: - type: string - - description: Search for expression objects via a full text query over all - expression metadata. E.g. `TPM`. Queries matching dictionary terms are automatically - expanded to include synonyms. - in: query - name: query - schema: - type: string - - description: |- - If the full-text query term is present in an ODM dictionary, enabling this parameter will modify the query to include child terms of the full-text query. - - For example, the search query "Body fluid" can be expanded to include the term "Blood" (a child term of "Body fluid") so files containing either "Body fluid" or "Blood" in their metadata will be returned in the search results. - - The parent-child relationship is defined by the key "broaders" or "subClassOf" in the dictionary. - - If the full query term is not present in a dictionary then this parameter has no effect. - in: query - name: searchSpecificTerms - schema: - type: boolean - - description: |- - The parameter defines amount of metadata attributes to return: - - 1. `minimal_data` - return metadata attributes according to the default template. - 2. `extended_data_included` - return metadata attributes according to applied template, if object doesn’t have applied template, default template will be used. This is the default for User endpoints. - 3. `original_data_included` - return all metadata attributes with values and null attributes, if they are present in the applied template. This is the default for Curator endpoints. - in: query - name: returnedMetadataFields - schema: - enum: - - minimal_data - - extended_data_included - - original_data_included - type: string - - description: |- - Specify which versions of omics data files are used in the query. By default the active version is used. See Versioning above. Syntax: - - \* or `v` or ``:`v` or ``:`` - in: query - name: useVersions - schema: - type: string - - description: "Show the page {pageOffset+1} results from the start of the results.\ - \ E.g. 100 will show a page of results starting from the 101st result.\ - \ The default value is 0." - in: query - name: pageOffset - schema: - format: int32 - type: integer - - description: Maximum number of results to return per page (see Paging above). - This value must be between 0 and 2000 (inclusive). The default is 2000. - in: query - name: pageLimit - schema: - format: int32 - type: integer - responses: - "200": - content: - application/json: - schema: - $ref: "#/components/schemas/ListResponse" - description: The request was successful. The returned value is a list of - objects. - "400": - content: {} - description: The supplied object ID is invalid. - "401": - content: {} - description: |- - User is not authenticated. Please supply a valid Access Token in the `Authorization` HTTP header (e.g. Authorization: bearer [token]) - or Genestack API token in the `Genestack-API-Token` header (this token may be obtained from the Genestack UI _Profile_ page). - "404": - content: {} - description: No object exists with the given ID. - "500": - content: {} - description: "An internal server error occurred. This indicates an unexpected\ - \ failure in the Genestack system, please file a bug report to support@genestack.com,\ - \ including the error details." - security: - - Access-token: [] - - Genestack-API-Token: [] - summary: Retrieve groups that match a query - tags: - - Expression SPoT as User - /api/v1/as-user/expressions/group/by/run/{id}: - get: - operationId: getExpressionGroupByRunAsUser - parameters: - - description: Supply this parameter with the value `term_id` as part of the - query to return extended information including IDs for values and dictionaries. - in: query - name: responseFormat - schema: - $ref: "#/components/schemas/ResponseFormat" - - description: Unique identifier (runId) of the run. - in: path - name: id - required: true - schema: - type: string - - description: |- - The parameter defines amount of metadata attributes to return: - - 1. `minimal_data` - return metadata attributes according to the default template. - 2. `extended_data_included` - return metadata attributes according to applied template, if object doesn’t have applied template, default template will be used. This is the default for User endpoints. - 3. `original_data_included` - return all metadata attributes with values and null attributes, if they are present in the applied template. This is the default for Curator endpoints. - in: query - name: returnedMetadataFields - schema: - enum: - - minimal_data - - extended_data_included - - original_data_included - type: string - responses: - "200": - content: - application/json: - schema: - $ref: "#/components/schemas/MetadataWithId" - description: The request was successful. The returned value is the object. - "400": - content: {} - description: The supplied object ID is invalid. - "401": - content: {} - description: |- - User is not authenticated. Please supply a valid Access Token in the `Authorization` HTTP header (e.g. Authorization: bearer [token]) - or Genestack API token in the `Genestack-API-Token` header (this token may be obtained from the Genestack UI _Profile_ page). - "404": - content: {} - description: No object exists with the given ID. - "500": - content: {} - description: "An internal server error occurred. This indicates an unexpected\ - \ failure in the Genestack system, please file a bug report to support@genestack.com,\ - \ including the error details." - security: - - Access-token: [] - - Genestack-API-Token: [] - summary: Retrieve a single group object by run ID (runId) - tags: - - Expression SPoT as User - /api/v1/as-user/expressions/group/{id}: - get: - operationId: getExpressionGroupAsUser - parameters: - - description: Supply this parameter with the value `term_id` as part of the - query to return extended information including IDs for values and dictionaries. - in: query - name: responseFormat - schema: - $ref: "#/components/schemas/ResponseFormat" - - description: Expression group identifier (groupId). - in: path - name: id - required: true - schema: - type: string - - description: |- - The parameter defines amount of metadata attributes to return: - - 1. `minimal_data` - return metadata attributes according to the default template. - 2. `extended_data_included` - return metadata attributes according to applied template, if object doesn’t have applied template, default template will be used. This is the default for User endpoints. - 3. `original_data_included` - return all metadata attributes with values and null attributes, if they are present in the applied template. This is the default for Curator endpoints. - in: query - name: returnedMetadataFields - schema: - enum: - - minimal_data - - extended_data_included - - original_data_included - type: string - responses: - "200": - content: - application/json: - schema: - $ref: "#/components/schemas/MetadataWithId" - description: The request was successful. The returned value is the object. - "400": - content: {} - description: The supplied object ID is invalid. - "401": - content: {} - description: |- - User is not authenticated. Please supply a valid Access Token in the `Authorization` HTTP header (e.g. Authorization: bearer [token]) - or Genestack API token in the `Genestack-API-Token` header (this token may be obtained from the Genestack UI _Profile_ page). - "404": - content: {} - description: No object exists with the given ID. - "500": - content: {} - description: "An internal server error occurred. This indicates an unexpected\ - \ failure in the Genestack system, please file a bug report to support@genestack.com,\ - \ including the error details." - security: - - Access-token: [] - - Genestack-API-Token: [] - summary: Retrieve a single expression group by ID (groupId) - tags: - - Expression SPoT as User - /api/v1/as-user/expressions/runs/by/group/{id}: - get: - description: |+ - ## Paging - For performance reasons this endpoint returns results in "pages" of limited size together with a `cursor` tag. To retrieve the next page of results please supply this `cursor` tag to resume the query from your previous result and get the next page. If there are no more results you will just retrieve an empty result. - - operationId: searchExpressionRunsAsUser - parameters: - - description: Unique identifier (accession) of the object. - in: path - name: id - required: true - schema: - type: string - - description: The page tag to resume results from (see paging above). - in: query - name: cursor - schema: - type: string - - description: Maximum number of results to return per page (see Paging above). - This value must be between 0 and 2000 (inclusive). The default is 2000. - in: query - name: pageLimit - schema: - format: int32 - type: integer - responses: - "200": - content: - application/json: - schema: - $ref: "#/components/schemas/RunsResponse" - description: The request was successful. The returned value is the object. - "400": - content: {} - description: The supplied object ID is invalid. - "401": - content: {} - description: |- - User is not authenticated. Please supply a valid Access Token in the `Authorization` HTTP header (e.g. Authorization: bearer [token]) - or Genestack API token in the `Genestack-API-Token` header (this token may be obtained from the Genestack UI _Profile_ page). - "404": - content: {} - description: No object exists with the given ID. - "500": - content: {} - description: "An internal server error occurred. This indicates an unexpected\ - \ failure in the Genestack system, please file a bug report to support@genestack.com,\ - \ including the error details." - security: - - Access-token: [] - - Genestack-API-Token: [] - summary: Retrieve run objects related to the given group - tags: - - Expression SPoT as User - /api/v1/as-user/expressions/{id}: - get: - operationId: getExpressionAsUser - parameters: - - description: Supply this parameter with the value `term_id` as part of the - query to return extended information including IDs for values and dictionaries. - in: query - name: responseFormat - schema: - $ref: "#/components/schemas/ResponseFormat" - - description: Expression object unique identifier (itemId). - in: path - name: id - required: true - schema: - type: string - - description: |- - The parameter defines amount of metadata attributes to return: - - 1. `minimal_data` - return metadata attributes according to the default template. - 2. `extended_data_included` - return metadata attributes according to applied template, if object doesn’t have applied template, default template will be used. This is the default for User endpoints. - 3. `original_data_included` - return all metadata attributes with values and null attributes, if they are present in the applied template. This is the default for Curator endpoints. - in: query - name: returnedMetadataFields - schema: - enum: - - minimal_data - - extended_data_included - - original_data_included - type: string - responses: - "200": - content: - application/json: - schema: - $ref: "#/components/schemas/ExpressionItem" - description: The request was successful. The returned value is the object. - "400": - content: {} - description: The supplied object ID is invalid. - "401": - content: {} - description: |- - User is not authenticated. Please supply a valid Access Token in the `Authorization` HTTP header (e.g. Authorization: bearer [token]) - or Genestack API token in the `Genestack-API-Token` header (this token may be obtained from the Genestack UI _Profile_ page). - "404": - content: {} - description: No object exists with the given ID. - "500": - content: {} - description: "An internal server error occurred. This indicates an unexpected\ - \ failure in the Genestack system, please file a bug report to support@genestack.com,\ - \ including the error details." - security: - - Access-token: [] - - Genestack-API-Token: [] - summary: Retrieve a single expression object by ID (itemId) - tags: - - Expression SPoT as User - /api/v1/as-user/expressions/{id}/versions: - get: - operationId: getExpressionVersionsAsUser - parameters: - - description: Expression object run ID (runId). - in: path - name: id - required: true - schema: - type: string - responses: - "200": - content: - application/json: - schema: - items: - $ref: "#/components/schemas/CommitInfo" - type: array - description: The request was successful. The returned value is the list - of object versions. - "401": - content: {} - description: |- - User is not authenticated. Please supply a valid Access Token in the `Authorization` HTTP header (e.g. Authorization: bearer [token]) - or Genestack API token in the `Genestack-API-Token` header (this token may be obtained from the Genestack UI _Profile_ page). - "500": - content: {} - description: "An internal server error occurred. This indicates an unexpected\ - \ failure in the Genestack system, please file a bug report to support@genestack.com,\ - \ including the error details." - security: - - Access-token: [] - - Genestack-API-Token: [] - summary: Retrieve a list of expression object versions by run ID (runId) - tags: - - Expression SPoT as User - /api/v1/as-user/expressions/{id}/versions/{version}: - get: - operationId: getExpressionByVersionAsUser - parameters: - - description: Supply this parameter with the value `term_id` as part of the - query to return extended information including IDs for values and dictionaries. - in: query - name: responseFormat - schema: - $ref: "#/components/schemas/ResponseFormat" - - description: Expression object run ID (runId). - in: path - name: id - required: true - schema: - type: string - - description: Unique version of the object. - in: path - name: version - required: true - schema: - type: string - - description: |- - The parameter defines amount of metadata attributes to return: - - 1. `minimal_data` - return metadata attributes according to the default template. - 2. `extended_data_included` - return metadata attributes according to applied template, if object doesn’t have applied template, default template will be used. This is the default for User endpoints. - 3. `original_data_included` - return all metadata attributes with values and null attributes, if they are present in the applied template. This is the default for Curator endpoints. - in: query - name: returnedMetadataFields - schema: - enum: - - minimal_data - - extended_data_included - - original_data_included - type: string - responses: - "200": - content: - application/json: - schema: - $ref: "#/components/schemas/SignalRun" - description: The request was successful. The returned value is the object. - "400": - content: {} - description: The supplied object ID is invalid. - "401": - content: {} - description: |- - User is not authenticated. Please supply a valid Access Token in the `Authorization` HTTP header (e.g. Authorization: bearer [token]) - or Genestack API token in the `Genestack-API-Token` header (this token may be obtained from the Genestack UI _Profile_ page). - "404": - content: {} - description: No object exists with the given ID. - "500": - content: {} - description: "An internal server error occurred. This indicates an unexpected\ - \ failure in the Genestack system, please file a bug report to support@genestack.com,\ - \ including the error details." - security: - - Access-token: [] - - Genestack-API-Token: [] - summary: Retrieve a single expression object by run ID and its version - tags: - - Expression SPoT as User -components: - schemas: - CommitInfo: - $ref: "./schemas/common/CommitInfo.yaml" - ExpressionItem: - $ref: "./schemas/expression/ExpressionItem.yaml" - ExpressionResponse: - $ref: "./schemas/expression/ExpressionResponse.yaml" - IntegrationHelper: - $ref: "./schemas/common/IntegrationHelper.yaml" - ListResponse: - $ref: "./schemas/common/ListResponse.yaml" - MetaResponse: - $ref: "./schemas/common/MetaResponse.yaml" - MetadataContent: - $ref: "./schemas/common/MetadataContent.yaml" - MetadataWithId: - $ref: "./schemas/common/MetadataWithId.yaml" - PaginationInfo: - $ref: "./schemas/common/PaginationInfo.yaml" - ResponseFormat: - $ref: "./schemas/common/ResponseFormat.yaml" - RunFilter: - $ref: "./schemas/common/RunFilter.yaml" - RunsResponse: - $ref: "./schemas/common/RunsResponse.yaml" - SignalRun: - $ref: "./schemas/common/SignalRun.yaml" - securitySchemes: - Access-token: - in: header - name: Authorization - type: apiKey - Genestack-API-Token: - in: header - name: Genestack-API-Token - type: apiKey diff --git a/openapi/v1/expressionCurator.yaml b/openapi/v1/expression{Role}.yaml similarity index 96% rename from openapi/v1/expressionCurator.yaml rename to openapi/v1/expression{Role}.yaml index 191d7c22..6960168b 100644 --- a/openapi/v1/expressionCurator.yaml +++ b/openapi/v1/expression{Role}.yaml @@ -1,7 +1,7 @@ openapi: 3.1.0 info: description: |- - This swagger page describes the expressionCurator APIs. + This swagger page describes the expression{Role} API endpoints for ODM. These are typically used to find and retrieve any tabular data (not only expression data) except Gene Variant or Flow Cytometry. Before carrying out any API calls you will need an API token. API tokens can be obtained under your profile within the Genestack software. @@ -16,9 +16,9 @@ info: title: ODM API version: default-released tags: -- name: Expression SPoT as Curator +- name: Expression SPoT as {Role} paths: - /api/v1/as-curator/expressions: + /api/v1/as-{role}/expressions: get: description: |+ Retrieve all expression data and metadata objects that match a query. @@ -47,7 +47,7 @@ paths: ## Paging For performance reasons this endpoint returns results in "pages" of limited size together with a `cursor` tag. To retrieve the next page of results please supply this `cursor` tag to resume the query from your previous result and get the next page. If there are no more results you will just retrieve an empty result. - operationId: getExpressionDataAsCurator + operationId: getExpressionDataAs{Role} parameters: - description: Supply this parameter with the value `term_id` as part of the query to return extended information including IDs for values and dictionaries. @@ -176,8 +176,8 @@ paths: - Genestack-API-Token: [] summary: Retrieve multiple expression data and metadata objects tags: - - Expression SPoT as Curator - /api/v1/as-curator/expressions/group: + - Expression SPoT as {Role} + /api/v1/as-{role}/expressions/group: get: description: |- Retrieve all group metadata objects that match a query. @@ -209,7 +209,7 @@ paths: ## List operation This endpoint can be called with no `query` parameter. Doing so returns a list of all data objects. - operationId: searchExpressionGroupsAsCurator + operationId: searchExpressionGroupsAs{Role} parameters: - description: Supply this parameter with the value `term_id` as part of the query to return extended information including IDs for values and dictionaries. @@ -308,10 +308,10 @@ paths: - Genestack-API-Token: [] summary: Retrieve groups that match a query tags: - - Expression SPoT as Curator - /api/v1/as-curator/expressions/group/by/run/{id}: + - Expression SPoT as {Role} + /api/v1/as-{role}/expressions/group/by/run/{id}: get: - operationId: getExpressionGroupByRunAsCurator + operationId: getExpressionGroupByRunAs{Role} parameters: - description: Supply this parameter with the value `term_id` as part of the query to return extended information including IDs for values and dictionaries. @@ -367,10 +367,10 @@ paths: - Genestack-API-Token: [] summary: Retrieve a single group object by run ID (runId) tags: - - Expression SPoT as Curator - /api/v1/as-curator/expressions/group/{id}: + - Expression SPoT as {Role} + /api/v1/as-{role}/expressions/group/{id}: get: - operationId: getExpressionGroupAsCurator + operationId: getExpressionGroupAs{Role} parameters: - description: Supply this parameter with the value `term_id` as part of the query to return extended information including IDs for values and dictionaries. @@ -426,14 +426,14 @@ paths: - Genestack-API-Token: [] summary: Retrieve a single expression group by ID (groupId) tags: - - Expression SPoT as Curator - /api/v1/as-curator/expressions/runs/by/group/{id}: + - Expression SPoT as {Role} + /api/v1/as-{role}/expressions/runs/by/group/{id}: get: description: |+ ## Paging For performance reasons this endpoint returns results in "pages" of limited size together with a `cursor` tag. To retrieve the next page of results please supply this `cursor` tag to resume the query from your previous result and get the next page. If there are no more results you will just retrieve an empty result. - operationId: searchExpressionRunsAsCurator + operationId: searchExpressionRunsAs{Role} parameters: - description: Unique identifier (accession) of the object. in: path @@ -481,10 +481,10 @@ paths: - Genestack-API-Token: [] summary: Retrieve run objects related to the given group tags: - - Expression SPoT as Curator - /api/v1/as-curator/expressions/{id}: + - Expression SPoT as {Role} + /api/v1/as-{role}/expressions/{id}: get: - operationId: getExpressionAsCurator + operationId: getExpressionAs{Role} parameters: - description: Supply this parameter with the value `term_id` as part of the query to return extended information including IDs for values and dictionaries. @@ -540,7 +540,8 @@ paths: - Genestack-API-Token: [] summary: Retrieve a single expression object by ID (itemId) tags: - - Expression SPoT as Curator + - Expression SPoT as {Role} +##{Role=Curator} patch: description: |- ## Basic operation @@ -597,9 +598,10 @@ paths: tags: - Expression SPoT as Curator x-codegen-request-body-name: body - /api/v1/as-curator/expressions/{id}/versions: +## end {Role=Curator} + /api/v1/as-{role}/expressions/{id}/versions: get: - operationId: getExpressionVersionsAsCurator + operationId: getExpressionVersionsAs{Role} parameters: - description: Expression object run ID (runId). in: path @@ -632,10 +634,10 @@ paths: - Genestack-API-Token: [] summary: Retrieve a list of expression object versions by run ID (runId) tags: - - Expression SPoT as Curator - /api/v1/as-curator/expressions/{id}/versions/{version}: + - Expression SPoT as {Role} + /api/v1/as-{role}/expressions/{id}/versions/{version}: get: - operationId: getExpressionByVersionAsCurator + operationId: getExpressionByVersionAs{Role} parameters: - description: Supply this parameter with the value `term_id` as part of the query to return extended information including IDs for values and dictionaries. @@ -697,7 +699,7 @@ paths: - Genestack-API-Token: [] summary: Retrieve a single expression object by run ID and its version tags: - - Expression SPoT as Curator + - Expression SPoT as {Role} components: schemas: CommitInfo: diff --git a/openapi/v1/fileUser.yaml b/openapi/v1/fileUser.yaml deleted file mode 100644 index 6bbf2e5e..00000000 --- a/openapi/v1/fileUser.yaml +++ /dev/null @@ -1,246 +0,0 @@ -openapi: 3.1.0 -info: - description: |- - This swagger page describes the APIs for retrieving files. - title: ODM API - version: default-released -tags: - - name: Files as User -paths: - /api/v1/as-user/files/{id}/download: - head: - description: |+ - Check if a file exists by its accession. - - This endpoint can be used to check if a file exists and accessible before downloading it. - operationId: headFileAsUser - summary: Check if a file exists by ID (accession). - parameters: - - description: Unique identifier (accession) of the object. - in: path - name: id - required: true - schema: - type: string - responses: - "200": - description: File exists. Additional metadata is provided in the response headers. - "400": - content: {} - description: File cannot be downloaded. - "401": - content: {} - description: |- - User is not authenticated. Please supply a valid Access Token in the `Authorization` HTTP header (e.g. Authorization: bearer [token]) - or Genestack API token in the `Genestack-API-Token` header (this token may be obtained from the Genestack UI _Profile_ page). - "404": - content: {} - description: No object exists with the given ID. - "406": - content: {} - description: File cannot be downloaded. - "500": - content: {} - description: "An internal server error occurred. This indicates an unexpected\ - \ failure in the Genestack system, please file a bug report to" - security: - - Access-token: [ ] - - Genestack-API-Token: [ ] - tags: - - Files as User - get: - description: |+ - Download a file by its accession. - operationId: getFileAsUser - parameters: - - description: Unique identifier (accession) of the object. - in: path - name: id - required: true - schema: - type: string - - name: Range - in: header - required: false - schema: - type: string - example: bytes=0- - description: | - Request a specific range of bytes to support partial downloads. - Example: `bytes=0-1024` to download the first 1024 bytes. Supplying several - ranges is not supported. - responses: - "200": - description: File downloaded successfully - content: - application/octet-stream: - schema: - type: string - format: binary - "206": - description: Partial content downloaded successfully - content: - application/octet-stream: - schema: - type: string - format: binary - "400": - content: {} - description: File cannot be retrieved. - "401": - content: {} - description: |- - User is not authenticated. Please supply a valid Access Token in the `Authorization` HTTP header (e.g. Authorization: bearer [token]) - or Genestack API token in the `Genestack-API-Token` header (this token may be obtained from the Genestack UI _Profile_ page). - "404": - content: {} - description: No object exists with the given ID. - "406": - content: {} - description: File cannot be downloaded. - "500": - content: {} - description: "An internal server error occurred. This indicates an unexpected\ - \ failure in the Genestack system, please file a bug report to support@genestack.com,\ - \ including the error details." - security: - - Access-token: [] - - Genestack-API-Token: [] - summary: Retrieve a file by ID (accession) - tags: - - Files as User - /api/v1/as-user/files/{id}: - get: - operationId: getFileMetadataByIdAsUser - parameters: - - description: Unique identifier (accession) of the object. - in: path - name: id - required: true - schema: - type: string - - description: Select `true` in order to include file structure (contents) for .h5, .h5ad, .zip, .gz to the response. - in: query - name: includeContents - required: false - schema: - default: false - type: boolean - responses: - "200": - content: - application/json: - schema: - $ref: "#/components/schemas/AFile" - description: The request was successful. The returned value is the object. - "400": - content: { } - description: Invalid data in the request. See the error message for details. - "401": - content: { } - description: |- - User is not authenticated. Please supply a valid Access Token in the `Authorization` HTTP header (e.g. Authorization: bearer [token]) - or Genestack API token in the `Genestack-API-Token` header (this token may be obtained from the Genestack UI _Profile_ page). - "404": - content: { } - description: Object with provided accession could not be found in ODM. - "500": - content: { } - description: "An internal server error occurred. This indicates an unexpected\ - \ failure in the Genestack system, please file a bug report to support@genestack.com,\ - \ including the error details." - security: - - Access-token: [ ] - - Genestack-API-Token: [ ] - summary: Retrieve file's metadata by ID (accession) - tags: - - Files as User - /api/v1/as-user/files: - get: - operationId: getFilesMetadataAsUser - description: |- - ## Metadata full-text queries - Single words can be supplied as is, otherwise use speech marks (`"`) to quote queries that include whitespace. Speech marks and backslash characters in the query need to be escaped with a backslash (`\`). - - ## Paging - For performance reasons, this endpoint returns results in "pages" of limited size. In order to retrieve all matching results the client needs to request multiple pages starting from an offset to the first result. You can do this using the `pageOffset` query parameter. A value of 0 (the default) instructs the server to return the first page of results, 100 would return a page of results starting from the 101st result and so on. To retrieve all results, iterate through pages by increasing the offset in multiples of limit (e.g., `offset = n * limit`), until all results have been retrieved. The total number of pages can be calculated by dividing the total number of results by the limit. - - ## List operation - - This endpoint can be called without any query parameters. When called this way, it returns a list of all files metadata objects. - parameters: - - in: query - name: filter - description: Filter by files metadata (key-value metadata pair(s)). - schema: - type: string - - in: query - name: query - description: Search for files via a full-text query over all file metadata. - schema: - type: string - - in: query - name: includeContents - description: Select `true` in order to include file structure (contents) for .h5, .h5ad, .zip, .gz to the response. - required: false - schema: - default: false - type: boolean - - in: query - name: pageLimit - description: Maximum number of results to return per page (see Paging above). This value must be - between 0 and 2000 (inclusive). The default is 2000. - schema: - format: int32 - type: integer - - in: query - name: pageOffset - description: Show the page {pageOffset + 1} results from the start of the results. E.g. 100 will show - a page of results starting from the 101st result. The default value is 0. - schema: - format: int32 - type: integer - responses: - "200": - content: - application/json: - schema: - $ref: "#/components/schemas/ListResponse" - text/tab-separated-values: - schema: - $ref: "#/components/schemas/ListResponse" - description: The request was successful. The returned value is a list of objects. - "400": - content: { } - description: Invalid data in the request. See the error message for details. - "401": - content: { } - description: |- - User is not authenticated. Please supply a valid Access Token in the `Authorization` HTTP header (e.g. Authorization: bearer [token]) - or Genestack API token in the `Genestack-API-Token` header (this token may be obtained from the Genestack UI _Profile_ page). - "500": - content: { } - description: "An internal server error occurred. This indicates an unexpected\ - \ failure in the Genestack system, please file a bug report to support@genestack.com,\ - \ including the error details." - security: - - Access-token: [ ] - - Genestack-API-Token: [ ] - summary: Retrieve file's metadata by its fields - tags: - - Files as User -components: - schemas: - AFile: - $ref: "./schemas/afile/AFile.yaml" - ListResponse: - $ref: "./schemas/common/ListResponse.yaml" - securitySchemes: - Access-token: - in: header - name: Authorization - type: apiKey - Genestack-API-Token: - in: header - name: Genestack-API-Token - type: apiKey diff --git a/openapi/v1/fileCurator.yaml b/openapi/v1/file{Role}.yaml similarity index 95% rename from openapi/v1/fileCurator.yaml rename to openapi/v1/file{Role}.yaml index 591e3860..a717baac 100644 --- a/openapi/v1/fileCurator.yaml +++ b/openapi/v1/file{Role}.yaml @@ -5,15 +5,16 @@ info: title: ODM API version: default-released tags: - - name: Files as Curator + - name: Files as {Role} paths: - /api/v1/as-curator/files/{id}/download: + /api/v1/as-{role}/files/{id}/download: head: description: |+ Check if a file exists by its accession. This endpoint can be used to check if a file exists and accessible before downloading it. - operationId: headFileAsCurator + operationId: headFileAs{Role} + summary: Check if a file exists by ID (accession). parameters: - description: Unique identifier (accession) of the object. in: path @@ -46,11 +47,11 @@ paths: - Access-token: [ ] - Genestack-API-Token: [ ] tags: - - Files as Curator + - Files as {Role} get: description: |+ Download a file by its accession. - operationId: getFileAsCurator + operationId: getFileAs{Role} parameters: - description: Unique identifier (accession) of the object. in: path @@ -107,10 +108,10 @@ paths: - Genestack-API-Token: [] summary: Retrieve a file by ID (accession) tags: - - Files as Curator - /api/v1/as-curator/files/{id}: + - Files as {Role} + /api/v1/as-{role}/files/{id}: get: - operationId: getFileMetadataByIdAsCurator + operationId: getFileMetadataByIdAs{Role} parameters: - description: Unique identifier (accession) of the object. in: path @@ -153,10 +154,10 @@ paths: - Genestack-API-Token: [ ] summary: Retrieve file's metadata by ID (accession) tags: - - Files as Curator - /api/v1/as-curator/files: + - Files as {Role} + /api/v1/as-{role}/files: get: - operationId: getFilesMetadataAsCurator + operationId: getFilesMetadataAs{Role} description: |- ## Metadata full-text queries Single words can be supplied as is, otherwise use speech marks (`"`) to quote queries that include whitespace. Speech marks and backslash characters in the query need to be escaped with a backslash (`\`). @@ -227,7 +228,7 @@ paths: - Genestack-API-Token: [ ] summary: Retrieve file's metadata by its fields tags: - - Files as Curator + - Files as {Role} components: schemas: AFile: diff --git a/openapi/v1/libraryUser.yaml b/openapi/v1/libraryUser.yaml deleted file mode 100644 index d5ed6482..00000000 --- a/openapi/v1/libraryUser.yaml +++ /dev/null @@ -1,413 +0,0 @@ -openapi: 3.1.0 -info: - description: |- - This swagger page describes the libraryUser API endpoints for ODM. These are typically used to find and retrieve library metadata. - - Before carrying out any API calls you will need an API token. API tokens can be obtained under your profile within the Genestack software. - - To try out calls in this swagger page: - - 1. Click the 'Authorize' button below to enter your API token - 2. Scroll to the 'Parameters' section for the method you wish to try out and click the 'Try it out' button - 3. Enter parameter values that you wish to try - 4. Scroll to the bottom of the Parameters section and click the 'Execute' bar that appears - - - The server response will be in the section that follows. - title: ODM API - version: default-released -tags: -- name: Library SPoT as User -paths: - /api/v1/as-user/libraries: - get: - description: |- - Retrieve library metadata objects by searching/listing library metadata. - - ## Metadata full-text queries - Single words can be supplied as is, otherwise use speech marks (`"`) to quote queries that include whitespace. Speech marks and backslash characters in the query need to be escaped with a backslash (`\`). - - ## Metadata filters - Metadata filters are key-value pairs joined by an operator. The `=` operator matches literal values/string. The `!=` operator matches anything except the literal value/string. The `<` or `>` operators match numerical results that are less or greater than the supplied value. Strings containing whitespace need to be quoted with (`"`). - - ## Combinations - Metadata queries/filters for the same parameter can be combined with `&&`, `AND`, `||` and `OR` operators, using white-space to separate out the terms and operators. Parentheses `( )` can be used for complex expressions. - - ## Paging - For performance reasons this endpoint returns results in "pages" of limited size. In order to retrieve all matching results the client needs to request multiple pages starting from an offset to the first result. You can do this using the pageOffset query parameter. A value of 0 (the default) instructs the server to return the first page of results, 100 would return a page of results starting from the 101st result and so on. To retrieve all results, iterate through pages using `pageOffset` values of `n * pageLimit` until a page returns fewer results than the page limit, which indicates there are no more results. - - ## List operation - - This endpoint can be called with no `query` parameter. Doing so returns a list of all variant objects. - operationId: searchLibrariesAsUser - parameters: - - description: Supply this parameter with the value `term_id` as part of the - query to return extended information including IDs for values and dictionaries. - in: query - name: responseFormat - schema: - $ref: "#/components/schemas/ResponseFormat" - - description: Filter by library metadata (key-value metadata pair(s)). E.g. - `"Library Type"=RNA-Seq-1` - in: query - name: filter - schema: - type: string - - description: Search for library objects via a full-text query over all library - metadata fields. E.g. `"illumina HiSeq500"`. Queries matching dictionary - terms are automatically expanded to include synonyms. - in: query - name: query - schema: - type: string - - description: |- - If the full-text query term is present in an ODM dictionary, enabling this parameter will modify the query to include child terms of the full-text query. - - For example, the search query "Body fluid" can be expanded to include the term "Blood" (a child term of "Body fluid") so files containing either "Body fluid" or "Blood" in their metadata will be returned in the search results. - - The parent-child relationship is defined by the key "broaders" or "subClassOf" in the dictionary. - - If the full query term is not present in a dictionary then this parameter has no effect. - in: query - name: searchSpecificTerms - schema: - type: boolean - - description: |- - The parameter defines amount of metadata attributes to return: - - 1. `minimal_data` - return metadata attributes according to the default template. - 2. `extended_data_included` - return metadata attributes according to applied template, if object doesn’t have applied template, default template will be used. This is the default for User endpoints. - 3. `original_data_included` - return all metadata attributes with values and null attributes, if they are present in the applied template. This is the default for Curator endpoints. - in: query - name: returnedMetadataFields - schema: - enum: - - minimal_data - - extended_data_included - - original_data_included - type: string - - description: |- - Attribute to sort by, with optional ascending/descending marker, of the form `"[+|-]"`. - - No marker or `"+"` indicates ascending sort, and `"-"` indicates descending sort. - - *Default:* sort by ID in ascending order. - in: query - name: sort - schema: - enum: - - id - - creation - - last_update - - name - - +id - - +creation - - +last_update - - +name - - -id - - -creation - - -last_update - - -name - type: string - - description: Maximum number of results to return per page (see Paging above). - This value must be between 0 and 2000 (inclusive). The default is 2000. - in: query - name: pageLimit - schema: - format: int32 - type: integer - - description: "Show the page {pageOffset+1} results from the start of the results.\ - \ E.g. 100 will show a page of results starting from the 101st result.\ - \ The default value is 0." - in: query - name: pageOffset - schema: - format: int32 - type: integer - responses: - "200": - content: - application/json: - schema: - $ref: "#/components/schemas/ListResponse" - text/tab-separated-values: - schema: - $ref: "#/components/schemas/ListResponse" - description: The request was successful. The returned value is a list of - objects. - "401": - content: {} - description: |- - User is not authenticated. Please supply a valid Access Token in the `Authorization` HTTP header (e.g. Authorization: bearer [token]) - or Genestack API token in the `Genestack-API-Token` header (this token may be obtained from the Genestack UI _Profile_ page). - "500": - content: {} - description: "An internal server error occurred. This indicates an unexpected\ - \ failure in the Genestack system, please file a bug report to support@genestack.com,\ - \ including the error details." - security: - - Access-token: [] - - Genestack-API-Token: [] - summary: List or search for library metadata objects - tags: - - Library SPoT as User - /api/v1/as-user/libraries/by/group/{id}: - get: - operationId: getLibrariesByGroupAsUser - parameters: - - description: Supply this parameter with the value `term_id` as part of the - query to return extended information including IDs for values and dictionaries. - in: query - name: responseFormat - schema: - $ref: "#/components/schemas/ResponseFormat" - - description: Unique identifier (accession) of the object. - in: path - name: id - required: true - schema: - type: string - - description: |- - The parameter defines amount of metadata attributes to return: - - 1. `minimal_data` - return metadata attributes according to the default template. - 2. `extended_data_included` - return metadata attributes according to applied template, if object doesn’t have applied template, default template will be used. This is the default for User endpoints. - 3. `original_data_included` - return all metadata attributes with values and null attributes, if they are present in the applied template. This is the default for Curator endpoints. - in: query - name: returnedMetadataFields - schema: - enum: - - minimal_data - - extended_data_included - - original_data_included - type: string - - description: "Show the page {pageOffset+1} results from the start of the results.\ - \ E.g. 100 will show a page of results starting from the 101st result.\ - \ The default value is 0." - in: query - name: pageOffset - schema: - format: int32 - type: integer - - description: Maximum number of results to return per page (see Paging above). - This value must be between 0 and 2000 (inclusive). The default is 2000. - in: query - name: pageLimit - schema: - format: int32 - type: integer - responses: - "200": - content: - application/json: - schema: - $ref: "#/components/schemas/ListResponse" - description: The request was successful. The returned value is a list of - objects. - "400": - content: {} - description: The supplied object ID is invalid. - "401": - content: {} - description: |- - User is not authenticated. Please supply a valid Access Token in the `Authorization` HTTP header (e.g. Authorization: bearer [token]) - or Genestack API token in the `Genestack-API-Token` header (this token may be obtained from the Genestack UI _Profile_ page). - "404": - content: {} - description: No object exists with the given ID. - "500": - content: {} - description: "An internal server error occurred. This indicates an unexpected\ - \ failure in the Genestack system, please file a bug report to support@genestack.com,\ - \ including the error details." - security: - - Access-token: [] - - Genestack-API-Token: [] - summary: Retrieve libraries related to the given group - tags: - - Library SPoT as User - /api/v1/as-user/libraries/{id}: - get: - operationId: getLibraryAsUser - parameters: - - description: Supply this parameter with the value `term_id` as part of the - query to return extended information including IDs for values and dictionaries. - in: query - name: responseFormat - schema: - $ref: "#/components/schemas/ResponseFormat" - - description: Unique identifier (accession) of the object. - in: path - name: id - required: true - schema: - type: string - - description: |- - The parameter defines amount of metadata attributes to return: - - 1. `minimal_data` - return metadata attributes according to the default template. - 2. `extended_data_included` - return metadata attributes according to applied template, if object doesn’t have applied template, default template will be used. This is the default for User endpoints. - 3. `original_data_included` - return all metadata attributes with values and null attributes, if they are present in the applied template. This is the default for Curator endpoints. - in: query - name: returnedMetadataFields - schema: - enum: - - minimal_data - - extended_data_included - - original_data_included - type: string - responses: - "200": - content: - application/json: - schema: - $ref: "#/components/schemas/Library" - description: The request was successful. The returned value is the object. - "400": - content: {} - description: The supplied object ID is invalid. - "401": - content: {} - description: |- - User is not authenticated. Please supply a valid Access Token in the `Authorization` HTTP header (e.g. Authorization: bearer [token]) - or Genestack API token in the `Genestack-API-Token` header (this token may be obtained from the Genestack UI _Profile_ page). - "404": - content: {} - description: No object exists with the given ID. - "500": - content: {} - description: "An internal server error occurred. This indicates an unexpected\ - \ failure in the Genestack system, please file a bug report to support@genestack.com,\ - \ including the error details." - security: - - Access-token: [] - - Genestack-API-Token: [] - summary: Retrieve a single library object by ID (accession) - tags: - - Library SPoT as User - /api/v1/as-user/libraries/{id}/versions: - get: - operationId: getLibraryVersionsAsUser - parameters: - - description: Unique identifier (accession) of the object. - in: path - name: id - required: true - schema: - type: string - responses: - "200": - content: - application/json: - schema: - items: - $ref: "#/components/schemas/CommitInfo" - type: array - description: The request was successful. The returned value is the list - of object versions. - "401": - content: {} - description: |- - User is not authenticated. Please supply a valid Access Token in the `Authorization` HTTP header (e.g. Authorization: bearer [token]) - or Genestack API token in the `Genestack-API-Token` header (this token may be obtained from the Genestack UI _Profile_ page). - "500": - content: {} - description: "An internal server error occurred. This indicates an unexpected\ - \ failure in the Genestack system, please file a bug report to support@genestack.com,\ - \ including the error details." - security: - - Access-token: [] - - Genestack-API-Token: [] - summary: Retrieve a list of object versions by ID - tags: - - Library SPoT as User - /api/v1/as-user/libraries/{id}/versions/{version}: - get: - operationId: getLibraryByVersionAsUser - parameters: - - description: Supply this parameter with the value `term_id` as part of the - query to return extended information including IDs for values and dictionaries. - in: query - name: responseFormat - schema: - $ref: "#/components/schemas/ResponseFormat" - - description: Unique identifier (accession) of the object. - in: path - name: id - required: true - schema: - type: string - - description: Unique version of the object. - in: path - name: version - required: true - schema: - type: string - - description: |- - The parameter defines amount of metadata attributes to return: - - 1. `minimal_data` - return metadata attributes according to the default template. - 2. `extended_data_included` - return metadata attributes according to applied template, if object doesn’t have applied template, default template will be used. This is the default for User endpoints. - 3. `original_data_included` - return all metadata attributes with values and null attributes, if they are present in the applied template. This is the default for Curator endpoints. - in: query - name: returnedMetadataFields - schema: - enum: - - minimal_data - - extended_data_included - - original_data_included - type: string - responses: - "200": - content: - application/json: - schema: - $ref: "#/components/schemas/Library" - description: The request was successful. The returned value is the object. - "400": - content: {} - description: The supplied object ID is invalid. - "401": - content: {} - description: |- - User is not authenticated. Please supply a valid Access Token in the `Authorization` HTTP header (e.g. Authorization: bearer [token]) - or Genestack API token in the `Genestack-API-Token` header (this token may be obtained from the Genestack UI _Profile_ page). - "404": - content: {} - description: No object exists with the given ID. - "500": - content: {} - description: "An internal server error occurred. This indicates an unexpected\ - \ failure in the Genestack system, please file a bug report to support@genestack.com,\ - \ including the error details." - security: - - Access-token: [] - - Genestack-API-Token: [] - summary: Retrieve a single library object by ID (accession) - tags: - - Library SPoT as User -components: - schemas: - CommitInfo: - $ref: "./schemas/common/CommitInfo.yaml" - IntegrationHelper: - $ref: "./schemas/common/IntegrationHelper.yaml" - Library: - $ref: "./schemas/library/Library.yaml" - ListResponse: - $ref: "./schemas/common/ListResponse.yaml" - MetaResponse: - $ref: "./schemas/common/MetaResponse.yaml" - PaginationInfo: - $ref: "./schemas/common/PaginationInfo.yaml" - ResponseFormat: - $ref: "./schemas/common/ResponseFormat.yaml" - securitySchemes: - Access-token: - in: header - name: Authorization - type: apiKey - Genestack-API-Token: - in: header - name: Genestack-API-Token - type: apiKey diff --git a/openapi/v1/libraryCurator.yaml b/openapi/v1/library{Role}.yaml similarity index 95% rename from openapi/v1/libraryCurator.yaml rename to openapi/v1/library{Role}.yaml index 832d2ccd..9b2eb264 100644 --- a/openapi/v1/libraryCurator.yaml +++ b/openapi/v1/library{Role}.yaml @@ -1,7 +1,7 @@ openapi: 3.1.0 info: description: |- - This swagger page describes the libraryCurator APIs. + This swagger page describes the library{Role} API endpoints for ODM. These are typically used to find and retrieve library metadata. Before carrying out any API calls you will need an API token. API tokens can be obtained under your profile within the Genestack software. @@ -16,9 +16,9 @@ info: title: ODM API version: default-released tags: -- name: Library SPoT as Curator +- name: Library SPoT as {Role} paths: - /api/v1/as-curator/libraries: + /api/v1/as-{role}/libraries: get: description: |- Retrieve library metadata objects by searching/listing library metadata. @@ -38,7 +38,7 @@ paths: ## List operation This endpoint can be called with no `query` parameter. Doing so returns a list of all variant objects. - operationId: searchLibrariesAsCurator + operationId: searchLibrariesAs{Role} parameters: - description: Supply this parameter with the value `term_id` as part of the query to return extended information including IDs for values and dictionaries. @@ -149,10 +149,10 @@ paths: - Genestack-API-Token: [] summary: List or search for library metadata objects tags: - - Library SPoT as Curator - /api/v1/as-curator/libraries/by/group/{id}: + - Library SPoT as {Role} + /api/v1/as-{role}/libraries/by/group/{id}: get: - operationId: getLibrariesByGroupAsCurator + operationId: getLibrariesByGroupAs{Role} parameters: - description: Supply this parameter with the value `term_id` as part of the query to return extended information including IDs for values and dictionaries. @@ -224,10 +224,10 @@ paths: - Genestack-API-Token: [] summary: Retrieve libraries related to the given group tags: - - Library SPoT as Curator - /api/v1/as-curator/libraries/{id}: + - Library SPoT as {Role} + /api/v1/as-{role}/libraries/{id}: get: - operationId: getLibraryAsCurator + operationId: getLibraryAs{Role} parameters: - description: Supply this parameter with the value `term_id` as part of the query to return extended information including IDs for values and dictionaries. @@ -283,7 +283,8 @@ paths: - Genestack-API-Token: [] summary: Retrieve a single library object by ID (accession) tags: - - Library SPoT as Curator + - Library SPoT as {Role} +##{Role=Curator} patch: description: |- ## Basic operation @@ -294,7 +295,7 @@ paths: ## Attribute values The attribute values are intelligently parsed as booleans, integers, etc. - operationId: updateLibraryAsCurator + operationId: updateLibraryAs{Role} parameters: - description: Unique identifier (accession) of the object. in: path @@ -338,11 +339,12 @@ paths: - Genestack-API-Token: [] summary: Update a library object tags: - - Library SPoT as Curator + - Library SPoT as {Role} x-codegen-request-body-name: body - /api/v1/as-curator/libraries/{id}/versions: +## end {Role=Curator} + /api/v1/as-{role}/libraries/{id}/versions: get: - operationId: getLibraryVersionsAsCurator + operationId: getLibraryVersionsAs{Role} parameters: - description: Unique identifier (accession) of the object. in: path @@ -375,10 +377,10 @@ paths: - Genestack-API-Token: [] summary: Retrieve a list of object versions by ID tags: - - Library SPoT as Curator - /api/v1/as-curator/libraries/{id}/versions/{version}: + - Library SPoT as {Role} + /api/v1/as-{role}/libraries/{id}/versions/{version}: get: - operationId: getLibraryByVersionAsCurator + operationId: getLibraryByVersionAs{Role} parameters: - description: Supply this parameter with the value `term_id` as part of the query to return extended information including IDs for values and dictionaries. @@ -440,7 +442,7 @@ paths: - Genestack-API-Token: [] summary: Retrieve a single library object by ID (accession) tags: - - Library SPoT as Curator + - Library SPoT as {Role} components: schemas: CommitInfo: @@ -453,8 +455,10 @@ components: $ref: "./schemas/common/ListResponse.yaml" MetaResponse: $ref: "./schemas/common/MetaResponse.yaml" +##{Role=Curator} MetadataContent: $ref: "./schemas/common/MetadataContent.yaml" +## end {Role=Curator} PaginationInfo: $ref: "./schemas/common/PaginationInfo.yaml" ResponseFormat: diff --git a/openapi/v1/preparationUser.yaml b/openapi/v1/preparationUser.yaml deleted file mode 100644 index 8d3ed782..00000000 --- a/openapi/v1/preparationUser.yaml +++ /dev/null @@ -1,414 +0,0 @@ -openapi: 3.1.0 -info: - description: |- - This swagger page describes the preparationUser API endpoints for ODM. These are typically used to find and retrieve preparation metadata. - - Before carrying out any API calls you will need an API token. API tokens can be obtained under your profile within the Genestack software. - - To try out calls in this swagger page: - - 1. Click the 'Authorize' button below to enter your API token - 2. Scroll to the 'Parameters' section for the method you wish to try out and click the 'Try it out' button - 3. Enter parameter values that you wish to try - 4. Scroll to the bottom of the Parameters section and click the 'Execute' bar that appears - - - The server response will be in the section that follows. - title: ODM API - version: default-released -tags: -- name: Preparation SPoT as User -paths: - /api/v1/as-user/preparations: - get: - description: |- - Retrieve preparation metadata objects by searching/listing preparation metadata. - - ## Metadata full-text queries - Single words can be supplied as is, otherwise use speech marks (`"`) to quote queries that include whitespace. Speech marks and backslash characters in the query need to be escaped with a backslash (`\`). - - ## Metadata filters - Metadata filters are key-value pairs joined by an operator. The `=` operator matches literal values/string. The `!=` operator matches anything except the literal value/string. The `<` or `>` operators match numerical results that are less or greater than the supplied value. Strings containing whitespace need to be quoted with (`"`). - - ## Combinations - Metadata queries/filters for the same parameter can be combined with `&&`, `AND`, `||` and `OR` operators, using white-space to separate out the terms and operators. Parentheses `( )` can be used for complex expressions. - - ## Paging - For performance reasons this endpoint returns results in "pages" of limited size. In order to retrieve all matching results the client needs to request multiple pages starting from an offset to the first result. You can do this using the pageOffset query parameter. A value of 0 (the default) instructs the server to return the first page of results, 100 would return a page of results starting from the 101st result and so on. To return all results iterate through pages using pageOffset values of `n*pageLimit` until the `resultsExhausted` response field is true. - - ## List operation - - This endpoint can be called with no `query` parameter. Doing so returns a list of all variant objects. - operationId: searchPreparationsAsUser - parameters: - - description: Supply this parameter with the value `term_id` as part of the - query to return extended information including IDs for values and dictionaries. - in: query - name: responseFormat - schema: - $ref: "#/components/schemas/ResponseFormat" - - description: Filter by preparation metadata (key-value metadata pair(s)). - E.g. `Digestion=Trypsin` - in: query - name: filter - schema: - type: string - - description: Search for preparation objects via a full-text query over all - preparation metadata fields. E.g. `"reversed-phase liquid chromatography"`. - Queries matching dictionary terms are automatically expanded to include - synonyms. - in: query - name: query - schema: - type: string - - description: |- - If the full-text query term is present in an ODM dictionary, enabling this parameter will modify the query to include child terms of the full-text query. - - For example, the search query "Body fluid" can be expanded to include the term "Blood" (a child term of "Body fluid") so files containing either "Body fluid" or "Blood" in their metadata will be returned in the search results. - - The parent-child relationship is defined by the key "broaders" or "subClassOf" in the dictionary. - - If the full query term is not present in a dictionary then this parameter has no effect. - in: query - name: searchSpecificTerms - schema: - type: boolean - - description: |- - The parameter defines amount of metadata attributes to return: - - 1. `minimal_data` - return metadata attributes according to the default template. - 2. `extended_data_included` - return metadata attributes according to applied template, if object doesn’t have applied template, default template will be used. This is the default for User endpoints. - 3. `original_data_included` - return all metadata attributes with values and null attributes, if they are present in the applied template. This is the default for Curator endpoints. - in: query - name: returnedMetadataFields - schema: - enum: - - minimal_data - - extended_data_included - - original_data_included - type: string - - description: |- - Attribute to sort by, with optional ascending/descending marker, of the form `"[+|-]"`. - - No marker or `"+"` indicates ascending sort, and `"-"` indicates descending sort. - - *Default:* sort by ID in ascending order. - in: query - name: sort - schema: - enum: - - id - - creation - - last_update - - name - - +id - - +creation - - +last_update - - +name - - -id - - -creation - - -last_update - - -name - type: string - - description: Maximum number of results to return per page (see Paging above). - This value must be between 0 and 2000 (inclusive). The default is 2000. - in: query - name: pageLimit - schema: - format: int32 - type: integer - - description: "Show the page {pageOffset+1} results from the start of the results.\ - \ E.g. 100 will show a page of results starting from the 101st result.\ - \ The default value is 0." - in: query - name: pageOffset - schema: - format: int32 - type: integer - responses: - "200": - content: - application/json: - schema: - $ref: "#/components/schemas/ListResponse" - text/tab-separated-values: - schema: - $ref: "#/components/schemas/ListResponse" - description: The request was successful. The returned value is a list of - objects. - "401": - content: {} - description: |- - User is not authenticated. Please supply a valid Access Token in the `Authorization` HTTP header (e.g. Authorization: bearer [token]) - or Genestack API token in the `Genestack-API-Token` header (this token may be obtained from the Genestack UI _Profile_ page). - "500": - content: {} - description: "An internal server error occurred. This indicates an unexpected\ - \ failure in the Genestack system, please file a bug report to support@genestack.com,\ - \ including the error details." - security: - - Access-token: [] - - Genestack-API-Token: [] - summary: List or search for preparation metadata objects - tags: - - Preparation SPoT as User - /api/v1/as-user/preparations/by/group/{id}: - get: - operationId: getPreparationsByGroupAsUser - parameters: - - description: Supply this parameter with the value `term_id` as part of the - query to return extended information including IDs for values and dictionaries. - in: query - name: responseFormat - schema: - $ref: "#/components/schemas/ResponseFormat" - - description: Unique identifier (accession) of the object. - in: path - name: id - required: true - schema: - type: string - - description: |- - The parameter defines amount of metadata attributes to return: - - 1. `minimal_data` - return metadata attributes according to the default template. - 2. `extended_data_included` - return metadata attributes according to applied template, if object doesn’t have applied template, default template will be used. This is the default for User endpoints. - 3. `original_data_included` - return all metadata attributes with values and null attributes, if they are present in the applied template. This is the default for Curator endpoints. - in: query - name: returnedMetadataFields - schema: - enum: - - minimal_data - - extended_data_included - - original_data_included - type: string - - description: "Show the page {pageOffset+1} results from the start of the results.\ - \ E.g. 100 will show a page of results starting from the 101st result.\ - \ The default value is 0." - in: query - name: pageOffset - schema: - format: int32 - type: integer - - description: Maximum number of results to return per page (see Paging above). - This value must be between 0 and 2000 (inclusive). The default is 2000. - in: query - name: pageLimit - schema: - format: int32 - type: integer - responses: - "200": - content: - application/json: - schema: - $ref: "#/components/schemas/ListResponse" - description: The request was successful. The returned value is a list of - objects. - "400": - content: {} - description: The supplied object ID is invalid. - "401": - content: {} - description: |- - User is not authenticated. Please supply a valid Access Token in the `Authorization` HTTP header (e.g. Authorization: bearer [token]) - or Genestack API token in the `Genestack-API-Token` header (this token may be obtained from the Genestack UI _Profile_ page). - "404": - content: {} - description: No object exists with the given ID. - "500": - content: {} - description: "An internal server error occurred. This indicates an unexpected\ - \ failure in the Genestack system, please file a bug report to support@genestack.com,\ - \ including the error details." - security: - - Access-token: [] - - Genestack-API-Token: [] - summary: Retrieve preparations related to the given group - tags: - - Preparation SPoT as User - /api/v1/as-user/preparations/{id}: - get: - operationId: getPreparationAsUser - parameters: - - description: Supply this parameter with the value `term_id` as part of the - query to return extended information including IDs for values and dictionaries. - in: query - name: responseFormat - schema: - $ref: "#/components/schemas/ResponseFormat" - - description: Unique identifier (accession) of the object. - in: path - name: id - required: true - schema: - type: string - - description: |- - The parameter defines amount of metadata attributes to return: - - 1. `minimal_data` - return metadata attributes according to the default template. - 2. `extended_data_included` - return metadata attributes according to applied template, if object doesn’t have applied template, default template will be used. This is the default for User endpoints. - 3. `original_data_included` - return all metadata attributes with values and null attributes, if they are present in the applied template. This is the default for Curator endpoints. - in: query - name: returnedMetadataFields - schema: - enum: - - minimal_data - - extended_data_included - - original_data_included - type: string - responses: - "200": - content: - application/json: - schema: - $ref: "#/components/schemas/Preparation" - description: The request was successful. The returned value is the object. - "400": - content: {} - description: The supplied object ID is invalid. - "401": - content: {} - description: |- - User is not authenticated. Please supply a valid Access Token in the `Authorization` HTTP header (e.g. Authorization: bearer [token]) - or Genestack API token in the `Genestack-API-Token` header (this token may be obtained from the Genestack UI _Profile_ page). - "404": - content: {} - description: No object exists with the given ID. - "500": - content: {} - description: "An internal server error occurred. This indicates an unexpected\ - \ failure in the Genestack system, please file a bug report to support@genestack.com,\ - \ including the error details." - security: - - Access-token: [] - - Genestack-API-Token: [] - summary: Retrieve a single preparation object by ID (accession) - tags: - - Preparation SPoT as User - /api/v1/as-user/preparations/{id}/versions: - get: - operationId: getPreparationVersionsAsUser - parameters: - - description: Unique identifier (accession) of the object. - in: path - name: id - required: true - schema: - type: string - responses: - "200": - content: - application/json: - schema: - items: - $ref: "#/components/schemas/CommitInfo" - type: array - description: The request was successful. The returned value is the list - of object versions. - "401": - content: {} - description: |- - User is not authenticated. Please supply a valid Access Token in the `Authorization` HTTP header (e.g. Authorization: bearer [token]) - or Genestack API token in the `Genestack-API-Token` header (this token may be obtained from the Genestack UI _Profile_ page). - "500": - content: {} - description: "An internal server error occurred. This indicates an unexpected\ - \ failure in the Genestack system, please file a bug report to support@genestack.com,\ - \ including the error details." - security: - - Access-token: [] - - Genestack-API-Token: [] - summary: Retrieve a list of object versions by ID - tags: - - Preparation SPoT as User - /api/v1/as-user/preparations/{id}/versions/{version}: - get: - operationId: getPreparationByVersionAsUser - parameters: - - description: Supply this parameter with the value `term_id` as part of the - query to return extended information including IDs for values and dictionaries. - in: query - name: responseFormat - schema: - $ref: "#/components/schemas/ResponseFormat" - - description: Unique identifier (accession) of the object. - in: path - name: id - required: true - schema: - type: string - - description: Unique version of the object. - in: path - name: version - required: true - schema: - type: string - - description: |- - The parameter defines amount of metadata attributes to return: - - 1. `minimal_data` - return metadata attributes according to the default template. - 2. `extended_data_included` - return metadata attributes according to applied template, if object doesn’t have applied template, default template will be used. This is the default for User endpoints. - 3. `original_data_included` - return all metadata attributes with values and null attributes, if they are present in the applied template. This is the default for Curator endpoints. - in: query - name: returnedMetadataFields - schema: - enum: - - minimal_data - - extended_data_included - - original_data_included - type: string - responses: - "200": - content: - application/json: - schema: - $ref: "#/components/schemas/Preparation" - description: The request was successful. The returned value is the object. - "400": - content: {} - description: The supplied object ID is invalid. - "401": - content: {} - description: |- - User is not authenticated. Please supply a valid Access Token in the `Authorization` HTTP header (e.g. Authorization: bearer [token]) - or Genestack API token in the `Genestack-API-Token` header (this token may be obtained from the Genestack UI _Profile_ page). - "404": - content: {} - description: No object exists with the given ID. - "500": - content: {} - description: "An internal server error occurred. This indicates an unexpected\ - \ failure in the Genestack system, please file a bug report to support@genestack.com,\ - \ including the error details." - security: - - Access-token: [] - - Genestack-API-Token: [] - summary: Retrieve a single preparation object by ID (accession) - tags: - - Preparation SPoT as User -components: - schemas: - CommitInfo: - $ref: "./schemas/common/CommitInfo.yaml" - IntegrationHelper: - $ref: "./schemas/common/IntegrationHelper.yaml" - ListResponse: - $ref: "./schemas/common/ListResponse.yaml" - MetaResponse: - $ref: "./schemas/common/MetaResponse.yaml" - PaginationInfo: - $ref: "./schemas/common/PaginationInfo.yaml" - Preparation: - $ref: "./schemas/preparation/Preparation.yaml" - ResponseFormat: - $ref: "./schemas/common/ResponseFormat.yaml" - securitySchemes: - Access-token: - in: header - name: Authorization - type: apiKey - Genestack-API-Token: - in: header - name: Genestack-API-Token - type: apiKey diff --git a/openapi/v1/preparationCurator.yaml b/openapi/v1/preparation{Role}.yaml similarity index 95% rename from openapi/v1/preparationCurator.yaml rename to openapi/v1/preparation{Role}.yaml index 56c3dee3..5bebaef8 100644 --- a/openapi/v1/preparationCurator.yaml +++ b/openapi/v1/preparation{Role}.yaml @@ -1,7 +1,7 @@ openapi: 3.1.0 info: description: |- - This swagger page describes the preparationCurator APIs. + This swagger page describes the preparation{Role} API endpoints for ODM. These are typically used to find and retrieve preparation metadata. Before carrying out any API calls you will need an API token. API tokens can be obtained under your profile within the Genestack software. @@ -16,9 +16,9 @@ info: title: ODM API version: default-released tags: -- name: Preparation SPoT as Curator +- name: Preparation SPoT as {Role} paths: - /api/v1/as-curator/preparations: + /api/v1/as-{role}/preparations: get: description: |- Retrieve preparation metadata objects by searching/listing preparation metadata. @@ -38,7 +38,7 @@ paths: ## List operation This endpoint can be called with no `query` parameter. Doing so returns a list of all variant objects. - operationId: searchPreparationsAsCurator + operationId: searchPreparationsAs{Role} parameters: - description: Supply this parameter with the value `term_id` as part of the query to return extended information including IDs for values and dictionaries. @@ -150,10 +150,10 @@ paths: - Genestack-API-Token: [] summary: List or search for preparation metadata objects tags: - - Preparation SPoT as Curator - /api/v1/as-curator/preparations/by/group/{id}: + - Preparation SPoT as {Role} + /api/v1/as-{role}/preparations/by/group/{id}: get: - operationId: getPreparationsByGroupAsCurator + operationId: getPreparationsByGroupAs{Role} parameters: - description: Supply this parameter with the value `term_id` as part of the query to return extended information including IDs for values and dictionaries. @@ -225,10 +225,10 @@ paths: - Genestack-API-Token: [] summary: Retrieve preparations related to the given group tags: - - Preparation SPoT as Curator - /api/v1/as-curator/preparations/{id}: + - Preparation SPoT as {Role} + /api/v1/as-{role}/preparations/{id}: get: - operationId: getPreparationAsCurator + operationId: getPreparationAs{Role} parameters: - description: Supply this parameter with the value `term_id` as part of the query to return extended information including IDs for values and dictionaries. @@ -284,7 +284,8 @@ paths: - Genestack-API-Token: [] summary: Retrieve a single preparation object by ID (accession) tags: - - Preparation SPoT as Curator + - Preparation SPoT as {Role} +##{Role=Curator} patch: description: |- ## Basic operation @@ -295,7 +296,7 @@ paths: ## Attribute values The attribute values are intelligently parsed as booleans, integers, etc. - operationId: updatePreparationAsCurator + operationId: updatePreparationAs{Role} parameters: - description: Unique identifier (accession) of the object. in: path @@ -339,11 +340,12 @@ paths: - Genestack-API-Token: [] summary: Update a preparation object tags: - - Preparation SPoT as Curator + - Preparation SPoT as {Role} x-codegen-request-body-name: body - /api/v1/as-curator/preparations/{id}/versions: +## end {Role=Curator} + /api/v1/as-{role}/preparations/{id}/versions: get: - operationId: getPreparationVersionsAsCurator + operationId: getPreparationVersionsAs{Role} parameters: - description: Unique identifier (accession) of the object. in: path @@ -376,10 +378,10 @@ paths: - Genestack-API-Token: [] summary: Retrieve a list of object versions by ID tags: - - Preparation SPoT as Curator - /api/v1/as-curator/preparations/{id}/versions/{version}: + - Preparation SPoT as {Role} + /api/v1/as-{role}/preparations/{id}/versions/{version}: get: - operationId: getPreparationByVersionAsCurator + operationId: getPreparationByVersionAs{Role} parameters: - description: Supply this parameter with the value `term_id` as part of the query to return extended information including IDs for values and dictionaries. @@ -441,7 +443,7 @@ paths: - Genestack-API-Token: [] summary: Retrieve a single preparation object by ID (accession) tags: - - Preparation SPoT as Curator + - Preparation SPoT as {Role} components: schemas: CommitInfo: @@ -452,8 +454,10 @@ components: $ref: "./schemas/common/ListResponse.yaml" MetaResponse: $ref: "./schemas/common/MetaResponse.yaml" +##{Role=Curator} MetadataContent: $ref: "./schemas/common/MetadataContent.yaml" +## end {Role=Curator} PaginationInfo: $ref: "./schemas/common/PaginationInfo.yaml" Preparation: diff --git a/openapi/v1/sampleUser.yaml b/openapi/v1/sampleUser.yaml deleted file mode 100644 index 2984abc0..00000000 --- a/openapi/v1/sampleUser.yaml +++ /dev/null @@ -1,339 +0,0 @@ -openapi: 3.1.0 -info: - description: |- - This swagger page describes the sampleUser API endpoints for ODM. These are typically used to find and retrieve sample metadata. - - Before carrying out any API calls you will need an API token. API tokens can be obtained under your profile within the Genestack software. - - To try out calls in this swagger page: - - 1. Click the 'Authorize' button below to enter your API token - 2. Scroll to the 'Parameters' section for the method you wish to try out and click the 'Try it out' button - 3. Enter parameter values that you wish to try - 4. Scroll to the bottom of the Parameters section and click the 'Execute' bar that appears - - - The server response will be in the section that follows. - title: ODM API - version: default-released -tags: -- name: Sample SPoT as User -paths: - /api/v1/as-user/samples: - get: - description: |- - Retrieve sample metadata objects by searching/listing sample metadata. - - ## Metadata full-text queries - Single words can be supplied as is, otherwise use speech marks (`"`) to quote queries that include whitespace. Speech marks and backslash characters in the query need to be escaped with a backslash (`\`). - - ## Metadata filters - Metadata filters are key-value pairs joined by an operator. The `=` operator matches literal values/string. The `!=` operator matches anything except the literal value/string. The `<` or `>` operators match numerical results that are less or greater than the supplied value. Strings containing whitespace need to be quoted with (`"`). - - ## Combinations - Metadata queries/filters for the same parameter can be combined with `&&`, `AND`, `||` and `OR` operators, using white-space to separate out the terms and operators. Parentheses `( )` can be used for complex expressions. - - ## Paging - For performance reasons this endpoint returns results in "pages" of limited size. In order to retrieve all matching results the client needs to request multiple pages starting from an offset to the first result. You can do this using the pageOffset query parameter. A value of 0 (the default) instructs the server to return the first page of results, 100 would return a page of results starting from the 101st result and so on. To return all results iterate through pages using pageOffset values of `n*pageLimit` until the `resultsExhausted` response field is true. - - ## List operation - - This endpoint can be called with no `query` parameter. Doing so returns a list of all variant objects. - operationId: searchSamplesAsUser - parameters: - - description: Supply this parameter with the value `term_id` as part of the - query to return extended information including IDs for values and dictionaries. - in: query - name: responseFormat - schema: - $ref: "#/components/schemas/ResponseFormat" - - description: |+ - Filter by sample metadata (key-value metadata pair(s)). E.g. `"Species or strain"="Homo sapiens"` - - in: query - name: filter - schema: - type: string - - description: Search for sample objects via a full-text query over all sample - metadata fields. E.g. `Clozapine`. Queries matching dictionary terms are - automatically expanded to include synonyms. - in: query - name: query - schema: - type: string - - description: |- - If the full-text query term is present in an ODM dictionary, enabling this parameter will modify the query to include child terms of the full-text query. - - For example, the search query "Body fluid" can be expanded to include the term "Blood" (a child term of "Body fluid") so files containing either "Body fluid" or "Blood" in their metadata will be returned in the search results. - - The parent-child relationship is defined by the key "broaders" or "subClassOf" in the dictionary. - - If the full query term is not present in a dictionary then this parameter has no effect. - in: query - name: searchSpecificTerms - schema: - type: boolean - - description: |- - The parameter defines amount of metadata attributes to return: - - 1. `minimal_data` - return metadata attributes according to the default template. - 2. `extended_data_included` - return metadata attributes according to applied template, if object doesn’t have applied template, default template will be used. This is the default for User endpoints. - 3. `original_data_included` - return all metadata attributes with values and null attributes, if they are present in the applied template. This is the default for Curator endpoints. - in: query - name: returnedMetadataFields - schema: - enum: - - minimal_data - - extended_data_included - - original_data_included - type: string - - description: |- - Attribute to sort by, with optional ascending/descending marker, of the form `"[+|-]"`. - - No marker or `"+"` indicates ascending sort, and `"-"` indicates descending sort. - - *Default:* sort by ID in ascending order. - in: query - name: sort - schema: - enum: - - id - - creation - - last_update - - name - - +id - - +creation - - +last_update - - +name - - -id - - -creation - - -last_update - - -name - type: string - - description: Maximum number of results to return. This value must be between - 0 and 2000 (inclusive). - in: query - name: pageLimit - schema: - format: int32 - type: integer - - description: "Show the page {pageOffset+1} results from the start of the results.\ - \ E.g. 100 will show a page of results starting from the 101st result.\ - \ The default value is 0." - in: query - name: pageOffset - schema: - format: int32 - type: integer - responses: - "200": - content: - application/json: - schema: - $ref: "#/components/schemas/ListResponse" - text/tab-separated-values: - schema: - $ref: "#/components/schemas/ListResponse" - description: The request was successful. The returned value is a list of - objects. - "401": - content: {} - description: |- - User is not authenticated. Please supply a valid Access Token in the `Authorization` HTTP header (e.g. Authorization: bearer [token]) - or Genestack API token in the `Genestack-API-Token` header (this token may be obtained from the Genestack UI _Profile_ page). - "500": - content: {} - description: "An internal server error occurred. This indicates an unexpected\ - \ failure in the Genestack system, please file a bug report to support@genestack.com,\ - \ including the error details." - security: - - Access-token: [] - - Genestack-API-Token: [] - summary: List or search for sample metadata objects - tags: - - Sample SPoT as User - /api/v1/as-user/samples/{id}: - get: - operationId: getSampleAsUser - parameters: - - description: Supply this parameter with the value `term_id` as part of the - query to return extended information including IDs for values and dictionaries. - in: query - name: responseFormat - schema: - $ref: "#/components/schemas/ResponseFormat" - - description: Unique identifier (accession) of the object. - in: path - name: id - required: true - schema: - type: string - - description: |- - The parameter defines amount of metadata attributes to return: - - 1. `minimal_data` - return metadata attributes according to the default template. - 2. `extended_data_included` - return metadata attributes according to applied template, if object doesn’t have applied template, default template will be used. This is the default for User endpoints. - 3. `original_data_included` - return all metadata attributes with values and null attributes, if they are present in the applied template. This is the default for Curator endpoints. - in: query - name: returnedMetadataFields - schema: - enum: - - minimal_data - - extended_data_included - - original_data_included - type: string - responses: - "200": - content: - application/json: - schema: - $ref: "#/components/schemas/Sample" - description: The request was successful. The returned value is the object. - "400": - content: {} - description: The supplied object ID is invalid. - "401": - content: {} - description: |- - User is not authenticated. Please supply a valid Access Token in the `Authorization` HTTP header (e.g. Authorization: bearer [token]) - or Genestack API token in the `Genestack-API-Token` header (this token may be obtained from the Genestack UI _Profile_ page). - "404": - content: {} - description: No object exists with the given ID. - "500": - content: {} - description: "An internal server error occurred. This indicates an unexpected\ - \ failure in the Genestack system, please file a bug report to support@genestack.com,\ - \ including the error details." - security: - - Access-token: [] - - Genestack-API-Token: [] - summary: Retrieve a single sample object by ID (accession) - tags: - - Sample SPoT as User - /api/v1/as-user/samples/{id}/versions: - get: - operationId: getSampleVersionsAsUser - parameters: - - description: Unique identifier (accession) of the object. - in: path - name: id - required: true - schema: - type: string - responses: - "200": - content: - application/json: - schema: - items: - $ref: "#/components/schemas/CommitInfo" - type: array - description: The request was successful. The returned value is the list - of object versions. - "401": - content: {} - description: |- - User is not authenticated. Please supply a valid Access Token in the `Authorization` HTTP header (e.g. Authorization: bearer [token]) - or Genestack API token in the `Genestack-API-Token` header (this token may be obtained from the Genestack UI _Profile_ page). - "500": - content: {} - description: "An internal server error occurred. This indicates an unexpected\ - \ failure in the Genestack system, please file a bug report to support@genestack.com,\ - \ including the error details." - security: - - Access-token: [] - - Genestack-API-Token: [] - summary: Retrieve a list of object versions by ID - tags: - - Sample SPoT as User - /api/v1/as-user/samples/{id}/versions/{version}: - get: - operationId: getSampleByVersionAsUser - parameters: - - description: Supply this parameter with the value `term_id` as part of the - query to return extended information including IDs for values and dictionaries. - in: query - name: responseFormat - schema: - $ref: "#/components/schemas/ResponseFormat" - - description: Unique identifier (accession) of the object. - in: path - name: id - required: true - schema: - type: string - - description: Unique version of the object. - in: path - name: version - required: true - schema: - type: string - - description: |- - The parameter defines amount of metadata attributes to return: - - 1. `minimal_data` - return metadata attributes according to the default template. - 2. `extended_data_included` - return metadata attributes according to applied template, if object doesn’t have applied template, default template will be used. This is the default for User endpoints. - 3. `original_data_included` - return all metadata attributes with values and null attributes, if they are present in the applied template. This is the default for Curator endpoints. - in: query - name: returnedMetadataFields - schema: - enum: - - minimal_data - - extended_data_included - - original_data_included - type: string - responses: - "200": - content: - application/json: - schema: - $ref: "#/components/schemas/Sample" - description: The request was successful. The returned value is the object. - "400": - content: {} - description: The supplied object ID is invalid. - "401": - content: {} - description: |- - User is not authenticated. Please supply a valid Access Token in the `Authorization` HTTP header (e.g. Authorization: bearer [token]) - or Genestack API token in the `Genestack-API-Token` header (this token may be obtained from the Genestack UI _Profile_ page). - "404": - content: {} - description: No object exists with the given ID. - "500": - content: {} - description: "An internal server error occurred. This indicates an unexpected\ - \ failure in the Genestack system, please file a bug report to support@genestack.com,\ - \ including the error details." - security: - - Access-token: [] - - Genestack-API-Token: [] - summary: Retrieve a single sample object by ID (accession) - tags: - - Sample SPoT as User -components: - schemas: - CommitInfo: - $ref: "./schemas/common/CommitInfo.yaml" - IntegrationHelper: - $ref: "./schemas/common/IntegrationHelper.yaml" - ListResponse: - $ref: "./schemas/common/ListResponse.yaml" - MetaResponse: - $ref: "./schemas/common/MetaResponse.yaml" - PaginationInfo: - $ref: "./schemas/common/PaginationInfo.yaml" - ResponseFormat: - $ref: "./schemas/common/ResponseFormat.yaml" - Sample: - $ref: "./schemas/sample/Sample.yaml" - securitySchemes: - Access-token: - in: header - name: Authorization - type: apiKey - Genestack-API-Token: - in: header - name: Genestack-API-Token - type: apiKey diff --git a/openapi/v1/sampleCurator.yaml b/openapi/v1/sample{Role}.yaml similarity index 95% rename from openapi/v1/sampleCurator.yaml rename to openapi/v1/sample{Role}.yaml index c72b175b..721130d1 100644 --- a/openapi/v1/sampleCurator.yaml +++ b/openapi/v1/sample{Role}.yaml @@ -1,7 +1,7 @@ openapi: 3.1.0 info: description: |- - This swagger page describes the sampleCurator APIs. + This swagger page describes the sample{Role} API endpoints for ODM. These are typically used to find and retrieve sample metadata. Before carrying out any API calls you will need an API token. API tokens can be obtained under your profile within the Genestack software. @@ -16,9 +16,9 @@ info: title: ODM API version: default-released tags: -- name: Sample SPoT as Curator +- name: Sample SPoT as {Role} paths: - /api/v1/as-curator/samples: + /api/v1/as-{role}/samples: get: description: |- Retrieve sample metadata objects by searching/listing sample metadata. @@ -38,7 +38,7 @@ paths: ## List operation This endpoint can be called with no `query` parameter. Doing so returns a list of all variant objects. - operationId: searchSamplesAsCurator + operationId: searchSamplesAs{Role} parameters: - description: Supply this parameter with the value `term_id` as part of the query to return extended information including IDs for values and dictionaries. @@ -150,10 +150,10 @@ paths: - Genestack-API-Token: [] summary: List or search for sample metadata objects tags: - - Sample SPoT as Curator - /api/v1/as-curator/samples/{id}: + - Sample SPoT as {Role} + /api/v1/as-{role}/samples/{id}: get: - operationId: getSampleAsCurator + operationId: getSampleAs{Role} parameters: - description: Supply this parameter with the value `term_id` as part of the query to return extended information including IDs for values and dictionaries. @@ -209,7 +209,8 @@ paths: - Genestack-API-Token: [] summary: Retrieve a single sample object by ID (accession) tags: - - Sample SPoT as Curator + - Sample SPoT as {Role} +##{Role=Curator} patch: description: |- ## Basic operation @@ -220,7 +221,7 @@ paths: ## Attribute values The attribute values are intelligently parsed as booleans, integers, etc. - operationId: updateSampleAsCurator + operationId: updateSampleAs{Role} parameters: - description: Unique identifier (accession) of the object. in: path @@ -264,11 +265,12 @@ paths: - Genestack-API-Token: [] summary: Update a sample object tags: - - Sample SPoT as Curator + - Sample SPoT as {Role} x-codegen-request-body-name: body - /api/v1/as-curator/samples/{id}/versions: +## end {Role=Curator} + /api/v1/as-{role}/samples/{id}/versions: get: - operationId: getSampleVersionsAsCurator + operationId: getSampleVersionsAs{Role} parameters: - description: Unique identifier (accession) of the object. in: path @@ -301,10 +303,10 @@ paths: - Genestack-API-Token: [] summary: Retrieve a list of object versions by ID tags: - - Sample SPoT as Curator - /api/v1/as-curator/samples/{id}/versions/{version}: + - Sample SPoT as {Role} + /api/v1/as-{role}/samples/{id}/versions/{version}: get: - operationId: getSampleByVersionAsCurator + operationId: getSampleByVersionAs{Role} parameters: - description: Supply this parameter with the value `term_id` as part of the query to return extended information including IDs for values and dictionaries. @@ -366,7 +368,7 @@ paths: - Genestack-API-Token: [] summary: Retrieve a single sample object by ID (accession) tags: - - Sample SPoT as Curator + - Sample SPoT as {Role} components: schemas: CommitInfo: @@ -377,10 +379,12 @@ components: $ref: "./schemas/common/ListResponse.yaml" MetaResponse: $ref: "./schemas/common/MetaResponse.yaml" +##{Role=Curator} MetadataContent: $ref: "./schemas/common/MetadataContent.yaml" MetadataWithId: $ref: "./schemas/common/MetadataWithId.yaml" +## end {Role=Curator} PaginationInfo: $ref: "./schemas/common/PaginationInfo.yaml" ResponseFormat: diff --git a/openapi/v1/studyUser.yaml b/openapi/v1/studyUser.yaml deleted file mode 100644 index ca54d746..00000000 --- a/openapi/v1/studyUser.yaml +++ /dev/null @@ -1,340 +0,0 @@ -openapi: 3.1.0 -info: - description: |- - This swagger page describes the studyUser API endpoints for ODM. These are typically used to find and retrieve study metadata. - - Before carrying out any API calls you will need an API token. API tokens can be obtained under your profile within the Genestack software. - - To try out calls in this swagger page: - - 1. Click the 'Authorize' button below to enter your API token - 2. Scroll to the 'Parameters' section for the method you wish to try out and click the 'Try it out' button - 3. Enter parameter values that you wish to try - 4. Scroll to the bottom of the Parameters section and click the 'Execute' bar that appears - - - The server response will be in the section that follows. - title: ODM API - version: default-released -tags: -- name: Study SPoT as User -paths: - /api/v1/as-user/studies: - get: - description: |- - Retrieve study metadata objects by searching/listing study metadata. - - ## Metadata full-text queries - Single words can be supplied as is, otherwise use speech marks (`"`) to quote queries that include whitespace. Speech marks and backslash characters in the query need to be escaped with a backslash (`\`). - - ## Metadata filters - Metadata filters are key-value pairs joined by an operator. The `=` operator matches literal values/string. The `!=` operator matches anything except the literal value/string. The `<` or `>` operators match numerical results that are less or greater than the supplied value. Strings containing whitespace need to be quoted with (`"`). - - ## Combinations - Metadata queries/filters for the same parameter can be combined with `&&`, `AND`, `||` and `OR` operators, using white-space to separate out the terms and operators. Parentheses `( )` can be used for complex expressions. - - ## Paging - For performance reasons this endpoint returns results in "pages" of limited size. In order to retrieve all matching results the client needs to request multiple pages starting from an offset to the first result. You can do this using the pageOffset query parameter. A value of 0 (the default) instructs the server to return the first page of results, 100 would return a page of results starting from the 101st result and so on. To return all results iterate through pages using pageOffset values of `n * pageLimit` until the `resultsExhausted` response field is true. - - ## List operation - - This endpoint can be called with no `query` parameter. Doing so returns a list of all study objects. - operationId: searchStudiesAsUser - parameters: - - description: Supply this parameter with the value `term_id` as part of the - query to return extended information including IDs for values and dictionaries. - in: query - name: responseFormat - schema: - $ref: "#/components/schemas/ResponseFormat" - - description: |+ - Filter by study metadata (key-value metadata pair(s)). E.g. `"Study Source"=ArrayExpress` - - - in: query - name: filter - schema: - type: string - - description: Search for study objects via a full-text query over all study - metadata fields. E.g. `"RNA-Seq of human dendritic cells"`. Queries matching - dictionary terms are automatically expanded to include synonyms. - in: query - name: query - schema: - type: string - - description: |- - If the full-text query term is present in an ODM dictionary, enabling this parameter will modify the query to include child terms of the full-text query. - - For example, the search query "Body fluid" can be expanded to include the term "Blood" (a child term of "Body fluid") so files containing either "Body fluid" or "Blood" in their metadata will be returned in the search results. - - The parent-child relationship is defined by the key "broaders" or "subClassOf" in the dictionary. - - If the full query term is not present in a dictionary then this parameter has no effect. - in: query - name: searchSpecificTerms - schema: - type: boolean - - description: |- - The parameter defines amount of metadata attributes to return: - - 1. `minimal_data` - return metadata attributes according to the default template. - 2. `extended_data_included` - return metadata attributes according to applied template, if object doesn’t have applied template, default template will be used. This is the default for User endpoints. - 3. `original_data_included` - return all metadata attributes with values and null attributes, if they are present in the applied template. This is the default for Curator endpoints. - in: query - name: returnedMetadataFields - schema: - enum: - - minimal_data - - extended_data_included - - original_data_included - type: string - - description: |- - Attribute to sort by, with optional ascending/descending marker, of the form `"[+|-]"`. - - No marker or `"+"` indicates ascending sort, and `"-"` indicates descending sort. - - *Default:* sort by ID in ascending order. - in: query - name: sort - schema: - enum: - - id - - creation - - last_update - - name - - +id - - +creation - - +last_update - - +name - - -id - - -creation - - -last_update - - -name - type: string - - description: Maximum number of results to return. This value must be between - 0 and 2000 (inclusive). - in: query - name: pageLimit - schema: - format: int32 - type: integer - - description: "Show the page {pageOffset+1} results from the start of the results.\ - \ E.g. 100 will show a page of results starting from the 101st result.\ - \ The default value is 0." - in: query - name: pageOffset - schema: - format: int32 - type: integer - responses: - "200": - content: - application/json: - schema: - $ref: "#/components/schemas/ListResponse" - text/tab-separated-values: - schema: - $ref: "#/components/schemas/ListResponse" - description: The request was successful. The returned value is a list of - objects. - "401": - content: {} - description: |- - User is not authenticated. Please supply a valid Access Token in the `Authorization` HTTP header (e.g. Authorization: bearer [token]) - or Genestack API token in the `Genestack-API-Token` header (this token may be obtained from the Genestack UI _Profile_ page). - "500": - content: {} - description: "An internal server error occurred. This indicates an unexpected\ - \ failure in the Genestack system, please file a bug report to support@genestack.com,\ - \ including the error details." - security: - - Access-token: [] - - Genestack-API-Token: [] - summary: List or search for study metadata objects - tags: - - Study SPoT as User - /api/v1/as-user/studies/{id}: - get: - operationId: getStudyAsUser - parameters: - - description: Supply this parameter with the value `term_id` as part of the - query to return extended information including IDs for values and dictionaries. - in: query - name: responseFormat - schema: - $ref: "#/components/schemas/ResponseFormat" - - description: Unique identifier (accession) of the object. - in: path - name: id - required: true - schema: - type: string - - description: |- - The parameter defines amount of metadata attributes to return: - - 1. `minimal_data` - return metadata attributes according to the default template. - 2. `extended_data_included` - return metadata attributes according to applied template, if object doesn’t have applied template, default template will be used. This is the default for User endpoints. - 3. `original_data_included` - return all metadata attributes with values and null attributes, if they are present in the applied template. This is the default for Curator endpoints. - in: query - name: returnedMetadataFields - schema: - enum: - - minimal_data - - extended_data_included - - original_data_included - type: string - responses: - "200": - content: - application/json: - schema: - $ref: "#/components/schemas/Study" - description: The request was successful. The returned value is the object. - "400": - content: {} - description: The supplied object ID is invalid. - "401": - content: {} - description: |- - User is not authenticated. Please supply a valid Access Token in the `Authorization` HTTP header (e.g. Authorization: bearer [token]) - or Genestack API token in the `Genestack-API-Token` header (this token may be obtained from the Genestack UI _Profile_ page). - "404": - content: {} - description: No object exists with the given ID. - "500": - content: {} - description: "An internal server error occurred. This indicates an unexpected\ - \ failure in the Genestack system, please file a bug report to support@genestack.com,\ - \ including the error details." - security: - - Access-token: [] - - Genestack-API-Token: [] - summary: Retrieve a single study object by ID (accession) - tags: - - Study SPoT as User - /api/v1/as-user/studies/{id}/versions: - get: - operationId: getStudyVersionsAsUser - parameters: - - description: Unique identifier (accession) of the object. - in: path - name: id - required: true - schema: - type: string - responses: - "200": - content: - application/json: - schema: - items: - $ref: "#/components/schemas/CommitInfo" - type: array - description: The request was successful. The returned value is the list - of object versions. - "401": - content: {} - description: |- - User is not authenticated. Please supply a valid Access Token in the `Authorization` HTTP header (e.g. Authorization: bearer [token]) - or Genestack API token in the `Genestack-API-Token` header (this token may be obtained from the Genestack UI _Profile_ page). - "500": - content: {} - description: "An internal server error occurred. This indicates an unexpected\ - \ failure in the Genestack system, please file a bug report to support@genestack.com,\ - \ including the error details." - security: - - Access-token: [] - - Genestack-API-Token: [] - summary: Retrieve a list of object versions by ID - tags: - - Study SPoT as User - /api/v1/as-user/studies/{id}/versions/{version}: - get: - operationId: getStudyByVersionAsUser - parameters: - - description: Supply this parameter with the value `term_id` as part of the - query to return extended information including IDs for values and dictionaries. - in: query - name: responseFormat - schema: - $ref: "#/components/schemas/ResponseFormat" - - description: Unique identifier (accession) of the object. - in: path - name: id - required: true - schema: - type: string - - description: Unique version of the object. - in: path - name: version - required: true - schema: - type: string - - description: |- - The parameter defines amount of metadata attributes to return: - - 1. `minimal_data` - return metadata attributes according to the default template. - 2. `extended_data_included` - return metadata attributes according to applied template, if object doesn’t have applied template, default template will be used. This is the default for User endpoints. - 3. `original_data_included` - return all metadata attributes with values and null attributes, if they are present in the applied template. This is the default for Curator endpoints. - in: query - name: returnedMetadataFields - schema: - enum: - - minimal_data - - extended_data_included - - original_data_included - type: string - responses: - "200": - content: - application/json: - schema: - $ref: "#/components/schemas/Study" - description: The request was successful. The returned value is the object. - "400": - content: {} - description: The supplied object ID is invalid. - "401": - content: {} - description: |- - User is not authenticated. Please supply a valid Access Token in the `Authorization` HTTP header (e.g. Authorization: bearer [token]) - or Genestack API token in the `Genestack-API-Token` header (this token may be obtained from the Genestack UI _Profile_ page). - "404": - content: {} - description: No object exists with the given ID. - "500": - content: {} - description: "An internal server error occurred. This indicates an unexpected\ - \ failure in the Genestack system, please file a bug report to support@genestack.com,\ - \ including the error details." - security: - - Access-token: [] - - Genestack-API-Token: [] - summary: Retrieve a single study object by ID (accession) - tags: - - Study SPoT as User -components: - schemas: - CommitInfo: - $ref: "./schemas/common/CommitInfo.yaml" - IntegrationHelper: - $ref: "./schemas/common/IntegrationHelper.yaml" - ListResponse: - $ref: "./schemas/common/ListResponse.yaml" - MetaResponse: - $ref: "./schemas/common/MetaResponse.yaml" - PaginationInfo: - $ref: "./schemas/common/PaginationInfo.yaml" - ResponseFormat: - $ref: "./schemas/common/ResponseFormat.yaml" - Study: - $ref: "./schemas/study/Study.yaml" - securitySchemes: - Access-token: - in: header - name: Authorization - type: apiKey - Genestack-API-Token: - in: header - name: Genestack-API-Token - type: apiKey diff --git a/openapi/v1/studyCurator.yaml b/openapi/v1/study{Role}.yaml similarity index 95% rename from openapi/v1/studyCurator.yaml rename to openapi/v1/study{Role}.yaml index f881a10e..c481e22f 100644 --- a/openapi/v1/studyCurator.yaml +++ b/openapi/v1/study{Role}.yaml @@ -1,7 +1,7 @@ openapi: 3.1.0 info: description: |- - This swagger page describes the studyCurator APIs. + This swagger page describes the study{Role} API endpoints for ODM. These are typically used to find and retrieve study metadata. Before carrying out any API calls you will need an API token. API tokens can be obtained under your profile within the Genestack software. @@ -16,9 +16,9 @@ info: title: ODM API version: default-released tags: -- name: Study SPoT as Curator +- name: Study SPoT as {Role} paths: - /api/v1/as-curator/studies: + /api/v1/as-{role}/studies: get: description: |- Retrieve study metadata objects by searching/listing study metadata. @@ -38,7 +38,7 @@ paths: ## List operation This endpoint can be called with no `query` parameter. Doing so returns a list of all study objects. - operationId: searchStudiesAsCurator + operationId: searchStudiesAs{Role} parameters: - description: Supply this parameter with the value `term_id` as part of the query to return extended information including IDs for values and dictionaries. @@ -151,10 +151,10 @@ paths: - Genestack-API-Token: [] summary: List or search for study metadata objects tags: - - Study SPoT as Curator - /api/v1/as-curator/studies/{id}: + - Study SPoT as {Role} + /api/v1/as-{role}/studies/{id}: get: - operationId: getStudyAsCurator + operationId: getStudyAs{Role} parameters: - description: Supply this parameter with the value `term_id` as part of the query to return extended information including IDs for values and dictionaries. @@ -210,7 +210,8 @@ paths: - Genestack-API-Token: [] summary: Retrieve a single study object by ID (accession) tags: - - Study SPoT as Curator + - Study SPoT as {Role} +##{Role=Curator} patch: description: |- ## Basic operation @@ -221,7 +222,7 @@ paths: ## Attribute values The attribute values are intelligently parsed as booleans, integers, etc. - operationId: updateStudyAsCurator + operationId: updateStudyAs{Role} parameters: - description: Unique identifier (accession) of the object. in: path @@ -265,11 +266,12 @@ paths: - Genestack-API-Token: [] summary: Update a study object tags: - - Study SPoT as Curator + - Study SPoT as {Role} x-codegen-request-body-name: body - /api/v1/as-curator/studies/{id}/versions: +## end {Role=Curator} + /api/v1/as-{role}/studies/{id}/versions: get: - operationId: getStudyVersionsAsCurator + operationId: getStudyVersionsAs{Role} parameters: - description: Unique identifier (accession) of the object. in: path @@ -302,10 +304,10 @@ paths: - Genestack-API-Token: [] summary: Retrieve a list of object versions by ID tags: - - Study SPoT as Curator - /api/v1/as-curator/studies/{id}/versions/{version}: + - Study SPoT as {Role} + /api/v1/as-{role}/studies/{id}/versions/{version}: get: - operationId: getStudyByVersionAsCurator + operationId: getStudyByVersionAs{Role} parameters: - description: Supply this parameter with the value `term_id` as part of the query to return extended information including IDs for values and dictionaries. @@ -367,7 +369,7 @@ paths: - Genestack-API-Token: [] summary: Retrieve a single study object by ID (accession) tags: - - Study SPoT as Curator + - Study SPoT as {Role} components: schemas: CommitInfo: @@ -378,8 +380,10 @@ components: $ref: "./schemas/common/ListResponse.yaml" MetaResponse: $ref: "./schemas/common/MetaResponse.yaml" +##{Role=Curator} MetadataContent: $ref: "./schemas/common/MetadataContent.yaml" +## end {Role=Curator} PaginationInfo: $ref: "./schemas/common/PaginationInfo.yaml" ResponseFormat: diff --git a/openapi/v1/variantUser.yaml b/openapi/v1/variantUser.yaml deleted file mode 100644 index 644567aa..00000000 --- a/openapi/v1/variantUser.yaml +++ /dev/null @@ -1,714 +0,0 @@ -openapi: 3.1.0 -info: - description: |- - This swagger page describes the variantUser API endpoints for ODM. These are typically used to find and retrieve variant data and metadata. - - Before carrying out any API calls you will need an API token. API tokens can be obtained under your profile within the Genestack software. - - To try out calls in this swagger page: - - 1. Click the 'Authorize' button below to enter your API token - 2. Scroll to the 'Parameters' section for the method you wish to try out and click the 'Try it out' button - 3. Enter parameter values that you wish to try - 4. Scroll to the bottom of the Parameters section and click the 'Execute' bar that appears - - - The server response will be in the section that follows. - title: ODM API - version: default-released -tags: -- name: Variant SPoT as User -paths: - /api/v1/as-user/variants: - get: - description: |+ - Retrieve all variant data and metadata objects that match a query. - - ## Metadata full-text queries - Single words can be supplied as is, otherwise use speech marks (`"`) to quote queries that include whitespace. Speech marks and backslash characters in the query need to be escaped with a backslash (`\`). - - ## Metadata filters - Metadata filters are key-value pairs joined by an operator. The `=` operator matches literal values/string. The `!=` operator matches anything except the literal value/string. The `<` or `>` operators match numerical results that are less or greater than the supplied value. Strings containing whitespace need to be quoted with (`"`). - - ## Combinations - Metadata queries/filters for the same parameter can be combined with `&&`, `AND`, `||` and `OR` operators, using white-space to separate out the terms and operators. Parentheses `( )` can be used for complex expressions. - - ## Versioning - Specific versions of omics data files (eg. GCT) can be queried via the useVersions parameter. Different versions of an omics data file are associated via their CHAIN_ID metadata value. This CHAIN_ID can be supplied to the useVersions parameter along with the version number or specific omics data file accessions to include them in the query. If nothing is supplied to the useVersions parameter then only the active version (which is usually the last one imported) is queried. This acts as a filter before the rest of the query is carried out. - - Example usage: - useVersions=* (query all versions, including those without CHAIN_IDs) - useVersions=v2 (query the second version. If there is no second version then the data file is not queried) - useVersions=v1,v0 (query the first version and any data files without CHAIN_IDs(v0) ) - useVersions=GSVC002:v3 (for omics data files with a CHAIN_ID of GSCV002 query the third version) - useVersions=GSVC002:GSF00494,GSF000496 (for omics data files with a CHAIN_ID of GSCV002 query only the specific accessions GSF00494 and GSF000496) - - Rules for multiple CHAIN_IDs can be supplied to the parameter using the ; separator. - - ## Paging - For performance reasons this endpoint returns results in "pages" of limited size together with a `cursor` tag. To retrieve the next page of results please supply this `cursor` tag to resume the query from your previous result and get the next page. If there are no more results you will just retrieve an empty result. - - operationId: getAllVariantsAsUser - parameters: - - description: Supply this parameter with the value `term_id` as part of the - query to return extended information including IDs for values and dictionaries. - in: query - name: responseFormat - schema: - $ref: "#/components/schemas/ResponseFormat" - - description: Filter by variant metadata (key-value metadata pair(s)). E.g. - `"Variant Source"=dbSNP`. - in: query - name: filter - schema: - type: string - - description: Search for variant objects via a full text query over all variant - metadata. E.g. `dbSNP`. Queries matching dictionary terms are automatically - expanded to include synonyms. - in: query - name: query - schema: - type: string - - description: |- - If the full-text query term is present in an ODM dictionary, enabling this parameter will modify the query to include child terms of the full-text query. - - For example, the search query "Body fluid" can be expanded to include the term "Blood" (a child term of "Body fluid") so files containing either "Body fluid" or "Blood" in their metadata will be returned in the search results. - - The parent-child relationship is defined by the key "broaders" or "subClassOf" in the dictionary. - - If the full query term is not present in a dictionary then this parameter has no effect. - in: query - name: searchSpecificTerms - schema: - type: boolean - - description: Specify a chromosome interval to find genes between these positions. E.g. `2:233364596-233385916`. Multiple intervals can be provided as a list. - in: query - name: variantRegion - schema: - items: - type: string - example: 2:233364596-233385916 - type: array - style: form - - description: Specify the name of the reference gene associated with a specific location in the reference genome which corresponds to the VCF file (variant group) from which the variant information is derived. By providing the gene name, such as `TP53`, variants located within the same genomic region as the specified gene will be retrieved. Multiple genes can be provided as a list. - in: query - name: variantFeature - schema: - items: - type: string - example: ENSG00000227232 - type: array - style: form - - description: One or more specific variation IDs can be specified. E.g. `rs838705` - in: query - name: variantId - schema: - items: - type: string - example: rs334 - type: array - style: form - - description: |- - The parameter allows to retrieve gene variants based on the filters defined in the vcf file. If not specified, all variants are returned. - - 1. pass - return gene variants which passed all filters - 2. noPass - return gene variants which failed one or more filters - in: query - name: variantFilter - schema: - enum: - - pass - - noPass - type: string - - description: |- - Filter by vcf `INFO` fields. E.g. to filter all variants annotated in dbSNP add `exists(info.DB)`. - Use `!exists(INFO.KEY)` to exclude variants having the key from the search results. - Provide `info.key=value` pair to search for an exact match or `info.key!=value` to exclude it from the search. - Due to the limits of precision in floating point numbers, we use a small range of 0.0000001 to identify close matches. - This means any differences smaller than that won't be detected. For more precise results, please use range queries. - Combine multiple filters for `INFO` fields using `AND` (`&&`), `OR` (`||`) logical operators and parentheses - in: query - name: variantInfo - schema: - type: string - - description: Autogenerated numeric ID that corresponds to a column and is used to link data from the same run to a sample. Multiple values can be provided as a list. - in: query - name: runFilter - schema: - $ref: "#/components/schemas/RunFilter" - style: form - - description: Column name from the file to which all data for a sample is related. Multiple values can be provided as a list to retrieve data from multiple columns. - explode: true - in: query - name: runSourceFilter - schema: - items: - type: string - example: Run Source ID - type: array - style: form - - description: |- - Specify which versions of omics data files are used in the query. By default the active version is used. See Versioning above. Syntax: - - \* or `v` or ``:`v` or ``:`` - in: query - name: useVersions - schema: - type: string - - description: |- - The parameter defines amount of metadata attributes to return: - - 1. `minimal_data` - return metadata attributes according to the default template. - 2. `extended_data_included` - return metadata attributes according to applied template, if object doesn’t have applied template, default template will be used. This is the default for User endpoints. - 3. `original_data_included` - return all metadata attributes with values and null attributes, if they are present in the applied template. This is the default for Curator endpoints. - in: query - name: returnedMetadataFields - schema: - enum: - - minimal_data - - extended_data_included - - original_data_included - type: string - - description: Maximum number of results to return per page (see Paging above). - This value must be between 0 and 2000 (inclusive). The default is 2000. - in: query - name: pageLimit - schema: - format: int32 - type: integer - - description: The page tag to resume results from (see paging above). - in: query - name: cursor - schema: - type: string - responses: - "200": - content: - application/json: - schema: - $ref: "#/components/schemas/VariantResponse" - description: Retrieved variant data. - "400": - content: {} - description: Variant data cannot be retrieved. - "401": - content: {} - description: |- - User is not authenticated. Please supply a valid Access Token in the `Authorization` HTTP header (e.g. Authorization: bearer [token]) - or Genestack API token in the `Genestack-API-Token` header (this token may be obtained from the Genestack UI _Profile_ page). - "404": - content: {} - description: No object exists with the given ID. - "500": - content: {} - description: "An internal server error occurred. This indicates an unexpected\ - \ failure in the Genestack system, please file a bug report to support@genestack.com,\ - \ including the error details." - security: - - Access-token: [] - - Genestack-API-Token: [] - summary: Retrieve multiple variant data and metadata objects - tags: - - Variant SPoT as User - /api/v1/as-user/variants/group: - get: - description: |- - Retrieve all group metadata objects that match a query. - - ## Metadata full-text queries - Single words can be supplied as is, otherwise use speech marks (`"`) to quote queries that include whitespace. Speech marks and backslash characters in the query need to be escaped with a backslash (`\`). - - ## Metadata filters - Metadata filters are key-value pairs joined by an operator. The `=` operator matches literal values/string. The `!=` operator matches anything except the literal value/string. The `<` or `>` operators match numerical results that are less or greater than the supplied value. Strings containing whitespace need to be quoted with (`"`). - - ## Combinations - Metadata queries/filters for the same parameter can be combined with `&&`, `AND`, `||` and `OR` operators, using white-space to separate out the terms and operators. Parentheses `( )` can be used for complex expressions. - - ## Versioning - Specific versions of omics data files (eg. GCT) can be queried via the useVersions parameter. Different versions of an omics data file are associated via their CHAIN_ID metadata value. This CHAIN_ID can be supplied to the useVersions parameter along with the version number or specific omics data file accessions to include them in the query. If nothing is supplied to the useVersions parameter then only the active version (which is usually the last one imported) is queried. This acts as a filter before the rest of the query is carried out. - - Example usage: - useVersions=* (query all versions, including those without CHAIN_IDs) - useVersions=v2 (query the second version. If there is no second version then the data file is not queried) - useVersions=v1,v0 (query the first version and any data files without CHAIN_IDs(v0) ) - useVersions=GSVC002:v3 (for omics data files with a CHAIN_ID of GSCV002 query the third version) - useVersions=GSVC002:GSF00494,GSF000496 (for omics data files with a CHAIN_ID of GSCV002 query only the specific accessions GSF00494 and GSF000496) - - Rules for multiple CHAIN_IDs can be supplied to the parameter using the ; separator. - - ## Paging - For performance reasons this endpoint returns results in "pages" of limited size. In order to retrieve all matching results the client needs to request multiple pages starting from an offset to the first result. You can do this using the pageOffset query parameter. A value of 0 (the default) instructs the server to return the first page of results, 100 would return a page of results starting from the 101st result and so on. To return all results iterate through pages using pageOffset values of `n*pageLimit` until the `resultsExhausted` response field is true. - - ## List operation - - This endpoint can be called with no `query` parameter. Doing so returns a list of all data objects. - operationId: searchVariantGroupsAsUser - parameters: - - description: Supply this parameter with the value `term_id` as part of the - query to return extended information including IDs for values and dictionaries. - in: query - name: responseFormat - schema: - $ref: "#/components/schemas/ResponseFormat" - - description: Filter by variant metadata (key-value metadata pair(s)). E.g. - `"Variant Source"=dbSNP`. - in: query - name: filter - schema: - type: string - - description: Search for variant objects via a full text query over all variant - metadata. E.g. `dbSNP`. Queries matching dictionary terms are automatically - expanded to include synonyms. - in: query - name: query - schema: - type: string - - description: |- - If the full-text query term is present in an ODM dictionary, enabling this parameter will modify the query to include child terms of the full-text query. - - For example, the search query "Body fluid" can be expanded to include the term "Blood" (a child term of "Body fluid") so files containing either "Body fluid" or "Blood" in their metadata will be returned in the search results. - - The parent-child relationship is defined by the key "broaders" or "subClassOf" in the dictionary. - - If the full query term is not present in a dictionary then this parameter has no effect. - in: query - name: searchSpecificTerms - schema: - type: boolean - - description: |- - The parameter defines amount of metadata attributes to return: - - 1. `minimal_data` - return metadata attributes according to the default template. - 2. `extended_data_included` - return metadata attributes according to applied template, if object doesn’t have applied template, default template will be used. This is the default for User endpoints. - 3. `original_data_included` - return all metadata attributes with values and null attributes, if they are present in the applied template. This is the default for Curator endpoints. - in: query - name: returnedMetadataFields - schema: - enum: - - minimal_data - - extended_data_included - - original_data_included - type: string - - description: |- - Specify which versions of omics data files are used in the query. By default the active version is used. See Versioning above. Syntax: - - \* or `v` or ``:`v` or ``:`` - in: query - name: useVersions - schema: - type: string - - description: "Show the page {pageOffset+1} results from the start of the results.\ - \ E.g. 100 will show a page of results starting from the 101st result.\ - \ The default value is 0." - in: query - name: pageOffset - schema: - format: int32 - type: integer - - description: Maximum number of results to return per page (see Paging above). - This value must be between 0 and 2000 (inclusive). The default is 2000. - in: query - name: pageLimit - schema: - format: int32 - type: integer - responses: - "200": - content: - application/json: - schema: - $ref: "#/components/schemas/ListResponse" - description: The request was successful. The returned value is a list of - objects. - "400": - content: {} - description: The supplied object ID is invalid. - "401": - content: {} - description: |- - User is not authenticated. Please supply a valid Access Token in the `Authorization` HTTP header (e.g. Authorization: bearer [token]) - or Genestack API token in the `Genestack-API-Token` header (this token may be obtained from the Genestack UI _Profile_ page). - "404": - content: {} - description: No object exists with the given ID. - "500": - content: {} - description: "An internal server error occurred. This indicates an unexpected\ - \ failure in the Genestack system, please file a bug report to support@genestack.com,\ - \ including the error details." - security: - - Access-token: [] - - Genestack-API-Token: [] - summary: Retrieve groups that match a query - tags: - - Variant SPoT as User - /api/v1/as-user/variants/group/by/run/{id}: - get: - operationId: getVariantGroupByRunAsUser - parameters: - - description: Supply this parameter with the value `term_id` as part of the - query to return extended information including IDs for values and dictionaries. - in: query - name: responseFormat - schema: - $ref: "#/components/schemas/ResponseFormat" - - description: Unique identifier (runId) of the run. - in: path - name: id - required: true - schema: - type: string - - description: |- - The parameter defines amount of metadata attributes to return: - - 1. `minimal_data` - return metadata attributes according to the default template. - 2. `extended_data_included` - return metadata attributes according to applied template, if object doesn’t have applied template, default template will be used. This is the default for User endpoints. - 3. `original_data_included` - return all metadata attributes with values and null attributes, if they are present in the applied template. This is the default for Curator endpoints. - in: query - name: returnedMetadataFields - schema: - enum: - - minimal_data - - extended_data_included - - original_data_included - type: string - responses: - "200": - content: - application/json: - schema: - $ref: "#/components/schemas/VariantMetadataWithId" - description: The request was successful. The returned value is the object. - "400": - content: {} - description: The supplied object ID is invalid. - "401": - content: {} - description: |- - User is not authenticated. Please supply a valid Access Token in the `Authorization` HTTP header (e.g. Authorization: bearer [token]) - or Genestack API token in the `Genestack-API-Token` header (this token may be obtained from the Genestack UI _Profile_ page). - "404": - content: {} - description: No object exists with the given ID. - "500": - content: {} - description: "An internal server error occurred. This indicates an unexpected\ - \ failure in the Genestack system, please file a bug report to support@genestack.com,\ - \ including the error details." - security: - - Access-token: [] - - Genestack-API-Token: [] - summary: Retrieve a single group object by run ID (runId) - tags: - - Variant SPoT as User - /api/v1/as-user/variants/group/{id}: - get: - operationId: getVariantGroupAsUser - parameters: - - description: Supply this parameter with the value `term_id` as part of the - query to return extended information including IDs for values and dictionaries. - in: query - name: responseFormat - schema: - $ref: "#/components/schemas/ResponseFormat" - - description: Variant group identifier (groupId). - in: path - name: id - required: true - schema: - type: string - - description: |- - The parameter defines amount of metadata attributes to return: - - 1. `minimal_data` - return metadata attributes according to the default template. - 2. `extended_data_included` - return metadata attributes according to applied template, if object doesn’t have applied template, default template will be used. This is the default for User endpoints. - 3. `original_data_included` - return all metadata attributes with values and null attributes, if they are present in the applied template. This is the default for Curator endpoints. - in: query - name: returnedMetadataFields - schema: - enum: - - minimal_data - - extended_data_included - - original_data_included - type: string - responses: - "200": - content: - application/json: - schema: - $ref: "#/components/schemas/VariantMetadataWithId" - description: The request was successful. The returned value is the object. - "400": - content: {} - description: The supplied object ID is invalid. - "401": - content: {} - description: |- - User is not authenticated. Please supply a valid Access Token in the `Authorization` HTTP header (e.g. Authorization: bearer [token]) - or Genestack API token in the `Genestack-API-Token` header (this token may be obtained from the Genestack UI _Profile_ page). - "404": - content: {} - description: No object exists with the given ID. - "500": - content: {} - description: "An internal server error occurred. This indicates an unexpected\ - \ failure in the Genestack system, please file a bug report to support@genestack.com,\ - \ including the error details." - security: - - Access-token: [] - - Genestack-API-Token: [] - summary: Retrieve a single variant group by ID (groupId) - tags: - - Variant SPoT as User - /api/v1/as-user/variants/runs/by/group/{id}: - get: - description: |+ - ## Paging - For performance reasons this endpoint returns results in "pages" of limited size together with a `cursor` tag. To retrieve the next page of results please supply this `cursor` tag to resume the query from your previous result and get the next page. If there are no more results you will just retrieve an empty result. - - operationId: searchVariantRunsAsUser - parameters: - - description: Unique identifier (accession) of the object. - in: path - name: id - required: true - schema: - type: string - - description: The page tag to resume results from (see paging above). - in: query - name: cursor - schema: - type: string - - description: Maximum number of results to return per page (see Paging above). - This value must be between 0 and 2000 (inclusive). The default is 2000. - in: query - name: pageLimit - schema: - format: int32 - type: integer - responses: - "200": - content: - application/json: - schema: - $ref: "#/components/schemas/RunsResponse" - description: The request was successful. The returned value is the object. - "400": - content: {} - description: The supplied object ID is invalid. - "401": - content: {} - description: |- - User is not authenticated. Please supply a valid Access Token in the `Authorization` HTTP header (e.g. Authorization: bearer [token]) - or Genestack API token in the `Genestack-API-Token` header (this token may be obtained from the Genestack UI _Profile_ page). - "404": - content: {} - description: No object exists with the given ID. - "500": - content: {} - description: "An internal server error occurred. This indicates an unexpected\ - \ failure in the Genestack system, please file a bug report to support@genestack.com,\ - \ including the error details." - security: - - Access-token: [] - - Genestack-API-Token: [] - summary: Retrieve run objects related to the given group - tags: - - Variant SPoT as User - /api/v1/as-user/variants/{id}: - get: - operationId: getVariantAsUser - parameters: - - description: Supply this parameter with the value `term_id` as part of the - query to return extended information including IDs for values and dictionaries. - in: query - name: responseFormat - schema: - $ref: "#/components/schemas/ResponseFormat" - - description: Variant object unique identifier (itemId). - in: path - name: id - required: true - schema: - type: string - - description: |- - The parameter defines amount of metadata attributes to return: - - 1. `minimal_data` - return metadata attributes according to the default template. - 2. `extended_data_included` - return metadata attributes according to applied template, if object doesn’t have applied template, default template will be used. This is the default for User endpoints. - 3. `original_data_included` - return all metadata attributes with values and null attributes, if they are present in the applied template. This is the default for Curator endpoints. - in: query - name: returnedMetadataFields - schema: - enum: - - minimal_data - - extended_data_included - - original_data_included - type: string - responses: - "200": - content: - application/json: - schema: - $ref: "#/components/schemas/VariantItem" - description: The request was successful. The returned value is the object. - "400": - content: {} - description: The supplied object ID is invalid. - "401": - content: {} - description: |- - User is not authenticated. Please supply a valid Access Token in the `Authorization` HTTP header (e.g. Authorization: bearer [token]) - or Genestack API token in the `Genestack-API-Token` header (this token may be obtained from the Genestack UI _Profile_ page). - "404": - content: {} - description: No object exists with the given ID. - "500": - content: {} - description: "An internal server error occurred. This indicates an unexpected\ - \ failure in the Genestack system, please file a bug report to support@genestack.com,\ - \ including the error details." - security: - - Access-token: [] - - Genestack-API-Token: [] - summary: Retrieve a single variant object by ID (itemId) - tags: - - Variant SPoT as User - /api/v1/as-user/variants/{id}/versions: - get: - operationId: getVariantVersionsAsUser - parameters: - - description: Variant object run ID (runId). - in: path - name: id - required: true - schema: - type: string - responses: - "200": - content: - application/json: - schema: - items: - $ref: "#/components/schemas/CommitInfo" - type: array - description: The request was successful. The returned value is the list - of object versions. - "401": - content: {} - description: |- - User is not authenticated. Please supply a valid Access Token in the `Authorization` HTTP header (e.g. Authorization: bearer [token]) - or Genestack API token in the `Genestack-API-Token` header (this token may be obtained from the Genestack UI _Profile_ page). - "500": - content: {} - description: "An internal server error occurred. This indicates an unexpected\ - \ failure in the Genestack system, please file a bug report to support@genestack.com,\ - \ including the error details." - security: - - Access-token: [] - - Genestack-API-Token: [] - summary: Retrieve a list of variant object versions by run ID (runId) - tags: - - Variant SPoT as User - /api/v1/as-user/variants/{id}/versions/{version}: - get: - operationId: getVariantByVersionAsUser - parameters: - - description: Supply this parameter with the value `term_id` as part of the - query to return extended information including IDs for values and dictionaries. - in: query - name: responseFormat - schema: - $ref: "#/components/schemas/ResponseFormat" - - description: Variant object run ID (runId). - in: path - name: id - required: true - schema: - type: string - - description: Unique version of the variant object. - in: path - name: version - required: true - schema: - type: string - - description: |- - The parameter defines amount of metadata attributes to return: - - 1. `minimal_data` - return metadata attributes according to the default template. - 2. `extended_data_included` - return metadata attributes according to applied template, if object doesn’t have applied template, default template will be used. This is the default for User endpoints. - 3. `original_data_included` - return all metadata attributes with values and null attributes, if they are present in the applied template. This is the default for Curator endpoints. - in: query - name: returnedMetadataFields - schema: - enum: - - minimal_data - - extended_data_included - - original_data_included - type: string - responses: - "200": - content: - application/json: - schema: - $ref: "#/components/schemas/SignalRun" - description: The request was successful. The returned value is the object. - "400": - content: {} - description: The supplied object ID is invalid. - "401": - content: {} - description: |- - User is not authenticated. Please supply a valid Access Token in the `Authorization` HTTP header (e.g. Authorization: bearer [token]) - or Genestack API token in the `Genestack-API-Token` header (this token may be obtained from the Genestack UI _Profile_ page). - "404": - content: {} - description: No object exists with the given ID. - "500": - content: {} - description: "An internal server error occurred. This indicates an unexpected\ - \ failure in the Genestack system, please file a bug report to support@genestack.com,\ - \ including the error details." - security: - - Access-token: [] - - Genestack-API-Token: [] - summary: Retrieve a single variant object by run ID and its version - tags: - - Variant SPoT as User -components: - schemas: - CommitInfo: - $ref: "./schemas/common/CommitInfo.yaml" - IntegrationHelper: - $ref: "./schemas/common/IntegrationHelper.yaml" - ListResponse: - $ref: "./schemas/common/ListResponse.yaml" - MetaResponse: - $ref: "./schemas/common/MetaResponse.yaml" - MetadataContent: - $ref: "./schemas/common/MetadataContent.yaml" - VariantMetadataWithId: - $ref: "./schemas/variant/VariantMetadataWithId.yaml" - PaginationInfo: - $ref: "./schemas/common/PaginationInfo.yaml" - ResponseFormat: - $ref: "./schemas/common/ResponseFormat.yaml" - RunFilter: - $ref: "./schemas/common/RunFilter.yaml" - RunsResponse: - $ref: "./schemas/common/RunsResponse.yaml" - SignalRun: - $ref: "./schemas/common/SignalRun.yaml" - VariantItem: - $ref: "./schemas/variant/VariantItem.yaml" - VariantResponse: - $ref: "./schemas/variant/VariantResponse.yaml" - securitySchemes: - Access-token: - in: header - name: Authorization - type: apiKey - Genestack-API-Token: - in: header - name: Genestack-API-Token - type: apiKey diff --git a/openapi/v1/variantCurator.yaml b/openapi/v1/variant{Role}.yaml similarity index 96% rename from openapi/v1/variantCurator.yaml rename to openapi/v1/variant{Role}.yaml index aa51ae7c..75a4fde2 100644 --- a/openapi/v1/variantCurator.yaml +++ b/openapi/v1/variant{Role}.yaml @@ -1,7 +1,7 @@ openapi: 3.1.0 info: description: |- - This swagger page describes the variantCurator APIs. + This swagger page describes the variant{Role} API endpoints for ODM. These are typically used to find and retrieve variant data and metadata. Before carrying out any API calls you will need an API token. API tokens can be obtained under your profile within the Genestack software. @@ -16,9 +16,9 @@ info: title: ODM API version: default-released tags: -- name: Variant SPoT as Curator +- name: Variant SPoT as {Role} paths: - /api/v1/as-curator/variants: + /api/v1/as-{role}/variants: get: description: |+ Retrieve all variant data and metadata objects that match a query. @@ -47,7 +47,7 @@ paths: ## Paging For performance reasons this endpoint returns results in "pages" of limited size together with a `cursor` tag. To retrieve the next page of results please supply this `cursor` tag to resume the query from your previous result and get the next page. If there are no more results you will just retrieve an empty result. - operationId: getAllVariantsAsCurator + operationId: getAllVariantsAs{Role} parameters: - description: Supply this parameter with the value `term_id` as part of the query to return extended information including IDs for values and dictionaries. @@ -208,8 +208,8 @@ paths: - Genestack-API-Token: [] summary: Retrieve multiple variant data and metadata objects tags: - - Variant SPoT as Curator - /api/v1/as-curator/variants/group: + - Variant SPoT as {Role} + /api/v1/as-{role}/variants/group: get: description: |- Retrieve all group metadata objects that match a query. @@ -241,7 +241,7 @@ paths: ## List operation This endpoint can be called with no `query` parameter. Doing so returns a list of all data objects. - operationId: searchGroupsAsCurator + operationId: searchGroupsAs{Role} parameters: - description: Supply this parameter with the value `term_id` as part of the query to return extended information including IDs for values and dictionaries. @@ -340,10 +340,10 @@ paths: - Genestack-API-Token: [] summary: Retrieve groups that match a query tags: - - Variant SPoT as Curator - /api/v1/as-curator/variants/group/by/run/{id}: + - Variant SPoT as {Role} + /api/v1/as-{role}/variants/group/by/run/{id}: get: - operationId: getVariantGroupByRunAsCurator + operationId: getVariantGroupByRunAs{Role} parameters: - description: Supply this parameter with the value `term_id` as part of the query to return extended information including IDs for values and dictionaries. @@ -399,10 +399,10 @@ paths: - Genestack-API-Token: [] summary: Retrieve a single group object by run ID (runId) tags: - - Variant SPoT as Curator - /api/v1/as-curator/variants/group/{id}: + - Variant SPoT as {Role} + /api/v1/as-{role}/variants/group/{id}: get: - operationId: getVariantGroupAsCurator + operationId: getVariantGroupAs{Role} parameters: - description: Supply this parameter with the value `term_id` as part of the query to return extended information including IDs for values and dictionaries. @@ -458,14 +458,14 @@ paths: - Genestack-API-Token: [] summary: Retrieve a single variant group by ID (groupId) tags: - - Variant SPoT as Curator - /api/v1/as-curator/variants/runs/by/group/{id}: + - Variant SPoT as {Role} + /api/v1/as-{role}/variants/runs/by/group/{id}: get: description: |+ ## Paging For performance reasons this endpoint returns results in "pages" of limited size together with a `cursor` tag. To retrieve the next page of results please supply this `cursor` tag to resume the query from your previous result and get the next page. If there are no more results you will just retrieve an empty result. - operationId: searchVariantRunsAsCurator + operationId: searchVariantRunsAs{Role} parameters: - description: Unique identifier (accession) of the object. in: path @@ -513,10 +513,10 @@ paths: - Genestack-API-Token: [] summary: Retrieve run objects related to the given group tags: - - Variant SPoT as Curator - /api/v1/as-curator/variants/{id}: + - Variant SPoT as {Role} + /api/v1/as-{role}/variants/{id}: get: - operationId: getVariantAsCurator + operationId: getVariantAs{Role} parameters: - description: Supply this parameter with the value `term_id` as part of the query to return extended information including IDs for values and dictionaries. @@ -572,10 +572,10 @@ paths: - Genestack-API-Token: [] summary: Retrieve a single variant object by ID (itemId) tags: - - Variant SPoT as Curator - /api/v1/as-curator/variants/{id}/versions: + - Variant SPoT as {Role} + /api/v1/as-{role}/variants/{id}/versions: get: - operationId: getVariantVersionsAsCurator + operationId: getVariantVersionsAs{Role} parameters: - description: Variant object run ID (runId). in: path @@ -608,10 +608,10 @@ paths: - Genestack-API-Token: [] summary: Retrieve a list of variant object versions by run ID (runId) tags: - - Variant SPoT as Curator - /api/v1/as-curator/variants/{id}/versions/{version}: + - Variant SPoT as {Role} + /api/v1/as-{role}/variants/{id}/versions/{version}: get: - operationId: getVariantByVersionAsCurator + operationId: getVariantByVersionAs{Role} parameters: - description: Supply this parameter with the value `term_id` as part of the query to return extended information including IDs for values and dictionaries. @@ -673,7 +673,7 @@ paths: - Genestack-API-Token: [] summary: Retrieve a single variant object by run ID and its version tags: - - Variant SPoT as Curator + - Variant SPoT as {Role} components: schemas: CommitInfo: From 44e2e2513d2dd5953789aa64a9d87dea6bbfaa7f Mon Sep 17 00:00:00 2001 From: oleg parkhomenko Date: Sat, 15 Nov 2025 00:47:53 +0400 Subject: [PATCH 5/9] fix some inconsistencies --- openapi/v1/integration{Role}.yaml | 8 +++++--- openapi/v1/variant{Role}.yaml | 2 +- 2 files changed, 6 insertions(+), 4 deletions(-) diff --git a/openapi/v1/integration{Role}.yaml b/openapi/v1/integration{Role}.yaml index 8bd78d36..0209e37a 100644 --- a/openapi/v1/integration{Role}.yaml +++ b/openapi/v1/integration{Role}.yaml @@ -3727,7 +3727,8 @@ paths: - Genestack-API-Token: [] summary: Retrieve study metadata by querying attachment file ID (accession) tags: - - Study integration as User + - Study integration as {Role} +##{Role=User} /api/v1/as-user/integration/fulltext/search/studies: post: description: |- @@ -3782,7 +3783,8 @@ paths: tags: - Study integration as User x-codegen-request-body-name: request - /api/v1/as-user/integration/link/variant/by/sample/{id}: +## end {Role=User} + /api/v1/as-{role}/integration/link/variant/by/sample/{id}: get: description: |+ ## Versioning @@ -3961,7 +3963,7 @@ paths: tags: - Variant integration as {Role} ##{Role=Curator} - api/v1/as-curator/integration/link/variant/group/{sourceId}/to/sample/group/{targetId}: + /api/v1/as-curator/integration/link/variant/group/{sourceId}/to/sample/group/{targetId}: delete: description: Delete link between a group of variant objects and a group of sample objects diff --git a/openapi/v1/variant{Role}.yaml b/openapi/v1/variant{Role}.yaml index 75a4fde2..8a449ef6 100644 --- a/openapi/v1/variant{Role}.yaml +++ b/openapi/v1/variant{Role}.yaml @@ -241,7 +241,7 @@ paths: ## List operation This endpoint can be called with no `query` parameter. Doing so returns a list of all data objects. - operationId: searchGroupsAs{Role} + operationId: searchVariantGroupsAs{Role} parameters: - description: Supply this parameter with the value `term_id` as part of the query to return extended information including IDs for values and dictionaries. From 9a810e3597ac5bd3a963a4697ffaacd376085362 Mon Sep 17 00:00:00 2001 From: oleg parkhomenko Date: Sat, 15 Nov 2025 00:55:45 +0400 Subject: [PATCH 6/9] fix spaces + minor --- .../main/kotlin/com/genestack/openapi/TemplateSpecification.kt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/buildSrc/src/main/kotlin/com/genestack/openapi/TemplateSpecification.kt b/buildSrc/src/main/kotlin/com/genestack/openapi/TemplateSpecification.kt index c167fea3..f0e09219 100644 --- a/buildSrc/src/main/kotlin/com/genestack/openapi/TemplateSpecification.kt +++ b/buildSrc/src/main/kotlin/com/genestack/openapi/TemplateSpecification.kt @@ -94,7 +94,7 @@ abstract class TemplateSpecification : DefaultTask() { val commentRole = lineCommentMatch.groupValues[1] if (commentRole == role) { // Keep the line but remove the comment - val processedLine = line.replace(lineCommentPattern, "") + val processedLine = line.replace(lineCommentPattern, "").trimEnd() outputContent.appendLine(processedLine) } // If role doesn't match, skip this line From 766480a4f103f00575c849fd0d06edf351182888 Mon Sep 17 00:00:00 2001 From: oleg parkhomenko Date: Sat, 15 Nov 2025 00:56:02 +0400 Subject: [PATCH 7/9] fix minor --- openapi/v1/integration{Role}.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/openapi/v1/integration{Role}.yaml b/openapi/v1/integration{Role}.yaml index 0209e37a..662be21e 100644 --- a/openapi/v1/integration{Role}.yaml +++ b/openapi/v1/integration{Role}.yaml @@ -4267,7 +4267,7 @@ paths: - Study integration as Curator x-codegen-request-body-name: request ## end {Role=Curator} - /api/v1/as-curator/links: + /api/v1/as-{role}/links: ## {Role=Curator} delete: description: "This method should be used in case you want to delete the links\ From 9dac71a195718dae1bf8467a1f70fd727ed1cf94 Mon Sep 17 00:00:00 2001 From: oleg parkhomenko Date: Sat, 15 Nov 2025 03:16:22 +0400 Subject: [PATCH 8/9] fix dir lookup --- build.gradle.kts | 13 +++---------- .../genestack/openapi/MergeSpecifications.kt | 12 ++++++------ .../genestack/openapi/TemplateSpecification.kt | 17 +++++++++-------- 3 files changed, 18 insertions(+), 24 deletions(-) diff --git a/build.gradle.kts b/build.gradle.kts index a78bc486..3d5803be 100644 --- a/build.gradle.kts +++ b/build.gradle.kts @@ -28,19 +28,12 @@ val openApiVersion: String = System.getenv("OPENAPI_VERSION") val mergedFileName = "odmApi.yaml" val mergedFilePath = "${sourceDirectory}/${mergedFileName}" -fun specFiles(selectTemplates: Boolean = false) = KotlinPath(sourceDirectory) - .listDirectoryEntries("*.yaml") - .filter { (!selectTemplates).xor(it.name.contains("{Role}")) } - .sorted() - .map { layout.projectDirectory.file("${sourceDirectory}/${it.name}") } - tasks { val templateSpecs by registering(TemplateSpecification::class) { - inputFiles = specFiles(true) + inputDir = layout.projectDirectory.file(sourceDirectory) outputDir = layout.projectDirectory.file(sourceDirectory) } val downloadSpec by registering(DownloadSpecification::class) { - dependsOn(templateSpecs) version.set(processorsControllerVersion) registryUsername.set(System.getenv("NEXUS_USER")) registryPassword.set(System.getenv("NEXUS_PASSWORD")) @@ -49,8 +42,8 @@ tasks { outputFile.set(layout.projectDirectory.file(processorsControllerFilePath)) } val mergeSpecifications by registering(MergeSpecifications::class) { - dependsOn(downloadSpec) - inputFiles = specFiles() + dependsOn(templateSpecs, downloadSpec) + inputDir = layout.projectDirectory.file(sourceDirectory) outputFile = layout.projectDirectory.file(mergedFilePath) } val generateOdmApiPython by registering(GenerateTask::class) { diff --git a/buildSrc/src/main/kotlin/com/genestack/openapi/MergeSpecifications.kt b/buildSrc/src/main/kotlin/com/genestack/openapi/MergeSpecifications.kt index cfe54e15..57a40eb9 100644 --- a/buildSrc/src/main/kotlin/com/genestack/openapi/MergeSpecifications.kt +++ b/buildSrc/src/main/kotlin/com/genestack/openapi/MergeSpecifications.kt @@ -6,7 +6,7 @@ import org.gradle.api.file.RegularFileProperty import org.gradle.api.provider.ListProperty import org.gradle.api.tasks.OutputFile import org.gradle.api.tasks.TaskAction -import org.gradle.api.tasks.InputFiles +import org.gradle.api.tasks.InputDirectory import com.fasterxml.jackson.databind.ObjectMapper import com.fasterxml.jackson.dataformat.yaml.YAMLFactory @@ -14,8 +14,8 @@ import com.fasterxml.jackson.dataformat.yaml.YAMLFactory abstract class MergeSpecifications : DefaultTask() { - @get:InputFiles - abstract val inputFiles: ListProperty + @get:InputDirectory + abstract val inputDir: RegularFileProperty @get:OutputFile abstract val outputFile: RegularFileProperty @@ -23,9 +23,9 @@ abstract class MergeSpecifications : DefaultTask() { @TaskAction fun merge() { val objectMapper = ObjectMapper(YAMLFactory()) - val mergedNode = inputFiles - .get().map { it.asFile } - .filterNot { it == outputFile.get().asFile } + val mergedNode = inputDir.get().asFile.listFiles { file -> + !file.name.contains("{Role}") && file.name.endsWith(".yaml") + }.sorted() .map { objectMapper.readTree(it) } .reduce { acc, node -> objectMapper.updateValue(acc, node) } objectMapper.writeValue(outputFile.get().asFile, mergedNode) diff --git a/buildSrc/src/main/kotlin/com/genestack/openapi/TemplateSpecification.kt b/buildSrc/src/main/kotlin/com/genestack/openapi/TemplateSpecification.kt index f0e09219..7f8d1459 100644 --- a/buildSrc/src/main/kotlin/com/genestack/openapi/TemplateSpecification.kt +++ b/buildSrc/src/main/kotlin/com/genestack/openapi/TemplateSpecification.kt @@ -6,7 +6,7 @@ import org.gradle.api.file.RegularFileProperty import org.gradle.api.provider.ListProperty import org.gradle.api.tasks.OutputFile import org.gradle.api.tasks.TaskAction -import org.gradle.api.tasks.InputFiles +import org.gradle.api.tasks.InputDirectory import org.gradle.api.tasks.OutputDirectory import java.io.File @@ -16,19 +16,20 @@ import com.fasterxml.jackson.dataformat.yaml.YAMLFactory abstract class TemplateSpecification : DefaultTask() { - @get:InputFiles - abstract val inputFiles: ListProperty + @get:InputDirectory + abstract val inputDir: RegularFileProperty @get:OutputDirectory abstract val outputDir: RegularFileProperty @TaskAction fun template() { - inputFiles.get().map { it.asFile } - .forEach { - writeTemplated(it, "User") - writeTemplated(it, "Curator") - } + inputDir.get().asFile.listFiles { file -> + file.name.contains("{Role}") && file.name.endsWith(".yaml") + }.forEach { + writeTemplated(it, "User") + writeTemplated(it, "Curator") + } } private fun writeTemplated(spec: File, role: String) { From 0bea86f9e7dde6267c56b3f04260357ce1e16f58 Mon Sep 17 00:00:00 2001 From: oleg parkhomenko Date: Sun, 16 Nov 2025 03:28:38 +0400 Subject: [PATCH 9/9] fix task dependency --- build.gradle.kts | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/build.gradle.kts b/build.gradle.kts index 3d5803be..73c088f4 100644 --- a/build.gradle.kts +++ b/build.gradle.kts @@ -34,6 +34,7 @@ tasks { outputDir = layout.projectDirectory.file(sourceDirectory) } val downloadSpec by registering(DownloadSpecification::class) { + dependsOn(templateSpecs) version.set(processorsControllerVersion) registryUsername.set(System.getenv("NEXUS_USER")) registryPassword.set(System.getenv("NEXUS_PASSWORD")) @@ -42,7 +43,7 @@ tasks { outputFile.set(layout.projectDirectory.file(processorsControllerFilePath)) } val mergeSpecifications by registering(MergeSpecifications::class) { - dependsOn(templateSpecs, downloadSpec) + dependsOn(downloadSpec) inputDir = layout.projectDirectory.file(sourceDirectory) outputFile = layout.projectDirectory.file(mergedFilePath) }