API Guide

S1. Service Invocation Syntax

Service Methods are invoked by XDOC using Simple HTTP URL endpoints as described below.

Method Invocation Each Service Method can have its own HTTP endpoint. Typically, most Services use a base URL endpoint for all Method invocations, with the name of the Method appended as either a query string parameter, or extra query information to the base URL. Configuration of the URL endpoints is done in the axSystemConfig.xml file, which is located at the root of the XDOC software installation.

For flexibility in supporting different URL syntaxes, XDOC allows each URL to contain substitution tokens representing the name of the Method that is being invoked, and the unique identifier of the object (Container) in the Integrated Application being queried.

XDOC parses each Method URL as follows.

• Reads the URL for the method form the XDOC configuration file.
• Replaces any corresponding Tokens in the URL if they exist.
• Appends any Method Specific Parameters to the Query String of the URL

For example, if using a single URL endpoint for all methods, you would construct your base URL to include a customer specific account code, which could then look as follows:

• http://yourapplication.com/xdoc/service/container/service.jsp?myCustCode=23123123

If you were using a RESTful style URL syntax, your GetContainer Method URL may look like:

• http://yourapplication.com/xdoc/service/container/$$container$$/

Method Request Parameter Passing XDOC can be configured to pass Parameters to each Method using the following:

• Query String parameters (HTTP Get). All parameters are passed on the query string.
• Form-Url-Encoded (Http Post). Parameters are url-encoded as name/value data and written directly to the Request Input Stream. The Request Content Type will be set to: application/x-www-form-urlencoded.
• XML Request. The parameters are wrapped in our standard node as outlined in Section 2, and written directly to the Request Input Stream. The Request Content Type will be set to: text/xml.

Method Response Data All Service Methods must return XML wrapped results. The XML is always wrapped in a common node as outlined in Section 2. Inside the ServiceReponse envelope is a ResponseData node that will vary based on the Method being invoked, and the corresponding XML Schema (XSD) for that return data.

XDOC always determines Success or Failure of the Method invocation by the following logic:

• Success is determined by inspecting the Success attribute of the ServiceResponse envelope, where a value of “1” indicates success.
• Note: The HTTP Status Code should always be set to the standard OK value of 200. XDOC will treat any other value as an error, regardless of the content of the Success attribute in the ServiceResponse node.