API Guide

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 (XST) parameters.

1.2 Service Method Example https://ws.example.com/XDocServerService.ashx?XM=Container.ContainerInfo&XSC=ABC&XST=

Internet Protocol HTTPS
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
    1. Parameters are passed in typical HTTP Get or Post protocol format.
    2. 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
    1. These methods typically have a data parameter, which is an XML payload that corresponds to a particular XML schema definition (XSD).
    2. 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

Parameter Type Required Sample Description
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.
    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”.