From NCBO Wiki

Overview

The NCBO UMLS REST Service have the ability to query all of UMLS with both CUIs and AUIs. These research services now support use of a CUI for all REST services that receive an identifier. Given that this is only an initial implementation, please consume them with that in mind.

To access any of the REST services, one must have the appropriate UMLS license code from NLM. Access to these REST services are strictly limited to those organizations with active licenses. Please do send your request to support@bioontology.org and indicate the following:

1. Your organization
2. Department
3. Area of interest
4. What kind of research where the REST services will be applied?
5. How did you learned about the UMLS REST Services?
6. Do you have an active valid UMLS license?

When accessing the UMLS REST Services, you will be challenged to enter your UMLS license code (case-sensitive). The NCBO UMLS REST services is now integrated with the the NLM UMLS License Server. Though, be wary that the NLM UMLS License Server is still currently under development, and thus may be down at various times.

The NCBO is developing the UMLS REST Services using an iterative software development approach. Thus, we welcome your feedback. If you have suggestions, please feel free email Benjamin Dai, the NCBO Chief Sofware Architect, at benjamin.dai@stanford.edu.

Web Service API

Notice that with the URL structure, switching between children, parent, and path REST service calls is as simple as changing one simple keyword. Similarly, changing a AUI call to a CUI call is as simple as swapping the identifier.

For clarity, I’ve listed all the UMLS services below with samples.

1) /umls - List all SABs (i.e., vocabularies) in UMLS - Tenatively, I’ve simply listed the SAB names. However, the data representation can easily accommodate meta-data for each SAB/vocabulary.

http://ncbolabs-nk2.stanford.edu:8080/umls

2) /umls/{SAB} – Get the root concept for the specified SAB

http://ncbolabs-nk2.stanford.edu:8080/umls/SNOMEDCT

http://ncbolabs-nk2.stanford.edu:8080/umls/ICD9CM

3) ./umls/concept/{SAB}/{AUI or CUI} – Get the concept in the specified SAB and with the specified AUI or CUI

http://ncbolabs-nk2.stanford.edu:8080/umls/SNOMEDCT/A3577576

http://ncbolabs-nk2.stanford.edu:8080/umls/SNOMEDCT/A3818834

http://ncbolabs-nk2.stanford.edu:8080/umls/SNOMEDCT/A2895444

http://ncbolabs-nk2.stanford.edu:8080/umls/SNOMEDCT/C0005388

http://ncbolabs-nk2.stanford.edu:8080/umls/SNOMEDCT/C1623497

4) ./umls/{SAB}/{AUI or CUI}/children – Get all children of the concept in the specified SAB and with the specified AUI or CUI

http://ncbolabs-nk2.stanford.edu:8080/umls/SNOMEDCT/A3684559/children

http://ncbolabs-nk2.stanford.edu:8080/umls/SNOMEDCT/A2895444/children

http://ncbolabs-nk2.stanford.edu:8080/umls/SNOMEDCT/C0037414/children

5) ./umls/{SAB}/{AUI or CUI}/parents – Get all parents of the concept in the specified SAB and with the specified AUI or CUI

http://ncbolabs-nk2.stanford.edu:8080/umls/SNOMEDCT/A3471356/parents

http://ncbolabs-nk2.stanford.edu:8080/umls/SNOMEDCT/A2895444/parents

http://ncbolabs-nk2.stanford.edu:8080/umls/SNOMEDCT/C0005388/parents

http://ncbolabs-nk2.stanford.edu:8080/umls/SNOMEDCT/C0037414/parents

6) ./umls/{SAB}/{AUI or CUI}/path – Get the parent concepts (AUIs) path to the root node for the concept in the specified SAB and with the specified AUI or CUI

http://ncbolabs-nk2.stanford.edu:8080/umls/SNOMEDCT/C0005388/path

http://ncbolabs-nk2.stanford.edu:8080/umls/SNOMEDCT/A3774012/path

http://ncbolabs-nk2.stanford.edu:8080/umls/SNOMEDCT/A10874433/path

7) ./umls/{SAB}/search/{Keyword} – Find all concepts in the specified SAB that contains the specified Keyword.

http://ncbolabs-nk2.stanford.edu:8080/umls/SNOMEDCT/search/bladder

8) ./umls/{SAB}/search/{Keyword}/{Start Index}/{Count} – Find all concepts in the specified SAB that contains the specified Keyword starting at result record Start Index with Count records returned.

http://ncbolabs-nk2.stanford.edu:8080/umls/SNOMEDCT/search/bladder/0/100

http://ncbolabs-nk2.stanford.edu:8080/umls/SNOMEDCT/search/liver/0/20

Things to Polish

There are number of practical things that require further attention. The list includes, but is not limited to, the following:

1. Conversion of search and subset parameters to be URL parameters instead of part of the URL structure (search and subset parameters are not part of the REST information model).
2. Implementation of standard HTTP error codes (e.g., for unknown resource request errors)
3. Ongoing adjustments to the SQL queries to improve accuracy. These UMLS REST Services are still considered research and require further fine-tuning and adjustments to validate accuracy.
4. Optimization of SQL queries
5. Search refactoring to improve response time and capability. A Lucense back-end implementation would serve the search REST services well.
6. Merging with ongoing NCBO UMLS research advancements.
7. Refactoring of security model.

Please do let us know if you have any feedback regarding these UMLS REST web services (support@bioontology.org).