S1. Method Invocation Syntax
All Service Methods are invoked in a consistent manner using a simple HTTP get or post invocation as described below.
1.1. Service Method Invocation
- A single common HTTP endpoint is used for all Service Method invocations: XDocServerService.ashx
- The name of the Service Method is appended as query string parameter (
XM) to the base URL.
- Authentication and Access control is via Security Context (
XSC) and Security Token (
1.2 Service Method Example
|ws.mxvm.net||Web server DNS name|
|XM Parameter||Fully qualified service method in the format: ServiceName.MethodName|
|XSC Parameter||Security Context. See section 3.|
|XST Parameter||Security Token. See section 4.|
1.3. Method Request Parameter Handling
Passing parameters to Method calls is handled in the following ways.
- Methods with a small fixed set of parameters. For example: Container.ContainerInfo
- Parameters are passed in typical HTTP Get or Post protocol format.
- If the Method also has a Parameter that is a binary file transmission, HTTP Post is used, and the binary file is written directly to the Request Input Stream as binary bytes.
- Methods that have a complex XML payload. For example: Document.DocumentAddXml
- These methods typically have a data parameter, which is an XML payload that corresponds to a particular XML schema definition (XSD).
- The XML payload can be written directly to the Request Input Stream, or included as an HTML form field named either XwsData or XwsPayload.
1.4. Standard Method Request Parameters
|XM||String||Yes||The fully qualified method name in the format ServiceName.MethodName. E.g.: Container.ContainerInfo|
|XSC||String||Yes||ABC||Security Context. Used for simple verification that the invoking application is allowed to invoke the service. Must match the value defined by the Invocation Security Context option in the Project Settings → API Settings → HTTP Services configuration page.|
|XST||String||Security Token. Encrypted multi-valued data used for advanced authentication of the invoking application. See section 5 for specifications.|
|XDEBUG||Bool||1||Indicates if the Method should log debugging information. Set to “1” to turn debug on.|
|XEXTKEY||String||Tracking key sent by the invoking application. Returned back to the invoking application in the Response Headers, and the ServiceResponse xml node.|
|XEXTINFO||String||Additional tracking info sent by the calling application. Returned back to the invoking application in the Response Headers, and the ServiceResponse xml node.|
1.5. Method Response Data Handling
When invoking Service Methods, some Methods return XML wrapped results, and some methods utilize Direct Streaming of the result data directly to the Response Stream. Success or Failure is determined for each as follows:
- For all methods, you can check success by inspecting the HTTP Response Header: XwsSuccess . This allows high-volume service calls to be very efficient when the consumer does not care about inspecting the detailed Response Stream payload in the case of success.
- The following HTTP Response Headers are set for all Method invocations.
a Header Type Values Sample Description XwsSuccess Bool 0,1 1 “True” or “1” indicates the method was successful. “False” or “0” indicates failure. XwsRequestDate Date 2009-12-01T15:43:00Z UTC Timestamp when the Request was received. XwsRequestId String 2110110153110012080 Unique request id for transaction XwsResponseDate Date 2009-12-02T16:45:23Z UTC Timestamp when the Response was completed. XwsResultCode Int 0 0 for success or result code on failure.
- The following HTTP Response Headers may be conditionally set if errors exist, single value return data exists, or a value exists for the header.
Header Type Values Sample Description XwsResultInfo String Result info corresponding to the ResultCode. XwsResultInfoEx String Extended result info. Method specific. XwsReturnData String 20092342423482348 Simple return data field for simple methods XwsErrorCode Int 0 0 for success or error code on failure XwsErrorInfo String Error info corresponding to the Error Code XwsErrorInfoEx String Extended error info if needed XwsExternalKey String External key passed from the invoking application XwsExternalInfo String External info passed from the invoking application
- For XML wrapped method results, success can also be determined by inspecting the Success attribute of the
<ServiceResponse>envelope, where a value of “1” indicates success. This is functionally equivalent to the XwsSuccess Response Header.
- For Direct Streaming methods, success can also be determined by inspecting the HTTP Status Code to indicate success or failure. If Successful, the HTTP Status Code will be set to the standard OK value of 200. For errors, the Status Code will be set to a standard HTTP Status Error Code that most closely represents the actual Application error that occurred. E.g.: 404 for “object not found”. The HTTP error Status Codes used by the Service are shown in section 2 below.
- For Direct Stream Methods, the Response Content-Type headers will be set appropriately, thus allowing for “straight-through” stream writing to the calling application and subsequently to the Browser if required. For example, if the Container.DocumentDownload is invoked that returns the Faxed document in PDF format, the Response Content-Type will be set to “application/pdf”.