SOAP WebServices

Database reference

The following E-R diagram shows the SOAP webservice configuration tables that allow to access to DSpace-CRIS data: accounts, access methods, filters, etc.

Architecture

The “Authentication” and “Authorization” customized modules  allow the administrator to manage access information.

Spring Web Services (Spring-WS) is provided by Spring community that is focused on creating document-driven Web services[1].

WSDL

A WSDL file is an XML document that describes a Web service. It specifies the location of the service and the operations (or methods) the service exposes. When creating Web services, there are two development styles: Contract Last and Contract First.

It was used Contract First because in Spring-WS it allows to start with WSDL definitions followed by Java code. Note that in Spring-WS, writing the WSDL by hand is not required. Based on the XSD and some conventions, Spring-WS may create the WSDL by itself.

Fragment of spring-ws-servlet.xml:

<bean id="wsdlforwsservices" class="…DynamicWsdl11Definition">
    <property name="builder">
    	<bean class="…XsdBasedSoap11Wsdl4jDefinitionBuilder">                           
				<property name="schema" value="<WEBINF>/crisrequestforwsdl.xsd" />
        	<property name="portTypeName" value="cris" />
        	<property name="locationUri" value="${dspace.url}/webservices/" />
    	    <property name="targetNamespace"
                           value="http://www.cilea.it/cris/definitions" />
   		</bean>
    </property>
</bean>

Point browser or a SOAP client like SoapUI (download from here ) to http://<dspace-webapp>/webservices/wsdlforwsservices.wsdl       

Spring-WS can generate WSDL for us based on XML Schema called crisrequestforwsdl.xsd. [m1] 

Others XML Schema imported on XML Schema for WSDL called requestresearcherpage.xsd and responseresearcherpage.xsd, requestresearchergrants.xsd and responseresearchergrant.xsd,  staticrequestpublications.xsd  and staticresponsepublicatins.xsd are not only your service contract but also are your data contract.[m2] 

Data contract (with request prefix on xsd file name) defines the message format to accept and the objects type to return (with response prefix).

In fact, at begin of WSDL, you can find import of those xsd, this is the contract for  request and response. [m3] Each simpleType of request contract defines object and field types to respond.

There are two schema related to WSDL:

• crisrequestforwsdl.xsd in the classpath is used to generate public  WSDL;
• crisrequest.xsd in the external folder is used to validate data request.

Note that crisrequestforwsdl.xsd and crisrequest.xsd have the same contents, they differ only by the initial imports.

<xs:simpleType name="ValueListPublications">
         <xs:restriction base="xs:string">
               <xs:enumeration value="search.resourceid" />
               <xs:enumeration value="dc.type" />
               <xs:enumeration value="dc.title" />
               ...              
               <xs:enumeration value="dc.contributor.author" />
         </xs:restriction>
    </xs:simpleType>

Validation is done on request call based on xsd. Note that for entities in the system  the xsd like for RP entity or GRANT entity will generate at system startup  and put them in  ws-xsd (configurated on dspace.cfg with key webservices.xsd.path) directory on dspace local directory. The only one to copy onto directory by hand is request contract and response contract for publications (you can find these in WEB-INF\classes directory onto webapp).

The service endpoints are managed by PayloadRootQNameEndpointMapping class provided by Spring Framework. 

This class maps SOAP request

"{http://www.cilea.it/cris/schemas}NormalAuthQueryRequest"

to

rpNormalEndpoint 

bean service and

"{http://www.cilea.it/cris/schemas}TokenAuthQueryRequest"

to rpTokenEndpoint bean service.

rpNormalEndpoint and rpTokenEndpoint first authenticate and authorize user, then manage request and build response to fulfill data contract.

Web Service User Management

The administration menu shows the “Web services” item through which the web service users may be managed.

It allows to create two kind of user authentication:

-          username/password

-          with a token and a range or single IP

It also allows to:

-          enable or disable users

-          enable or disable permissions

-          filter criteria (SOLR-like)

-          show values

  Objects managed appear in dspace.cfg:

##Web Services Configuration
webservices.criteria.type = publications, researcherPages, grants
webservices.criteria.type.publications = 2
webservices.criteria.type.researcherPages  = 9
webservices.criteria.type.grants  = 10

Note: to add new entity it is mandatory add new type in dspace.cfg and also manage XML Schema definition.

Web Service Test

SOAP UI allow to contact web services. Followed it is the SOAP XML document aka SOAP envelope[m6] . For further information see the code fragment comments.

Follows a token authentication request:

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:sch="http://www.cilea.it/researcherpage/schemas">
   <soapenv:Header/>
   <soapenv:Body>
      <sch:TokenAuthQueryRequest>
         <sch:Auth>
              <!-- the token -->
            <sch:Token>xsbcsdsdfsf-awe12-asdad</sch:Token>
         </sch:Auth>
         <sch:InfoQuery>
              <!-- the query -->
            <sch:Query>*:*</sch:Query>
              <!-- pagination -->    
            <sch:PaginationRows>20</sch:PaginationRows>
            <sch:PaginationStart>0</sch:PaginationStart>
            <sch:Projection>
               <!--You have a CHOICE of the next 3 items at this level-->
               <!-- CHOOSE only one and take the consistent type -->
               <!—if leave empty then the result depends on user profile->
               <sch:grantProjection>search.resourceid grant_keywords</sch:grantProjection>
            </sch:Projection>
            <sch:Type>
                 <!-- publication,researcherPages,grants are allowed -->
               <sch:type>grants</sch:type>
            </sch:Type>
         </sch:InfoQuery>
      </sch:TokenAuthQueryRequest>
   </soapenv:Body>
</soapenv:Envelope>

Server side, the token, get by SOAP messages, and the caller address IP, get by transport service aka HTTP, are validated. If validation is true then a query SOLR is builded in the follow manner:[m7] 

-          Getting query from SOAP message

-          Getting type and building a query (es. fq=search.resourcetype:2 where 2 stands for Item, 9 for RP and 10 for Grants)

-          Getting in the from User profile other queries

-          Shoot query on SOLR server (reminder: pagination is active)[m8] 

Follows a sample response: