Merge pull request #168 from TranslatorSRI/deprecate-reverse-lookup

We've had a lot of users getting confused because a CURIE that works in NodeNorm doesn't work in NameLookup -- this is because NameLookup's `/reverse_lookup` endpoint doesn't do any normalization. This PR deprecates those endpoints (while leaving them around), and adds new `/synonyms` endpoints, which explicitly call them `preferred_curies` and has a note in the description to indicate that NodeNorm should be used to get these. `/synonyms` isn't quite accurate, because really this endpoint returns all the information we have on that CURIE, including the suffix, taxon information and so on. But the obvious correct name (`/lookup`) is already in use for NameLookup's text search function.

Closes #136.

api/server.py

@@ -100,22 +100,33 @@ class Request(BaseModel):
     """Reverse-lookup request body."""
     curies: List[str]
 
+class SynonymsRequest(BaseModel):
+    """ Synonyms search request body. """
+    preferred_curies: List[str]
 
 @app.get(
     "/reverse_lookup",
     summary="Look up synonyms for a CURIE.",
     description="Returns a list of synonyms for a particular CURIE.",
     response_model=Dict[str, Dict],
     tags=["lookup"],
+    deprecated=True,
+)
+@app.get(
+    "/synonyms",
+    summary="Look up synonyms for a CURIE.",
+    description="Returns a list of synonyms for a particular preferred CURIE. You can normalize a CURIE to a preferred CURIE using NodeNorm.",
+    response_model=Dict[str, Dict],
+    tags=["lookup"],
 )
 async def lookup_names_get(
-        curies: List[str]= Query(
+        preferred_curies: List[str]= Query(
             example=["MONDO:0005737", "MONDO:0009757"],
             description="A list of CURIEs to look up synonyms for."
         )
 ) -> Dict[str, Dict]:
     """Returns a list of synonyms for a particular CURIE."""
-    return await reverse_lookup(curies)
+    return await reverse_lookup(preferred_curies)
 
 
 @app.post(
@@ -124,16 +135,33 @@ async def lookup_names_get(
     description="Returns a list of synonyms for a particular CURIE.",
     response_model=Dict[str, Dict],
     tags=["lookup"],
+    deprecated=True,
 )
 async def lookup_names_post(
         request: Request = Body(..., example={
             "curies": ["MONDO:0005737", "MONDO:0009757"],
         }),
-) -> Dict[str, List[str]]:
+) -> Dict[str, Dict]:
     """Returns a list of synonyms for a particular CURIE."""
     return await reverse_lookup(request.curies)
 
 
+@app.post(
+    "/synonyms",
+    summary="Look up synonyms for a CURIE.",
+    description="Returns a list of synonyms for a particular preferred CURIE. You can normalize a CURIE to a preferred CURIE using NodeNorm.",
+    response_model=Dict[str, Dict],
+    tags=["lookup"],
+)
+async def lookup_names_post(
+        request: SynonymsRequest = Body(..., example={
+            "preferred_curies": ["MONDO:0005737", "MONDO:0009757"],
+        }),
+) -> Dict[str, Dict]:
+    """Returns a list of synonyms for a particular CURIE."""
+    return await reverse_lookup(request.preferred_curies)
+
+
 async def reverse_lookup(curies) -> Dict[str, Dict]:
     """Returns a list of synonyms for a particular CURIE."""
     query = f"http://{SOLR_HOST}:{SOLR_PORT}/solr/name_lookup/select"

tests/test_service.py

@@ -128,3 +128,37 @@ def test_autocomplete():
     assert syns[1]["label"] == 'Alzheimer disease 6'
     assert syns[1]["types"][0] == "biolink:Disease"
 
+
+def test_synonyms():
+    """
+    Test the /synonyms endpoints -- these are used to look up all the information we know about a preferred CURIE.
+    """
+    client = TestClient(app)
+    response = client.get("/synonyms", params={'preferred_curies': ['CHEBI:74925', 'NONE:1234', 'MONDO:0000828']})
+
+    results = response.json()
+    chebi_74925_results = results['CHEBI:74925']
+    assert chebi_74925_results['curie'] == 'CHEBI:74925'
+    assert chebi_74925_results['preferred_name'] == 'BACE1 inhibitor'
+
+    none_1234_results = results['NONE:1234']
+    assert none_1234_results == {}
+
+    mondo_0000828_results = results['MONDO:0000828']
+    assert mondo_0000828_results['curie'] == 'MONDO:0000828'
+    assert mondo_0000828_results['preferred_name'] == 'juvenile-onset Parkinson disease'
+
+    response = client.post("/synonyms", json={'preferred_curies': ['MONDO:0000828', 'NONE:1234', 'CHEBI:74925']})
+
+    results = response.json()
+    chebi_74925_results = results['CHEBI:74925']
+    assert chebi_74925_results['curie'] == 'CHEBI:74925'
+    assert chebi_74925_results['preferred_name'] == 'BACE1 inhibitor'
+
+    none_1234_results = results['NONE:1234']
+    assert none_1234_results == {}
+
+    mondo_0000828_results = results['MONDO:0000828']
+    assert mondo_0000828_results['curie'] == 'MONDO:0000828'
+    assert mondo_0000828_results['preferred_name'] == 'juvenile-onset Parkinson disease'
+