This chapter describes an overview of the DIVArchive Web Services API. See Chapter 1 for an overview of DIVA Enterprise Connect, the platform, and release compatibility.
The DIVArchive Web Services API has both SOAP and REST implementations. The SOAP and REST APIs are both based on XML, and have similar parameter names and data types. To understand how to effectively use the DIVArchive Web Services API, it is useful to first understand some conventions employed by both the SOAP and REST implementations.
Every DIVArchive Web Services API request contains a sessionCode parameter, which must contain a valid and active session code. The session code is passed as content in the payload of the HTTP request, not in the HTTP request header. You can establish a session using the registerClient() call. A successful registerClient() response contains a new sessionCode. You can issue the following REST call to create a session:
curl -v -X POST \ -H "Content-Type: application/xml" \ --data \ '<p:registerClient xmlns:p="http://interaction.api.ws.diva.fpdigital.com/xsd"> <p:appName>MediaDatabase2</p:appName> <p:locName>USWest2</p:locName> <p:processId>5828</p:processId> </p:registerClient>' \ http://127.0.0.1:9443/diva/service/rest/2.2/DIVArchiveWS_REST/registerClient
All sessions expire after a certain period (the default is 30 minutes). The DIVArchive Web Services configuration file has two timeout parameters. The divas.service.session.maxAge parameter determines the maximum total age of a session (in seconds) before it is terminated. The divas.service.session.maxIdle parameter determines how long a session can be idle before being terminated. Oracle recommends that you set these two parameters to the same value.
When a session is no longer valid, it is the client application's responsibility to create another session by calling registerClient() again.
The Content-Type parameter is required for all service requests. The Content-Type parameter is an HTTP header field that identifies the type of content being sent. You must specify text/xml as the Content-Type to invoke the services using XML input. If you want to pass parameters using REST form parameters, specify a Content-Type of application/x-www-form-urlencoded.
The character set for all input parameters should be encoded using UTF-8. Appending charset: UTF-8 to the Content-Type is optional.
The returned parameters are in XML format, encoded using the UTF-8 character set. The services do not support XML returned in alternate character sets, for example, iso-8859-1.
Most DIVArchive Web Services API request parameters are required to be present in the API request. Very few parameters are optional in the XML schema (for both SOAP and REST). However, some required parameters can be empty or nil. These parameters are identified as nillable in the XSDs that are referenced in the WSDL. Some parameters have defaults that are applied when no value is provided. For example, if the priority parameter is passed as nil, the system uses the default specified in the DIVArchive configuration. If the filePathRoot is not supplied, some requests use the default stored in the archived object.
To pass an empty or nil value for String parameters, the client can pass an empty string as follows:
<filePathRoot></filePathRoot>
However, this technique is not valid for numeric values. You must use the nil attribute to pass an empty numeric value. The following example passes an empty priority value:
<priorityLevel xsi:nil="true" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"/>
You can omit the namespace declaration previously described if the namespace is declared at the top of the XML.
You can use -1 as the value for some parameters; the -1 indicates that the value is not specified. Parameters that accept -1 include priorityLevel and instanceID. Check the documentation if you choose to use this method.
Other parameters in the API contain entire data structures that are optional. You may be able to omit these sections in their entirety in the request, because the sections may not apply, depending the request. These parameters and sections are identified in the XSDs with minOccurs=0.
The order that you specify the XML parameters in both SOAP and REST requests is important. You must use the parameter order defined in the WSDL or wsTest scripts. However, the order of REST form parameters is not important.
The DIVArchive Web Services API is configured to require basic authentication by default. You create the API users using the Key Generator tool. The Key Generator generates a client ID and authentication key, and then stores the user information in the configured WebLogic directory.
API clients must pass the credentials (the client ID and authentication key) in the standard Basic authentication format to have service calls properly authenticated. Both SOAP and REST are authenticated using the same approach; passing the basic authentication credentials in an HTTP header. The following is an example of a REST service invocation with credentials supplied:
curl -v -X POST \ -H "Content-Type: application/x-www-form-urlencoded" \ -u "4926d1cc-4f92-3b9c-d421-f958a60a832b:k89kcQWPbDES/tX10ged" \ --data sessionCode=35c3f814-cbe8-421c-ac07-9209709c960c&requestNumber=1678 \ https://127.0.0.1:9444/diva/service/rest/2.2/DIVArchiveWS_REST/cancelRequest
In the previous call, the cURL -u parameter provides basic authentication information in the format user_name:password. The authentication information is encoded by the cURL utility before it is actually transmitted.
DIVArchive Web Services requires that the client ID and authentication key credentials be passed on every Web Service call, including the registerClient() call and WSDL document requests. The sessionCode does not appear in the HTTP header; it is present in the body of the HTTP request.
The DIVArchive SOAP web services are based on SOAP version 1.1 (Simple Object Access Protocol), a standardized way of structuring XML messages. SOAP messages have a structure composed of an envelope, a header, and body section. The interface of SOAP version 1.1 services is specified in a WSDL document (Web Services Description Language). The WSDL document is a standard way of programmatically describing a set of web services.
The WSDL describes the available services (request messages), the response messages for those services, and the data flowing on those messages. A WSDL in turn can refer to zero or more XSD (XML Schema Definition) documents. These provide detailed descriptions of the specific input parameters, output parameters, and data types present in the services.
To access or view the WSDL document for the 2.2 Web Services, access the following URL in a web browser (substituting the correct network address, or port, or both):
http://127.0.0.1:9443/diva/service/soap/2.2/DIVArchiveWS_SOAP?WSDL
If you use a web browser, you will likely need to supply a username and password to access the WSDL. Pass the client ID as the username, and the authentication key as the password. You can also access the individual XSD documents using the following URLs (the XSD documents are numbered in the WSDL document):
http://127.0.0.1:9443/diva/service/soap/2.2/DIVArchiveWS_SOAP?xsd=1
The advantage of a WSDL document is that clients can download it, and use it to generate client-side code. The code takes care of parsing and generating XML messages, and facilitates programmatic access to the services. Many software development environments have tools to generate client-side code from the WSDL. The following link shows how to generate a simple Web Service client from a WSDL document using JAX-WS (a standard Oracle Java Web Services library):
https://docs.oracle.com/cd/E17802_01/webservices/webservices/docs/2.0/tutorial/doc/JAXWS3.html
Then following link describes how to generate Java artifacts for using standard Oracle Java SE 8 tools:
https://docs.oracle.com/javase/8/docs/technotes/tools/unix/wsimport.html
The DIVArchive Web Services accept SOAP request messages sent using HTTP, with POST as the request method. The content of these messages are in XML SOAP format. The service endpoint is the URL used in the POST. The actual Web Service name (method name) is not specified in the URL; it is specified in the XML request. You must specify text/xml as the Content-Type to invoke the services. If you are generating client-side code using the WSDL, it is likely that this step is performed for you. The following is an example of a simple SOAP HTTP request issued to DIVArchive Web Services:
curl -v -X POST \
-H "Content-Type: text/xml" \
-u "4926d1cc-4f92-3b9c-d421-f958a60a832b:k89kcQWPbDES/tX10ged" \
--data \
'<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:p="http://interaction.api.ws.diva.fpdigital.com/xsd"
<soapenv:Header/>
<soapenv:Body>
<p:cancelRequest>
<p:sessionCode>35c3f814-cbe8-421c-ac07-9209709c960c</p:sessionCode> \
<p:requestNumber>1678</p:requestNumber>\
</p:cancelRequest>
</soapenv:Body>
</soapenv:Envelope>' \
http://127.0.0.1:9443/diva/service/soap/2.2/DIVArchiveWS_SOAP \
There are two main ways errors are handled in the DIVArchive SOAP services:
For fundamental errors such as authentication issues, XML message formatting issues, and some validation-related issues, the DIVArchive SOAP Web Services generates a SOAP Fault. A SOAP fault is an XML block returned as a response to a request. The structure of the fault is detailed in the WSDL document. Clients using libraries to generate code against the WSDL often have the ability to have a client-side exception generated (in the client's programming language) when a fault is returned as a response. If a request generates a SOAP fault, the HTTP return code will be HTTP code 500.
If the request is parsed correctly and sent to DIVArchive, the response may still contain an error. The request may reference an invalid object, or contain an illegal combination of parameters. In these cases, the DIVArchive SOAP Web Services return an architected DIVArchive API response that contains a DIVArchive API error code. The architected response for each request is documented in the reference chapters. The HTTP return code for these responses will be HTTP code 200. See Appendix A for the full list of DIVArchive API status codes.
DIVArchive REST (REpresentational State Transfer) services are similar to the DIVArchive SOAP services. You can invoke the REST services in two ways. The first method involves an HTTP POST with an XML-formatted request message. This message looks very much like the SOAP messages (minus the wrapping envelope and body tags). The second method of invocation involves passing input parameters using HTTP form parameters. In both methods, the URL contains the name of the method (for example, getArrayList).
Regardless of how the request is submitted, either an XML architected response message is returned (with a successful HTTP error code), or a response with a non-successful HTTP error code is returned. When an HTTP error code is returned, the body may have additional error text that can assist in diagnosing the issue.
The primary method of invoking a DIVArchive REST call is by submitting an XML request message as an HTTP POST to a request URL representing a DIVArchive API method. You specify text/xml as the Content-Type (application/xml is also accepted). The following example is a simple HTTP request issued to DIVArchive Web Services:
curl -v -X POST \ -H "Content-Type: application/xml" \ -u "4926d1cc-4f92-3b9c-d421-f958a60a832b:k89kcQWPbDES/tX10ged" \ --data \ '<p:cancelRequest xmlns:p="http://interaction.api.ws.diva.fpdigital.com/xsd"> <p:sessionCode>35c3f814-cbe8-421c-ac07-9209709c960c</p:sessionCode> <p:requestNumber>1678</p:requestNumber> </p:cancelRequest>' \ http://127.0.0.1:9443/diva/service/rest/2.2/DIVArchiveWS_REST/cancelRequest
The second way of invoking DIVArchive REST services involves supplying request parameters as form-encoded parameter and value pairs. The form-encoded parameters are sent as an HTTP POST request, using application/x-www-form-urlencoded as the Content-Type. The following is a sample cancel request that is invoked using form parameters:
curl -v -X POST \ -H "Content-Type: application/x-www-form-urlencoded" \ -u "4926d1cc-4f92-3b9c-d421-f958a60a832b:k89kcQWPbDES/tX10ged" \ --data sessionCode=35c3f814-cbe8-421c-ac07-9209709c960c&requestNumber=1678 \ http://127.0.0.1:9443/diva/service/rest/2.2/DIVArchiveWS_REST/cancelRequest
The information passed in the data section includes the requestNumber and the sessionCode. Each parameter value must be URL-encoded so it can be correctly parsed by the services. The information returned by all REST services is represented in XML format.
Form parameters cannot be used to invoke all services. The partialRestore(), associativeCopy(), and multipleRestoreObject() requests cannot be invoked this way because of the nested structure of the information required on the call. You can invoke all other requests using form parameters. Some requests may require repeated parameter names in the request. For example, you can invoke an archiveObject() request that has multiple file arguments by including a fileNamesList parameter for each file to be passed.
The response to a REST request contains either an architected response message in XML format (with a successful HTTP error code), or a response with a non-successful HTTP error code. When an HTTP error is returned, the body may have additional error text that can assist in diagnosing the issue.
For fundamental errors such as authentication issues, XML formatting issues, and server issues, the DIVArchive REST Web Services return a non-successful HTTP error code (a successful code is between 200 and 300). The following list identifies of some HTTP error codes that may appear in a non-successful request.
If 200 is returned, DIVArchive or DIVAnet has returned an architected response (see Architected Errors). The DIVArchive API status code in the response indicates the status of the call.
The request was invalid, due to an apparent client-side error. In some cases, DWS will be able to identify the error, and also return an architected response in the message body.
Authentication is required; credentials, session code, or both must be supplied.
Authentication was provided, but the credentials supplied did not grant access to the requested service or resource.
The URL is not found or is invalid.
The HTTP method (for example, GET, POST) is invalid for the request.
An error encountered on the server has caused the inability to satisfy the request. In some cases, the error can be identified and returned in an architected response in the message body.
For errors that are actually generated by DIVArchive, the DIVArchive REST Web Services return a DIVArchive API status code, and the architected responses identified in this document. If the HTTP return code is between 200 and 300, that does not necessarily indicate that the request was issued successfully. See Appendix A for a full list of DIVArchive API status codes.