REST API overview

ITXA REST APIs are used to expose ITXA functions as RESTful web services that can be called by HTTP clients.

Other applications can then use REST APIs to provide these SPE functions as web services:
  • Transform
  • Deenvelope
  • Envelope
  • Import
  • Export
  • Check Pending Ack Status
  • Create, Read, Update, and Delete
  • System status

REST APIs allow you to control and configure systems remotely, and to deploy artifacts seamlessly across the architecture. The implementation can be available cross platform and for the cloud.

Sample use cases

Provisioning example: You have an application that manages trading partner information. This includes not only the information needed for SPE processing, but also other partner information, such as contact information, and information used by a communications gateway. You want this application to automatically manage the SPE configuration information.

Runtime example: You have an application that needs to do occasional transform, envelope, or deenvelope functions. However, you prefer to invoke SPE as a web service, rather than installing SPE on the same system with your application.

How to implement

Most ITXA REST APIs (Envelope, Deenvelope, Transform, Import, Export, CheckPendingAckStatus) use a "job" model that can be described as follows:
  1. Create a job to perform the function.

    The Deenvelope, Envelope, and Transform APIs also have an option to run asynchronously. (The default option is synchronous.)

  2. Read the job you created to get the response.

    If the job is running synchronously and a code is returned indicating that the job is not complete, retry the job.

  3. Optionally, read the documents that were created by the job.
  4. Delete the job when you are done.

    The Delete service accepts a valid ID returned from a Create or Read SPEResponse Type and deletes the job information from the database.

The behavior of the Export API in the Web Services browser differs slightly depending on the resource. See Export service service.

See the Read services and SystemStatus service for information on how to implement those services.

Security

Access to REST APIs is determined by SPE profile roles:
  • To list, read, or delete a job, your SPE profile must contain the REST role. You must also be the submitter of the job.
  • The System Administrator role can perform all functions for all jobs.
  • Company Administrators can perform all job functions for their own company or tenant.

REST APIs and multitenancy

The behavior of the REST APIs corresponds to the behavior of ITXA of the Java API. If you connect to ITXA with a REST API, the user that you connect as determines which tenant you are allowed to manage.

As a system administrator, you can use reference IDs to specify multitenancy options in the REST APIs just the same as you do in the Java API. Other users can run only under their assigned tenant IDs.

Base64 encoding

Binary data can be passed in Base64-encoded form on REST API calls. This applies to Import jobs or map data, as well as for input for Envelope/Deenvelope/Transform jobs. Examples of data where you might want to use Base64 encoding include the following:
  • X12 data with BIN segments
  • Flat file data that contains binary information
  • Data where the record delimiters, tab characters, or other whitespace characters are significant
  • Compiled maps

In such cases, you want to make sure that the data processed by ITXA is exactly the same as the original data. If the data is passed without using Base64 encoding, some characters may be changed when the data is converted to JSON or XML and then parsed by ITXA.

The REST APIs look for a special prefix of SIB64ENCODE to denote Base64-encoded data follows.

The SPEOption BASE64_OUTPUT_DOCS designates whether output documents generated by ITXA and returned from the REST APIs will be Base64-encoded or not (for example, by the Transform, Envelope, Deenvelope jobs). Valid values are as follows:
NO
Default. Documents are returned by the server unencoded.
YES
Documents are returned by the server as Base64 encoded and the SIB64ENCODE prefix is prepended.

If using the web services browser, some services automatically encode the data in Base64 automatically. For example, use the Browse button to select a map for the Create Map service encodes the data automatically.

If not using the web services browser, you must encode the data in Base64 and prepend the SIB64ENCODE prefix so that the data is handled correctly by the server.