Merge pull request #139 from x-atlas-consortia/jas_sources_update

New source_dictionary_url key/value in response to sources endpoint

dd-api-spec.yaml

@@ -1,14 +1,14 @@
 openapi: 3.0.3
 info:
   title: Data Distillery API
-  description: The Data Distillery API provides REST endpoints that return results from queries against an instance of [Data Distillery](https://github.com/TaylorResearchLab/CFDE_DataDistillery), which is a deployment of the [Unified Biomedical Knowledge Graph (UBKG)](https://ubkg.docs.xconsortia.org/). To prevent exceeding service timeouts or payload limits, some endpoints are throttled in both execution time and in the size of its response payload--e.g., to a maximum execution time of 15 seconds and a maximum payload of 9 MB. The Data Distillery API requires an API Key.
+  description: The Data Distillery API provides REST endpoints that return results from queries against an instance of [Data Distillery](https://github.com/TaylorResearchLab/CFDE_DataDistillery), which is a deployment of the [Unified Biomedical Knowledge Graph (UBKG)](https://ubkg.docs.xconsortia.org/). To prevent exceeding service timeouts or payload limits, some endpoints are throttled in both execution time and in the size of its response payload--e.g., to a maximum execution time of 15 seconds and a maximum payload of 9 MB. NOTE - The API requires an Authorization key in the request header in format "UMLS-Key[space][apikey]", where apikey is the API key for a UMLS licensee acount.
   version: "2.0"
   contact:
     name: GitHub repository
     url: https://github.com/TaylorResearchLab/CFDE_DataDistillery
 externalDocs:
   description: UBKG documentation
-  url: https://ubkg.docs.xconsortia.org/
+  url: https://ubkg.docs.xconsortia.org/api
 servers:
   - url: https://datadistillery.api.sennetconsortium.org/
     description: Production server
@@ -169,7 +169,7 @@ paths:
   /concepts/{concept_id}/nodeobjects:
     get:
       operationId: concepts_identifier_nodes_get
-      summary: Returns a set of "Concept Node objects" that "match" an identifier. [A Concept node in the UBKG is the origin of a subgraph that links the Concept node to a set of Code, Term, Definition, and Semantic Type nodes. A "Concept Node object" represents this subgraph as a set of Concept properties--i.e., all of the Concept's linked Codes, terms, definitions, and semantic types. A "match" is an exact match between an identifier and a text-based property in a Concept Node object. Because an identifier may match properties in more than one Concept Node object, the endpoint can return multiple Concept Node objects.]
+      summary: Returns a set of "Concept Node objects" (also known as concept subgraphs) that "match" an identifier. [A Concept node in the UBKG is the origin of a "concept subgraph" that links the Concept node to a set of Code, Term, Definition, and Semantic Type nodes. A "Concept Node object" represents this subgraph as a set of Concept properties--i.e., all of the Concept's linked Codes, terms, definitions, and semantic types. A "match" is an exact match between an identifier and a text-based property in a Concept Node object. Because an identifier may match properties in more than one Concept Node object, the endpoint can return multiple Concept Node objects.]
       parameters:
         - name: concept_id
           in: path
@@ -1558,6 +1558,10 @@ components:
                 items:
                   type: string
                   example: "https://obofoundry.org/ontology/doid.html"
+              source_dictionary_url:
+                type: string
+                description: URL to the section of the CFDE Data Distillery Data Dictionary for the source
+                example: https://github.com/nih-cfde/data-distillery/blob/main/DataDistilleryDataDictionary.md#the-library-of-integrated-network-based-cellular-signatures-lincs-dcc
               licenses:
                 type: array
                 description: applicable licenses or terms of use of the source specified by stewards

src/ubkg_api/cypher/sources.cypher

@@ -49,6 +49,15 @@ CALL
 	AND r.CUI = p.CUI
 	RETURN COLLECT(t.name) AS home_urls
 }
+// source dictionary url
+CALL
+{
+	WITH CUISource
+	MATCH (pSource:Concept)-[:has_source_dictionary_url]->(p:Concept)-[:CODE]->(c:Code)-[r:PT]->(t:Term)
+	WHERE pSource.CUI=CUISource
+	AND r.CUI = p.CUI
+	RETURN t.name AS source_dictionary_url
+}
 // citations as both PMID and URL
 CALL
 {
@@ -152,9 +161,9 @@ CALL
 	RETURN t.name AS context
 }
 
-WITH CUISource,sab,source_name,source_description, home_urls, citations,
+WITH CUISource,sab,source_name,source_description, source_dictionary_url,home_urls, citations,
 CASE WHEN source_etl_command IS NULL THEN source_etl_owl ELSE source_etl_command END as source_etl,
 source_version, source_type,source_download_date, COLLECT(DISTINCT CASE WHEN license_type is NULL THEN NULL ELSE {type: CASE WHEN license_definition IS NULL THEN license_type ELSE license_definition END,subtype:license_subtype,version:license_version} END) AS licenses, COLLECT(DISTINCT context) AS contexts
-WITH {sab:sab,name:source_name,description:source_description,home_urls:home_urls,citations:citations,source_etl:source_etl,source_version:source_version, source_type:source_type, download_date:source_download_date,licenses:licenses,contexts:contexts} AS source
+WITH {sab:sab,name:source_name,description:source_description,home_urls:home_urls,source_dictionary_url:source_dictionary_url,citations:citations,source_etl:source_etl,source_version:source_version, source_type:source_type, download_date:source_download_date,licenses:licenses,contexts:contexts} AS source
 WITH COLLECT(source) AS sources
 RETURN {sources:sources} AS response

tests/test_ubkg_api.sh

@@ -1085,7 +1085,7 @@ echo | tee -a test.out
 echo "1. sources GET => should return 200" | tee -a test.out
 curl --request GET \
  --url "${UBKG_URL}/sources" \
- --header "Accept: application/json" | tee -a test.out
+ --header "Accept: application/json" | cut -c1-60 | tee -a test.out
 echo | tee -a test.out
 echo | tee -a test.out
 

ubkg-api-spec.yaml

@@ -6,6 +6,9 @@ info:
   contact:
     name: GitHub repository
     url: https://github.com/x-atlas-consortia/ubkg-api
+externalDocs:
+  description: UBKG documentation
+  url: https://ubkg.docs.xconsortia.org/api
 servers:
   - url: https://ontology.api.hubmapconsortium.org
     description: Production server
@@ -164,7 +167,7 @@ paths:
   /concepts/{concept_id}/nodeobjects:
     get:
       operationId: concepts_identifier_nodes_get
-      summary: Returns a set of "Concept Node objects" that "match" an identifier. [A Concept node in the UBKG is the origin of a subgraph that links the Concept node to a set of Code, Term, Definition, and Semantic Type nodes. A "Concept Node object" represents this subgraph as a set of Concept properties--i.e., all of the Concept's linked Codes, terms, definitions, and semantic types. A "match" is an exact match between an identifier and a text-based property in a Concept Node object. Because an identifier may match properties in more than one Concept Node object, the endpoint can return multiple Concept Node objects.]
+      summary: Returns a set of "Concept Node objects" (also known as concept subgraphs) that "match" an identifier. [Each Concept node in the UBKG is the origin of a "concept subgraph" that links the Concept node to a set of Code, Term, Definition, and Semantic Type nodes. A "Concept Node object" represents this subgraph as a set of Concept properties--i.e., all of the Concept's linked Codes, terms, definitions, and semantic types. A "match" is an exact match between an identifier and a text-based property in a Concept Node object. Because an identifier may match properties in more than one Concept Node object, the endpoint can return multiple Concept Node objects.]
       parameters:
         - name: concept_id
           in: path
@@ -1545,6 +1548,10 @@ components:
                 items:
                   type: string
                   example: "https://obofoundry.org/ontology/doid.html"
+              source_dictionary_url:
+                type: string
+                description: URL to the section of the CFDE Data Distillery Data Dictionary for the source
+                example: https://github.com/nih-cfde/data-distillery/blob/main/DataDistilleryDataDictionary.md#the-library-of-integrated-network-based-cellular-signatures-lincs-dcc
               licenses:
                 type: array
                 description: applicable licenses or terms of use of the source specified by stewards