Introduction to API

This article includes updates for Nexus Card SDK 6.4.

The SDK's interface is a web service offering a SOAP as well as a RESTful interface. All requests are available in both ways. This makes the service actually acting as a kind of "Hybrid" web service.

SOAP is typically recommended to be used with high level programming languages like C# or within in a J2EE application. An integrated development environment (IDE) will usually automatically build wrapper classes from the SDK's WSDL. For more information see Use Nexus Card SDK with different programming languages.

REST may be used as a lean and easy interface with languages like JavaScript (with its XML-HttpRequest object) or even with C (with Window'sWinINet functions like HttpSendRequest).

The choice, SOAP or REST, may also depend on your knowledge or on your personal preference. However, independent of using SOAP or REST, the web service offers a basically identical communication style: Each SDK function request receives its data as XML and returns its response as XML.

These basic rules regarding the request XMLs applies for all web service functions:

Response XML = Sent XML + Enriched data: The returned XML corresponds to the sent request XML and is extended or modified by some return data. However, a few exceptions for this rule exist but they are explicitly named in the sections below.
Language identifier: A request that shows a user interface may contain a language attribute to control the language of its interface. This language attribute is always part of the XMLs root element. Supported values correspond to the 2-letter code as defined in ISO 639-1. Currently supported language identifiers are EN, DE, SV, FR, IT, ES, PT, PL, RU, AR, ZH.

RESTful implementation

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.

SOAP implementation

SOAP-API deprecated
Starting with Card SDK 6.3 the SOAP-API will be deprecated. The interface is still available but will no longer be maintained or updated. Technical Support for this interface will no longer be available.

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

CODE

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

The response, as output message is defined as:

CODE

<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.

Examples and testing

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:

Enter XML data into the Request field of the page
Start the corresponding function.
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.

List of web service methods

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.

Additional information

For more information, see: