http://docs.openlinksw.com/virtuoso/webservices.html Web Services OpenLink Virtuoso Universal Server: Documentation virtuoso.docs@openlinksw.com virtuoso.docs@openlinksw.com 2009-11-16T14:26:59Z OpenLink Software Documentation Team http://docs.openlinksw.com/virtuoso/../images/misc/logo.jpg http://docs.openlinksw.com/virtuoso/soap.html virtuoso.docs@openlinksw.com virtuoso.docs@openlinksw.com SOAP 2009-11-16T14:26:59Z SOAP The Simple Object Access Protocol (SOAP) is a lightweight, extensible, XML-based application layer protocol for information exchange in a decentralized, distributed environment. SOAP defines a framework for message structures and a message processing model. SOAP also defines a set of encoding rules for serializing data and a convention for making remote procedure calls. The SOAP extensibility model provides a foundation for a wide range of composable modules and protocols. Although the most common way to transport SOAP messages is HTTP, it may also be run on top of other protocols. SOAP includes: http://docs.openlinksw.com/virtuoso/wsdl.html virtuoso.docs@openlinksw.com virtuoso.docs@openlinksw.com WSDL 2009-11-16T14:26:59Z WSDL The Web Services Description Language (WSDL) is a standard, structured way of describing SOAP messages and Web services. It is an XML format for describing the network services offered by a service provider. The provider will publish a WSDL file that contains details about the services provided, and the set of operations within each service that the provider supports. For each of the operations, the WSDL file also describes the format that the client must follow in requesting an operation. Since the WSDL file sets up requirements for both the provider and service requester, this file is like a contract between the two. The provider agrees to provide certain services if the client sends a properly formatted SOAP request. Suppose that we have a WSDL file defining a service called StockQuoteService. This service describes operations such as getTradePrice, getLowestTradePrice, and getHighestTradePrice. You place this WSDL file on the service provider server. A client who wishes to send a SOAP request to this server must first obtain a copy of the WSDL file from the provider, and then use it to format a suitable SOAP request. The client sends this request to the provider. The provider executes the requested operation and sends the results back to the client requester as a SOAP response. http://docs.openlinksw.com/virtuoso/vfoafssl.html virtuoso.docs@openlinksw.com virtuoso.docs@openlinksw.com FOAF+SSL Support 2009-11-16T14:26:59Z FOAF+SSL Support FOAF+SSL is an authentication and authorization protocol that links a "Web ID" or "Personal URI" to a public key to create a global, decentralized, distributed, and secure authentication system that functions with existing browsers. FOAF+SSL uses PKI standards - usually thought of as hierarchical trust management tools - in a decentralized web-of-trust way. The web of trust is built using semantic web vocabularies (particularly FOAF) published in RESTful manner to form Linked Data. Based on well known existing standards, FOAF+SSL is currently in development, and is being discussed on the FOAF protocols mailing list. http://docs.openlinksw.com/virtuoso/voauth.html virtuoso.docs@openlinksw.com virtuoso.docs@openlinksw.com OAuth Support 2009-11-16T14:26:59Z OAuth Support The OAuth protocol enables websites or applications (Consumers) to access Protected Resources from Web services (Service Providers) via an API, without requiring Users to disclose their Service Provider credentials to those Consumers. More generally, OAuth creates a freely-implementable and generic methodology for API-oriented authentication. For Consumer developers, OAuth is a method to publish and interact with protected data. For Service Provider developers, OAuth gives users access to their data while protecting their account credentials. http://docs.openlinksw.com/virtuoso/vwsssupport.html virtuoso.docs@openlinksw.com virtuoso.docs@openlinksw.com WS-Security (WSS) Support in Virtuoso SOAP Server 2009-11-16T14:26:59Z WS-Security (WSS) Support in Virtuoso SOAP Server The following terms are used in this section in the following meanings: The following algorithms are supported: Digest algorithms: http://docs.openlinksw.com/virtuoso/ws-routing.html virtuoso.docs@openlinksw.com virtuoso.docs@openlinksw.com Web Services Routing Protocol (WS-Routing) 2009-11-16T14:26:59Z Web Services Routing Protocol (WS-Routing) The SOAP Routing Protocol (WS-Routing) is a SOAP-based, stateless protocol for exchanging SOAP messages from an initial sender to an ultimate receiver, potentially via a set of intermediaries. The WS-Routing protocol is implemented as a SOAP extension, embedded in a SOAP Header entry. The WS-Routing implementation consists of SOAP Header processing. The header processing handler for the WS-Routing header determines if the Virtuoso SOAP server can act as an intermediary or a endpoint depending on the rules in message path. This implementation supports HTTP only. Message Id's generated are UUIDs. http://docs.openlinksw.com/virtuoso/warm.html virtuoso.docs@openlinksw.com virtuoso.docs@openlinksw.com Web Services Reliable Messaging Protocol (WS-ReliableMessaging) 2009-11-16T14:26:59Z Web Services Reliable Messaging Protocol (WS-ReliableMessaging) The WS-ReliableMessaging protocol is a SOAP-based RPC protocol for guaranteed delivery of messages; possibly in specific order from one sender to one receiver. Such messages are usual SOAP messages - XML documents conforming to the SOAP specification. The Sender is an alias of the transmission initiator, i.e. the originator of the message transfer. The Receiver is a recipient, that which accepts the messages. How accepted messages should be processed is not covered in this document.; What to do with the data and whether to send replies is at the discretion of the application. Further in this section for brevity WS-RM will be used in place of "Web Services Reliable Messaging Protocol". Delivery Assurances Types: http://docs.openlinksw.com/virtuoso/vwstrust.html virtuoso.docs@openlinksw.com virtuoso.docs@openlinksw.com Web Services Trust Protocol (WS-Trust) 2009-11-16T14:26:59Z Web Services Trust Protocol (WS-Trust) In order to secure communication between two parties, the two parties must exchange security credentials (either directly or indirectly). However, each party needs to determine if they can "trust" the asserted credentials of the other party. WS-Security defines the basic mechanisms for providing secure SOAP messaging. WS-Trust is an extension of WS-Security for security token exchange to enable the issuance and dissemination of credentials within different trust domains, and thus manage trust relationships. The goal of WS-Trust is to enable applications to construct trusted SOAP message exchanges. Using these extensions, applications can engage in secure communication designed to work with the general Web Services framework, including WSDL service descriptions, UDDI businessServices and bindingTemplates, and SOAP messages. WSS (WS-Security) enabled endpoint can make use of (WST) WS-Trust by exposing the "RequestSecurityToken" method. It then will check the WSS headers, decode if appropriate and pass the request parameters to the RequestSecurityToken method. http://docs.openlinksw.com/virtuoso/xmlxmla.html virtuoso.docs@openlinksw.com virtuoso.docs@openlinksw.com XML for Analysis Provider 2009-11-16T14:26:59Z XML for Analysis Provider XML for Analysis (XMLA) is a SOAP based XML API for data access interaction between a client application and a data provider working over the Web. The Virtuoso SOAP server can act as an XMLA data provider, also the Virtuoso SOAP client can be used as a client to talk with an XMLA data provider. The following terms: result-set and row-set will be used interchangeably to designate repeating content with identical structure. The mention of a result-set and row-set in this document is related to an SQL/ODBC result set which is represented as XML for use in XMLA. The implementation is based on the "XML for Analysis Specification v 1.0" by Microsoft Corp, found on the MSDN website. The Execute operation needs the properties Username and Password to be supplied in order to execute the statement on behalf of an SQL user account. If these are not supplied the request will be rejected with SOAP:Fault message. To prevent a network sniffer from catching the password in clear text, it is strongly recommended that sending of these properties be done via HTTPS (SSL/TLS) connection (for HTTPS setup see Web server section, and tutorials). The Virtuoso XMLA provider implements statelessness for the settable properties. This means that properties such as UserName and Password can be set in the beginning and they will be restored on server side on the next request ID for which they are not supplied. This mechanism is very similar to URL poisoning state support, which is described in the Web server section of the documentation. In short, the XMLA client asks to begin a session, the XMLA provider returns a session ID and from that point the client sends this ID to the server. If the client wishes, it may cancel the session with an end session request. http://docs.openlinksw.com/virtuoso/xmlrpc.html virtuoso.docs@openlinksw.com virtuoso.docs@openlinksw.com XML-RPC support 2009-11-16T14:26:59Z XML-RPC support The XML-RPC is a remote procedure calling system via HTTP using XML as the encoding. It is very much like the SOAP protocol, but the data encoding rules are different. XML-RPC supports fewer data types than SOAP. The data is self-describing and position bound. The Virtuoso SOAP server can process XML-RPC requests using the XML-RPC to SOAP bridge. This is done with two filters : input and output filter. The input filter transforms XML-RPC into a SOAP PRC encoded message. Then the transformed message is passed to the SOAP server for processing. The response from the SOAP server will be re-coded into XML-RPC format in the output filter. The combination of these filters constitutes the bridge. It is important to remember that XML-RPC defines two complex types : array and structure. These two types are represented by vector () and soap-structure respectively, when passing the data to the PL procedure in question. http://docs.openlinksw.com/virtuoso/syncml.html virtuoso.docs@openlinksw.com virtuoso.docs@openlinksw.com SyncML 2009-11-16T14:26:59Z SyncML SyncML is a protocol for synchronization of data collections between two devices - a SyncML Client and SyncML Server using an XML data representation. The client is typically some mobile device or mobile PC. The Virtuoso server implements the SyncML server protocol over HTTP. The SyncML server maintains the data collections within the WebDAV repository. The items (resources) in the collections (folders) represents items found on the client, e.g. VCARD, vcalendar records. As the WebDAV repository does not restrict the type of data that can be stored, likewise there are no restrictions on the type of data that can be synchronized. Also every WebDAV virtual directory can act as a SyncML server endpoint, the SyncML processing is triggered via the Content-Type, detected on the POST request (see below). The SyncML server detects the following formats from the Content-Type header string: http://docs.openlinksw.com/virtuoso/uddi.html virtuoso.docs@openlinksw.com virtuoso.docs@openlinksw.com UDDI 2009-11-16T14:26:59Z UDDI http://docs.openlinksw.com/virtuoso/expwsmodules.html virtuoso.docs@openlinksw.com virtuoso.docs@openlinksw.com Exposing Persistent Stored Modules as Web Services 2009-11-16T14:26:59Z Exposing Persistent Stored Modules as Web Services Virtuoso SQL stored procedures and functions can be exposed as SOAP services very simply from Virtuoso, whether they are native Virtuoso or on remote data sources. This powerful ability means that any database servers already existing within an organization can easily become a component in an eBusiness solution using Virtuoso. All you need is a few simple steps that typically take mere minutes to complete: XML Query Templates provide a direct way to store SQL in an XML file on the Virtuoso server that when executed, i.e. fetched from a web browser, actually returns the results of the query. The C Interface chapter describes how users can define custom built-in functions, from C or other programming languages, that can be used from within Virtuoso PL. This also means that VSE's can also be published as a Web Service! http://docs.openlinksw.com/virtuoso/vsmx.html virtuoso.docs@openlinksw.com virtuoso.docs@openlinksw.com Testing Web Published Web Services 2009-11-16T14:26:59Z Testing Web Published Web Services Virtuoso provides a mechanism for testing SOAP messages instantly. This mechanism is the Virtuoso Service Module for XML (VSMX) - an automatically generated test page for published web services. The VSMX file is generated at the same time the WSDL file is generated. A VSMX file is a SOAP operations test page generated based on the descriptions of a WSDL file. The VSMX file has the extension .vsmx, as opposed to the .wsdl extension of the WSDL file, and can be accessed similarly. VSMX pages give instant access to published SOAP services for testing. Any newly created service will need testing which normally means writing more code to call the service, supply parameters, retrieve the result, display the results in some manor, etc. The VSMX feature of Virtuoso eliminates this otherwise repetitive process by automatically maintaining a test page for SOAP messages: the VSMX file. This greatly speeds up the development and testing cycle. The beauty of this is that this is automated, even Microsoft's ASMX file requires that you code the services descriptions before seeing the results. Web Service developers would use VSMX to forego the test bed creation step in light of automatic test page generation. Project managers can easily keep track of their developers progress by checking the test page periodically. http://docs.openlinksw.com/virtuoso/bpel.html virtuoso.docs@openlinksw.com virtuoso.docs@openlinksw.com BPEL Reference 2009-11-16T14:26:59Z BPEL Reference Business Process Execution Language for Web Services (called BPEL4WS or simply BPEL in the rest of this chapter) provides a means of specifying interactions between web services for accomplishing a potentially long running business task. http://docs.openlinksw.com/virtuoso/xsql.html virtuoso.docs@openlinksw.com virtuoso.docs@openlinksw.com XSQL 2009-11-16T14:26:59Z XSQL XSQL is an XML-based format for describing simple stored procedures that can parse XML data, query or update database tables and compose XML output. Both input and output XMLs of such procedures are usually standard three-level documents: a top-level ROWSET element contains some number of ROW elements and every ROW contains one element per database field. XSQL lets the application developer avoid writing routine code for parsing and composing such documents: the server translates a short and self-evident XSQL description into a relatively long Virtuoso/PL procedure. XSQL pages are usually executed from XSLT stylesheets by calling processXSQL() XPATH function. When the page is executed, it can access an XML entity that is context entity of the processXSQL() call. This entity is used inside the page as an implicit parameter called "context XML". An XSQL document that describes one procedure is called "XSQL page". A page consists of small directives. Every directive is written as a single XML element from namespace "urn:oracle-xsql" (the typical namespace prefix is "xsql"). Every directive describes one standard operation. The resulting Virtuoso/PL procedure will execute all directives in turn. Directives are of four sorts: