# Presentation: 204669

## NIF ComponentWeb Services

- William Bug, M.S., M.Phil.
- UCSD

## Web Services: what are they?

- Machine interface
- Communication & data exchange for Software components
- Evolution of pre-Web remote procedure calls (*RPC*)
- Component 1 ----(request)----> Component 2
- Component 2 ----(respond)----> Component 1
- Critical for constructing reusable infrastructural components
- Interoperability
- Enables distributed, federated infrastructure & component reuse
- Simplicity
- Hides complexity and provides uniform communication mechanism
- Expressivity
- implement component-specific Application Programming Interfaces (API) using simple & complex data types

## Web Services: what are they?

- Web
- Leverage ubiquity of web communication infrastructure
- HTTP
- Web Interfaces
- Humans have web browsers
- Software components have Web Services
- Richly defined APIs using
- common schema = Web Service Description Language (WSDL)
- ubiquitous extendable markup language = *XML*
- envelope structured messages = Simple Object Access Protocol (*SOAP)*
- Structured data exchange reduces cost to implement software interoperation
- Typically use common web TCP ports
- open web party line

## Web Services: what are they?

- Non-WSDL web-based software RPC
- HTTP query
- HTTP GET & HTTP POST
- Designed to send web browser HTML Form info to a server & receive results
- Used to SELECT or INSERT/UPDATE/DELETE records in a database
- Pros
- HTTP query is ubiquitous on the web
- an import method to exploit when mining web data repositories
- algorithms can bypass the form to use HTTP GET or POST directly
- Requires less sophisticated software engineering skills
- Cons
- Antiquated, less structured means to query web databases
- Not designed for low-cost, standard software component integration
- XML-based query
- Used by Neurogateway.org
- Client program assembles a query according to a defined vocabulary against a specified data schema (NIF BrainML registry schema)
- Nestled between WSDL & HTTP GET

## Web Services: why are they useful?

- Common, open TCP/IP ports
- Unlike other forms of inter-component communication uses open TCP ports typically not blocked by firewalls and processed by ubiquitous HTTP servers
- Unlike ODBC/JDBC/ADO, IIOP, DCOM+, Java RMI, etc.
- These binary formats are more efficient, but often more complex or time-consuming to create and maintain
- Structured data types
- Complex methods require complex data
- HTTP GET - everything is STRING-based key-value pairs
- HTTP POST - can do non-STRING, but not complex without a lot of coding
- WSDL
- all types from simple through complex are declared explicitly which makes WS application logic much easier to create and maintain
- inputs and outputs can be specified via a separate complex XML Schema
- Software frameworks in most languages (C/C++, Java, Python, Ruby, etc.) that can automatically translate native code objects to WSDL representation

## Web Services: why are they useful?

- WSDL-based automation
- Tools created to use WSDL much less costly for each programmer (service and client) creating or digested specific services
- Marshalling/Unmarshalling & Proxy code
- the complex set of heuristics used to translate native objects (variables and structures in C/C++, Java, Python, etc.) into a serialized form that can be sent over the wire via HTTP
- Unmarshalling is the inverse of this process
- Proxy objects handle this marshalling so remote methods appear local
- When using WSDL, service provider and client programmers do not have to write ANY marshalling or proxy code
- This is one of THE primary reasons earlier network-based RPC such as CORBA, IIOP, DCOM+ were costly and difficult to use.  Few developers competent using those standards, because they needed to implement some object translation.
- Marshalling/Proxies very error-prone and brittle (sensitive to change)
- WSDL frameworks come with auto-marshalling tools - e.g., given a WSDL, the Apache Axis WS framework tool WSDL-to-Java automatically creates the Java objects for you.
- Since WSDL frameworks handle the marshalling, component communication with WSDL is much more like non-network coding
*Network* *Effect *(in the marketing sense)

**Notes:**
Network effect = easier to use ===> more ubiquitous ===> more programmers using it ===> more impetus for servers to adopt ===>_x0003_more value to writing clients, since more services
     * also: more people who use it ===> more impetus to create tools that make WSDL easier to use

## Web Services: What do they look like?

- Component 1 ----(request)----> Component 2
- <?xml version="1.0" encoding="UTF-8"?>
- <SOAP-ENV:Envelope
-     xmlns:xsd="http://www.w3.org/2001/XMLSchema"
-     xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
-     xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/"
-     SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"
-     xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
-     <SOAP-ENV:Body>
-         <m:getTerm xmlns:m="http://mediator.nbirn.net:8080/axis/Ontology.jws">
-             <in0 xsi:type="xsd:string">Substantia nigra</in0>
-             <in1 xsi:type="xsd:boolean">true</in1>
-             <in2 xsi:type="xsd:string">NIFSTD</in2>
-         </m:getTerm>
-     </SOAP-ENV:Body>
- </SOAP-ENV:Envelope>

**Notes:**
Describe getTerm() method

## Web Services: What do they look like?

- Component 2 ----(repsonse)----> Component 1
- <?xml version="1.0" encoding="UTF-8"?>
- <soapenv:Envelope
-     xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
-     xmlns:xsd="http://www.w3.org/2001/XMLSchema"
-     xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
-     <soapenv:Body>
-         <ns1:getTermResponse
-             soapenv:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"
-             xmlns:ns1="http://mediator.nbirn.net:8080/axis/Ontology.jws">
-             <getTermReturn xsi:type="xsd:string">
-                 <bioterm>
-                     <termSet>
-                         <term unique__id="birnlex_782" name="Predominantly gray regional part of substantia nigra" ontology="NIFSTD" definition="(null)"/>
-                         <term unique__id="birnlex_775" name="Regional part of substantia nigra" ontology="NIFSTD" definition="(null)"/>
-                         <term unique__id="birnlex_978" name="Regional part of substantia nigra pars reticulata" ontology="NIFSTD" definition="(null)"/>
-                         <term unique__id="sao34994437" name="Substantia Nigra Dopaminergic Cell" ontology="NIFSTD" definition="(null)"/>
-                         <term unique__id="birnlex_789" name="Substantia nigra" ontology="NIFSTD" definition="Predominantly gray matter midbrain structure lying dorsal to the crus cerebri and ventral to the midbrain tegmentum.  It is divided into a dorsal, cellularly compact region known as the pars compacta and a more ventrally located, containing more loosely packed cells, the pars reticulata.  The most lateral region of the reticulata is identified as the pars lateralis (MM)."/>
-                         <term unique__id="nifext_145" name="Substantia nigra dopaminergic cell" ontology="NIFSTD" definition="(null)"/>
-                         <term unique__id="birnlex_990" name="Substantia nigra pars compacta" ontology="NIFSTD" definition="Regional part of substantia nigra consisting of a densely packed region of cells, more or less dorsal to the pars reticulata, but extending into the pars reticulata in some species.  The dominant neurotransmitter used by pars compacta neurons is dopamine.  Pars compacta neurons are pigmented in many species (MM)."/>
-                         <term unique__id="nifext_15" name="Substantia nigra pars laminaris" ontology="NIFSTD" definition="(null)"/>
-                         <term unique__id="birnlex_866" name="Substantia nigra pars lateralis" ontology="NIFSTD" definition="Regional part of substantia nigra consisting of loosely packed cells, generally located ventral and lateral to the pars compacta.  Many cells in this region use GABA as a neurotransmitter (MM)."/>
-                         <term unique__id="birnlex_968" name="Substantia nigra pars reticulata" ontology="NIFSTD" definition="Regional part of substantia nigra consisting of loosely packed cells, generally located ventral and lateral to the pars compacta.  Many cells in this region use GABA as a neurotransmitter (MM)."/>
-                     </termSet>
-                 </bioterm>
-             </getTermReturn>
-         </ns1:getTermResponse>
-     </soapenv:Body>
- </soapenv:Envelope>

**Notes:**
Describe getTermReturn() response body
	• mention Bioterm XSD
	• describe term return

## NIF II Web Service Interfaces

- Bonfire

- Mediator Query

- Rsrc Registry

- TextPresso

- Term Index Srvc

- Neuroscientist
- UIs

- Term Index
- Source

- Mediator Registry

**Notes:**
Centrality of BONFIRE terminology server
Registry, TextPresso, Mediator - all map NIFSTD terms in their respective data sources
TIS - registering data sources for level 3 mediation
NOTE: some infrastructural components interact via web services as well

## Web API for NIF data access

- Bonfire

- Rsrc Registry

- TextPresso

**Notes:**
Centrality of BONFIRE terminology server
Registry, TextPresso, Mediator - all map NIFSTD terms in their respective data sources
TIS - registering data sources for level 3 mediation

## NIF Web Services

- BONFIRE
- _[http://mediator.nbirn.net:8080/axis/Ontology.jws?wsdl](http://mediator.nbirn.net:8080/axis/Ontology.jws?wsdl)_
- TextPresso
- http://dev.textpresso.org/wsdl/textpresso.wsdl
- NIF Resource Registry
- http://neurogateway.org/catalog/queryXMLExec.do
- Mediator Query
- _[http://mediator.nbirn.net:8080/axis/Registry.jws?wsdl](http://mediator.nbirn.net:8080/axis/Registry.jws?wsdl)_
- Mediator Source Dtb Registry
- _[http://mediator.nbirn.net:8080/axis/Registry.jws?wsdl](http://mediator.nbirn.net:8080/axis/Registry.jws?wsdl)_
- Term Index Service
- _[http://mediator.nbirn.net:8080/axis/TIS.jws?wsdl](http://mediator.nbirn.net:8080/axis/TIS.jws?wsdl)_

## NIF Terminology Server WS (BONFIRE)

*Access*
- _[http://mediator.nbirn.net:8080/axis/Ontology.jws?wsdl](http://mediator.nbirn.net:8080/axis/Ontology.jws?wsdl)_
- Methods
- getSourcesByTerm(*probeTerm*)
- Probe all source ontologies/terminologies for term - return source Id
- getConceptByTerm(*probeTerm, useSynonyms, ontologyId*)
- Probe ontology for term - return ID, prefLabel, & definition if found
- getSynonyms(*conceptID, ontologyID*)
- Return synonyms for a prefLabel in a given knowledge source
- showConceptProperties(*conceptID*)
- Return variety of annotation properties for a given concept in NIFSTD
- Concept graph exploration
- findNeighbor(*conceptId*)
- findShortestPath(*conceptId1, conceptId2*)
- findDescendents(*conceptId, relationType, maxLevel*)

**Notes:**
NOTE: these are examplars - not ALL methods in WSDL

## NIF TextPresso Search WS

*Access*
- http://dev.textpresso.org/wsdl/textpresso.wsdl
- Methods
- textpressoWebService(*keywords, fields, categories, search_scope, search_mode, exact_match, case_sensitive*)
- Fields = citation fields - e.g., abstract, title, etc.
- Categories = coarse-level concepts
- Search scope = document **|** field **|** sentence
- Search mode = Boolean **|** latent theme **| **vector

**Notes:**
NOTE: these are examplars - not ALL methods in WSDL

## NIF Resource Repository WS

*Access*
- http://neurogateway.org/catalog/queryXMLExec.do
- Methods
- queryXMLExec
- Client code creates an instance of BrainML that is customized to the NIF registry fields

**Notes:**
NOTE: these are examplars - not ALL methods in WSDL

## NIF Level3 Mediator (BIRN Mediator) WS

*Access*
- http://mediator.nbirn.net:8080/axis/Mediator.jws?wsdl
- Methods
- runQuery(*query*)
- Query specified in Mediator Query XML Schema
- Response specified in Mediator Query Response XML Schema

**Notes:**
NOTE: these are examplars - not ALL methods in WSDL

## BIRN Mediator Registry WS

*Access*
- http://mediator.nbirn.net:8080/axis/Registry.jws?wsdl
- Methods
- getRegistryData()
- getNewDataSources(*fromDate, toDate*)
- getAllSources(*sourceNameWildcard*)
- returns list of all registered sources
- getAllTablesFields(*sourceNameWildcard*)
- getAllViews(*viewNameWildcard*)
- getAllFields4View(*viewNameWildcard*)
- getFields4SourceTable (*sourceName*, *tableName*)
- getFields4View(*ivdName*)
- returns SQL DDL like description of source structures

**Notes:**
Lists register sources
Lists SQL DDL like descriptions of sources

## BIRN Term Index Source WS

*Access*
- http://mediator.nbirn.net:8080/axis/TIS.jws?wsdl
- Methods
- getTISdata()
- returns all Term Index Source data in multi-record format: ontology id, relation name, field name and type
- searchDataSourceByConceptID(*conceptIdList*)
- searchDataSourceByConceptName(*conceptNameList*)

**Notes:**
NOTE: these are examplars - not ALL methods in WSDL

## NIF Web Services Team

*Implementation*
- Vocabulary Server & Term Index Source (TIS)
- Brian Sanders, UCSD
- NIF Resource Repository
- Adrian Robert, Ajit Jagdale, & Eliza Chan, Cornell
- TextPresso
- Arun Rangarajun & Hans-Michael Muller, Cal Tech
- BIRN Mediator Query & Mediator Registry
- Vadim Astakhov, UCSD
*Testing*
- Luis Marenco & Yuli Li, Yale
- Xufie Qian, UCSD
*Design*
- Architecuture:
- Jeff Grethe, Amarnath Gupta, & Bill Bug, UCSD
- Individual Components:
- implementers listed above

## NIF Web Service Future

*Use of  web services to update NIFSTD lexically-enhanced ontology*
- WS connections to NLM/NCBI
- NCBI Entrez Gene, Homologene, Unigene
- Currently running as stand-alone program (alpha)
- NLM MeSH Browser (HTTP API)
- Pending
- MyNIF Alerts
*Auto-run saved searches*
*Not in current contract - but is very much compatible with current infrastructure*
*Question:*
- Would this be set up as an email service, web-based portal, RSS?

## FINIS

- Thank you