From ef2b50239ec30addced43984ec85912c845bccce Mon Sep 17 00:00:00 2001 From: Gaurav Vaidya Date: Wed, 5 Nov 2025 16:51:47 -0500 Subject: [PATCH 1/2] Added more information to endpoint descriptions. --- node_normalizer/resources/openapi.yml | 33 +++++++++++++++++++-------- 1 file changed, 24 insertions(+), 9 deletions(-) diff --git a/node_normalizer/resources/openapi.yml b/node_normalizer/resources/openapi.yml index d24c386..e6acbe5 100644 --- a/node_normalizer/resources/openapi.yml +++ b/node_normalizer/resources/openapi.yml @@ -9,13 +9,16 @@ info: x-role: responsible developer description: 'Node Normalization takes a CURIE, and returns:
  1. The preferred CURIE for this entity
  2. All other known equivalent identifiers for the entity -
  3. Semantic types for the entity as defined by the BioLink +
  4. Semantic types for the entity as defined by the Biolink Model
The data served by Node Normalization is created by Babel, which attempts to find identifier equivalences, and makes sure that CURIE prefixes - are BioLink Model Compliant. To determine whether Node Normalization is likely + are BioLink Model Compliant. To determine whether Node Normalization is likely to be useful, check /get_semantic_types, which lists the BioLink semantic types for which normalization has been attempted, and /get_curie_prefixes, which lists - the number of times each prefix is used for a semantic type.' + the number of times each prefix is used for a semantic type. You can find out more about these API methods at the + Node Normalization API documentation. + To learn more about how Babel creates cliques of equivalent identifiers, you can + read its documentation.' license: name: MIT url: https://opensource.org/licenses/MIT @@ -43,7 +46,8 @@ tags: paths: /get_curie_prefixes: get: - description: Returns the curies and their hit count for a semantic type(s). + description: 'Returns the curies and their hit count for a semantic type(s). You can read more about this endpoint + in the NodeNorm API documentation.' parameters: - in: query name: semantic_type @@ -78,8 +82,9 @@ paths: - Interfaces /get_normalized_nodes: get: - description: Returns the equivalent identifiers and semantic types for the curie(s) - entered. + description: 'Returns the equivalent identifiers and semantic types for the curie(s) + entered. You can read more about this endpoint in the + NodeNorm API documentation. ' parameters: - in: query name: curie @@ -146,8 +151,9 @@ paths: - Interfaces /get_semantic_types: get: - description: Returns a distinct set of the semantic types discovered in the - compendium data. + description: 'Returns a distinct set of the semantic types discovered in the + compendium data. You can read more about this endpoint in the + NodeNorm API documentation.' responses: '200': content: @@ -167,7 +173,16 @@ paths: - Interfaces /get_allowed_conflations: get: - description: Returns a list of allowed conflation options + description: 'Returns a list of allowed conflation options. Conflation allows cliques to be combined on-the-fly + on the basis of two different criteria: +
    +
  1. GeneProtein conflation merges protein-coding genes with the proteins they encode. The gene(s) always + appear first in the combined clique. +
  2. DrugChemical conflation merges chemicals based on their active ingredient. We attempt to ensure that + the active ingredient appears before any formulations in the combined clique. +
+ You can read more about conflation or + more about this endpoint.' responses: '200': content: From 279e4e4cde1c90ca82184ee9eeba7cad30d580d8 Mon Sep 17 00:00:00 2001 From: Gaurav Vaidya Date: Wed, 5 Nov 2025 17:04:00 -0500 Subject: [PATCH 2/2] Added additional documentation. --- node_normalizer/resources/openapi.yml | 78 +++++++++++++++++++++++---- 1 file changed, 67 insertions(+), 11 deletions(-) diff --git a/node_normalizer/resources/openapi.yml b/node_normalizer/resources/openapi.yml index e6acbe5..f4fd975 100644 --- a/node_normalizer/resources/openapi.yml +++ b/node_normalizer/resources/openapi.yml @@ -44,6 +44,25 @@ tags: - name: Interfaces - name: trapi paths: + /status: + get: + description: 'Returns the status of the Node Normalization service. You can read more about this endpoint in the + NodeNorm API documentation.' + responses: + '200': + content: + application/json: + schema: + example: + status: running + babel_version: 2025mar31 + babel_version_url: https://github.com/TranslatorSRI/Babel/blob/master/releases/2025mar31.md + databases: + eq_id_to_id_db: + dbname: id-id + count: 677731045 + used_memory_rss_human: 68.83G + is_cluster: false /get_curie_prefixes: get: description: 'Returns the curies and their hit count for a semantic type(s). You can read more about this endpoint @@ -102,6 +121,9 @@ paths: schema: example: MESH:D014867: + id: + identifier: CHEBI:15377 + label: Water equivalent_identifiers: - identifier: CHEBI:15377 label: Water @@ -115,14 +137,17 @@ paths: - identifier: INCHIKEY:XLYOFNOQVPJJNP-UHFFFAOYSA-N - identifier: UNII:059QF0K00R - identifier: KEGG.COMPOUND:C00001 - id: - identifier: CHEBI:15377 - label: Water type: - - chemical_substance - - molecular_entity - - biological_entity - - named_thing + - biolink:SmallMolecule + - biolink:MolecularEntity + - biolink:ChemicalEntity + - biolink:PhysicalEssence + - biolink:ChemicalOrDrugOrTreatment + - biolink:ChemicalEntityOrGeneOrGeneProduct + - biolink:ChemicalEntityOrProteinOrPolypeptide + - biolink:NamedThing + - biolink:PhysicalEssenceOrOccurrent + information_content: 47.5 NCIT:C34373: equivalent_identifiers: - identifier: MONDO:0004976 @@ -139,10 +164,12 @@ paths: identifier: MONDO:0004976 label: amyotrophic lateral sclerosis type: - - disease - - disease_or_phenotypic_feature - - biological_entity - - named_thing + - biolink:Disease + - biolink:DiseaseorPhenotypicFeature + - biolink:BiologicalEntity + - biolink:ThingWithTaxon + - biolink:NamedThing + information_content: 74.9 type: object description: Results summary: Get the equivalent identifiers and semantic types for the curie(s) @@ -197,3 +224,32 @@ paths: summary: Return a list of named conflations. tags: - Interfaces + /get_setid: + get: + description: 'Returns the set ID for a given set of CURIEs. A set-id is an identifier that can be used to identify + this set of CURIEs going forward. It is currently impossible to recreate a set of CURIEs from a set-id, but the + same set of CURIEs given to the same version of Node Normalization will always return the same set-id. + You can read more about this endpoint in the + NodeNorm API documentation.' + responses: + '200': + description: Successful result + content: + application/json: + schema: + example: + curies: + - MESH:D014867 + - NCIT:C34373 + - UNII:63M8RYN44N + - RUBBISH:1234 + conflations: + - GeneProtein + - DrugChemical + error: null + normalized_curies: + - CHEBI:15377 + - MONDO:0004976 + - RUBBISH:1234 + normalized_string: "CHEBI:15377||MONDO:0004976||RUBBISH:1234" + setid: "uuid:771d3c09-9a8c-5c46-8b85-97f481a90d40" \ No newline at end of file