API Guide

HTTP Server Services API

Product Info XDOC 5200
Last Update February 26, 2013

General Overview

This document provides an overview and reference for the XDOC Server Services. XDOC Server services utilize a simple HTTP protocol endpoint similar in concept to RESTful services. Service methods can be invoked with simple HTTP Get and Post methods without the SOAP overhead. This style of service has several advantages over Traditional Web Services including:

  • No SOAP or Web Service Client “stub” or “wrapper” is needed to invoke these services. Success or failure of a Method call is determined the same way for all method by inspecting the XDOC specific HTTP Response Headers, the envelope of the result XML, or the HTTP Status Codes if the Method utilizes Direct Streaming as described below.
  • Many Methods support Direct Streaming of the request data to the Request Input Stream, without the need for Base64 encoding. When using Methods that require binary document data to be passed to the Service, performance and scalability is increased, and invocation simplified.
  • Similarly, many Methods support Direct Streaming of the result data to the Response Output Stream. These include Methods used to retrieve document data (E.g. PDFs, TIFs, etc.) which write the data directly to the Response Stream. When using these direct streaming methods, there is significant performance and scalability advantages for both the XDOC Server, as well as the Invoking Application:
    • Since Binary return types such as PDF and TIF are written directly to the Response Stream, no Base64 encoding or decoding is needed on either end. This eliminates the processing overhead of the Base64 encoding / decoding, as well as decreases the overall size of the transmission by roughly 30%.
    • Streaming the document data to the Response Stream eliminates “Memory Spikes” in both the XDOC Server and the Invoking Application. For example, the document data can be streamed in chunks (E.g.: 16K) to the Invoking Application, which can in turn stream each chunk back to the end-user browser. During the entire method call, the XDOC Server and Invoking Application only use memory equivalent to a chunk.
    • Without this Streaming technique, consider a 1MB PDF file example. The Base64 encoding increases both the transmission size of the to approximately 1.4 MB, as well as drastically increases the memory utilization from 4K to 1.4MB per Method call. In high performance environments, this can have a substantial effect on the number of users or method calls that can be supported by each application server.

This document is divided into the following sections:

SECTION DESCRIPTION
S1 Method Invocation Syntax Specification for the syntax used to invoke Service Methods.
S2 Standard XML Schemas Listing of Standard XML payload schemas used across Service Methods.
S3 Security Context Identification Specifications for using a security context to identify the calling application / client.
S4 Security Token Authentication Specifications for using the encrypted security token to protect service invocation.
S5 Sample Code Sample Code showing invocation of Service Methods.