From ef2b50239ec30addced43984ec85912c845bccce Mon Sep 17 00:00:00 2001 From: Gaurav Vaidya Date: Wed, 5 Nov 2025 16:51:47 -0500 Subject: [PATCH 1/5] 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/5] 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 From b65bffc64df2e245324bf85c4d6aba7cfd880634 Mon Sep 17 00:00:00 2001 From: Gaurav Vaidya Date: Wed, 4 Feb 2026 17:40:39 -0500 Subject: [PATCH 3/5] Minor improvements. --- node_normalizer/resources/openapi.yml | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/node_normalizer/resources/openapi.yml b/node_normalizer/resources/openapi.yml index 43edecf..2dd9aa0 100644 --- a/node_normalizer/resources/openapi.yml +++ b/node_normalizer/resources/openapi.yml @@ -226,9 +226,9 @@ paths: - 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. + 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: @@ -252,4 +252,4 @@ paths: - 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 + setid: "uuid:771d3c09-9a8c-5c46-8b85-97f481a90d40" From ac226d4117ee8a9ee55d3536f44e61c9e636a3c3 Mon Sep 17 00:00:00 2001 From: Gaurav Vaidya Date: Wed, 4 Feb 2026 17:45:48 -0500 Subject: [PATCH 4/5] Updated get_curie_prefixes example output. --- node_normalizer/resources/openapi.yml | 50 ++++++++++++++++++++------- 1 file changed, 37 insertions(+), 13 deletions(-) diff --git a/node_normalizer/resources/openapi.yml b/node_normalizer/resources/openapi.yml index 2dd9aa0..8025272 100644 --- a/node_normalizer/resources/openapi.yml +++ b/node_normalizer/resources/openapi.yml @@ -72,8 +72,8 @@ paths: name: semantic_type schema: example: - - chemical_substance - - anatomical_entity + - biolink:ChemicalEntity + - biolink:AnatomicalEntity items: type: string type: array @@ -83,16 +83,36 @@ paths: application/json: schema: example: - anatomical_entity: + "biolink:ChemicalEntity": curie_prefix: - CHEBI: 1234, - UNICHEM: 4567, - etc.: the hit count - chemical_substance: + "PUBCHEM.COMPOUND": "123887334" + "INCHIKEY": "115975484" + "CAS": "4112274" + "HMDB": "217920" + "CHEMBL.COMPOUND": "2479770" + "UNII": "138975" + "CHEBI": "218762" + "MESH": "256235" + "UMLS": "603550" + "DrugCentral": "4995" + "GTOPDB": "13265" + "RXCUI": "124800" + "DRUGBANK": "15274" + "KEGG.COMPOUND": "16039" + "biolink:AnatomicalEntity": curie_prefix: - GO: 1234, - PUBCHEM: 4567, - etc.: a hit count + "UMLS": "159941", + "FMA": "98631", + "UBERON": "14564", + "ZFA": "606", + "NCIT": "10286", + "MESH": "1992", + "EMAPA": "966", + "FBbt": "117", + "WBbt": "18", + "GO": "4041", + "SNOMEDCT": "1422", + "CL": "3043" type: object description: Results summary: Return the number of times each CURIE prefix appears in an equivalent @@ -189,9 +209,13 @@ paths: example: semantic_types: types: - - cellular_component - - named_thing - - etc. + - biolink:ChemicalMixture + - biolink:MacromolecularMachineMixin + - biolink:GeographicLocation + - biolink:Agent + - biolink:Protein + - biolink:DiseaseOrPhenotypicFeature + - etc. type: object description: Results summary: Return a list of BioLink semantic types for which normalization has From 810e0206f217f4dace78c9b7e8c37aaad5ac40f2 Mon Sep 17 00:00:00 2001 From: Gaurav Vaidya Date: Wed, 4 Feb 2026 17:51:28 -0500 Subject: [PATCH 5/5] Improved documentation. --- node_normalizer/resources/openapi.yml | 10 +++++----- node_normalizer/server.py | 7 +++++-- 2 files changed, 10 insertions(+), 7 deletions(-) diff --git a/node_normalizer/resources/openapi.yml b/node_normalizer/resources/openapi.yml index 8025272..3afcd20 100644 --- a/node_normalizer/resources/openapi.yml +++ b/node_normalizer/resources/openapi.yml @@ -121,9 +121,10 @@ paths: - Interfaces /get_normalized_nodes: get: - 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. ' + description: 'Returns the equivalent identifiers and semantic types for the CURIEs entered. + You can optionally conflate identifiers if needed. + You can read more about this endpoint in the + NodeNorm API documentation.' parameters: - in: query name: curie @@ -192,8 +193,7 @@ paths: information_content: 74.9 type: object description: Results - summary: Get the equivalent identifiers and semantic types for the curie(s) - entered. + summary: Get the equivalent identifiers and semantic types for the CURIEs entered. tags: - Interfaces /get_semantic_types: diff --git a/node_normalizer/server.py b/node_normalizer/server.py index 42cc3a1..80c7faa 100644 --- a/node_normalizer/server.py +++ b/node_normalizer/server.py @@ -258,8 +258,11 @@ async def get_conflations() -> ConflationList: @app.get( "/get_normalized_nodes", - summary="Get the equivalent identifiers and semantic types for the curie(s) entered.", - description="Returns the equivalent identifiers and semantic types for the curie(s)", + summary="Get the equivalent identifiers and semantic types for the CURIEs entered.", + description="Returns the equivalent identifiers and semantic types for the CURIEs entered." + "You can optionally conflate identifiers if needed." + "You can read more about this endpoint in the " + "NodeNorm API documentation.", ) async def get_normalized_node_handler( curie: List[str] = fastapi.Query(