Introduction to API

In RESTful style, the XML data is sent in the body of the HTTP POST request. Only single calls, those which do not need data in the request, are using GET. Whether POST or GET is needed is specified for every function call in the following sections.

• If the function succeeds, the response of the request signals this by its HTTP return code. The return code 200 stands for a successful response. In this case, the response XML data, as described for each function, is returned in the HTTP response body.

• If the function fails or the user cancels, the service returns a HTTP code other than 200 and contains the following status response in the HTTP response body:

  CODE

  <?xml version="1.0"?>
  <status_response>
  	<result_id>-2</result_id>
  	<result_text>Cancel</result_text>
  </status_response>

  result_id is the numeric representation of the error.
  -1 signals a common or unspecific error.
  -2 stands always for a user cancel

Refer to the specific function description for further error codes. However, it is always advisable to check result_text for the error reason. This element returns a descriptive text of the failure.

In some low level errors, like HTTP protocol transmission failures, only an HTTP error code and no status_response XML may be returned in result_text.

In SOAP style, the XML data is sent as the request's only parameter. The WSDL defines the following input message for each function:

<message name="StandardRequest">
	<part name="RequestData" type="xsd:string"/>
</message>

The response, as output message is defined as:

<message name="StandardResponse">
	<part name="ResultId" type="xsd:int"/>
	<part name="ResultText" type="xsd:string"/>
	<part name="ResultData" type="xsd:string"/>
</message>

Again, this response is identical for each SOAP function (in SOAP terms: operation).

• If the function succeeds, the response signals this with ResultId 0. In this case, ResultData contains the function specific XML response data.
• If the function fails or the user cancels, ResultId is unequal 0. It actually corresponds to the result_id value as described in the RESTful style status response. ResultText contains a descriptive text for the error and corresponds to result_text in the RESTful way.

The WSDL for the SOAP interface may be retrieved by the URL http://localhost:54880/?wsdl (supposed the SDK is installed and running on the local machine and uses its default port 54880). Use this URL¹ to build a wrapper with your IDE.

¹ In most cases it is actually recommended to use the URL and not the downloaded WSDL (and its local file path) to generate the wrapper classes. The reason is that an object, instantiated from such a wrapper class may access the WSDL at runtime. But the file will not be present at the target system unless you ensure this. Java wrapper classes generated with wsimport.exe to be used with JAX-WS are an example for such WSDL accessing objects. For more information, see Use Nexus Card SDK with different programming languages.

The SDK's web service, the IDProductionService, is immediately running after installing the SDK. Entering the URL http://localhost:54880 in a web browser starts the service's web service interface². The service does not only act as SOAP and RESTful web service but it also offers a lean Web server that provides status information and development support.

The web interface offers basic Status information and a Components page which demonstrates the usage and test of the components. Especially for development purposes, the Development page offers the possibility to evaluate all SDK functions easily:

1. Enter XML data into the Request field of the page
2. Start the corresponding function.
3. See how the software behaves and returns its response XML.

However, the most convenient way is working with the Sample Request Templates which are directly provided by the service. The templates can be retrieved by the corresponding links in the Development page. You may modify the template XMLs to learn how the SDK behaves for different requests.

Using a HTTP logging tool like Fiddler (see Trace HTTP traffic) may even give you further support to evaluate the SDK. It allows you to inspect all sent and received data. The HTML page uses the RESTful interface. However, if you use SOAP with your application, this way to evaluate the SDK is helpful in the same way as the exchanged XML definitions are identical.

² For quick and frequent need to check the service's status and to access this interface, you can activate a Windows taskbar notification icon. You activate this icon in the SDK's Configuration Manager. When activated, the running service is shown as a blue gearwheel. For terminating the service you may use the context menu which opens on a right mouse click. Displaying the service's web interface is achieved by double-clicking the icon and following the Details link in the appearing dialog.

The web service methods are described in articles of their own.

Capturing

• ImageCapture - starts the capture dialog to capture an image.
• ImagePreview - creates a preview image.

Define cards (Non Managed Mode only)

• CardComposer - starts the CardComposer to edit a card definition.
• CardDesigner - starts the CardDesigner to edit a layout.
• EncodingConfigurator - starts the EncodingConfigurator to configure an encoding.

Define cards (Managed Mode only)

• CardDesigner starts the CardDesigner to manage card types.
• Cards - retrieves the list of card types.
• Fields - retrieves the list of fields.

Card production

• CardPreview - creates a card preview.
• CardJob - produces a card.

Administration

• ConfigManager - starts the Configuration Manager to configure SDK settings and devices.
• SystemStatus - retrieves the status of the SDK's components.