API Architecture

Although integration can be technically implemented using several different components, for example, third-party API gateways, load balancers, etc., TX API is based on the object model of TranzAxis and follows its representation of transaction processing. When being processed, all REST/JSON requests are transformed into the native TranzAxis RTP representation and passed to the designated internal RTP online interface for processing. Responses are processed in a similar way. Thus, for successful integration and effective use of TX API, it is necessary to have knowledge of the TranzAxis object model and transaction processing logic used in TranzAxis RTP.

Idempotency

An idempotent operation is an operation that has no additional effect when it is called more than once with the same input parameters. This is important, especially when errors and timeouts occur during the transaction processing. TX API uses the following approach to manage operations executed on objects: it uses the PUT command to create or update an object, thus providing additional flexibility and simplifying the work with objects when the processing result is unknown. For example, a response to the previous request is not received due to the network timeout and it is not known whether an object is created or not. In such a situation, it is possible to repeat the same request, and if the object has not been created before, it will be created. To manage the request processing result (for example, for operations used to update objects), it is possible to use extended parameters in the request body. These parameters are usually passed in the tranRq/match object, where the key parameter represents the unique key of each operation. The system assigns this key to the operation if this operation is processed successfully (for example, the object is updated successfully). So if the operation result is unknown for any reason, it is possible to repeat the same request with the same key. If the operation with this unique key is not found in the system, it will be processed as expected; otherwise, the system will respond that similar operation has already been processed and no changes will be introduced.

Example of the PUT operation for the Application object with the unique key specified:

{
    "object": {
        "ref": {
            "rid": "app123"
        },
        "status": "Draft",
    },
    "tranRq": {
        "match" : {
            "key": "QETUO13579WRYIP"
        }
    }
}

To ensure additional control of objects processing, it is possible to use the mustExist parameter that enables to manage the way the system processes create and update operations. The table below describes the options of using this parameter with the PUT operation:

mustExist value	Action
true	Attempt to update the object. If the object does not exist, an error occurs.
false	Attempt to create an object. If the object exists, an error occurs.
null (not specified)	Attempt to find the object. If the object does not exist, the system will create it. If the object exists, the system will update this object.

Example of using the mustExist parameter for the Application object:

PUT
https://tx/v1/application?mustExist=true

Attention! If any object ID is passed in the request (or if the system can find the object using the ID submitted), the system will attempt to find this object first and will ignore the mustExist value which means that presence of the unique ID in the request has priority over the mustExist parameter. For example, if mustExist=false and no card with the specified ID exists in the system, the response will be Object not found as the system receives the card ID and attempts to find the card first. When creating an object, it is not necessary to specify the internal object ID in the request, the system will generate and assign an internal ID to the object automatically.

Object Identification

All objects in the system are identified by their unique IDs. The system uses these IDs when processing such operations as create, update or delete. Most of the TX API objects have the following IDs:

ID	Type
id	Unique internal ID (generated and assigned in TranzAxis)
rid	Reference ID (can be assigned in an external system)

Example of retrieving the card details using the card ID:

GET
https://tx/v1/card?id=1357

Some objects can also be identified by extRid (which represents an object ID in an external system) or by other specific attributes, such as key, etc. For details on the available ID types, refer to the TX REST API specification.