1. REST API for Oracle Transaction Manager for Microservices REST API for Oracle Transaction Manager for Microservices
  2. Send Requests

Send Requests

Use these guidelines when sending requests using the Transaction Manager for Microservices (MicroTx) REST API.

Find IP Address of Istio Ingress Gateway

If you have installed MicroTx on a Kubernetes cluster, you must note down the external IP address of the Istio ingress gateway before you send any request.

Run the following command to find the external IP address of the Istio ingress gateway.

Command

kubectl get svc istio-ingressgateway -n istio-system

Sample Output

kubectl get svc istio-ingressgateway -n istio-system
NAME                   TYPE           CLUSTER-IP       EXTERNAL-IP   PORT(S)                                      AGE
istio-ingressgateway   LoadBalancer   10.109........   192.0.2.1     15021:31695/TCP,80:32333/TCP,443:7777/TCP    44h

Note the external IP address of the Istio ingress gateway and the port associated with the HTTP or HTTPS traffic, based on the access protocol that you have configured. For example, 192.0.2.1:443.

Required Role

Set permissions in your environment. Administrators can use the MicroTx REST APIs to view and manage all the transactions. Other users can manage and view only the distributed transactions that they have initiated; they cannot view the transactions initiated by other users.

URL Structure for requests in Kubernetes environment

If you have installed MicroTx on a Kubernetes cluster, here's the URL structure for the requests:

https://<Istio-gateway-IP-address>:<port>/<resource-path>

Where,

  • <Istio-gateway-IP-address>:<port> is the value to the external IP address and port number of the Istio ingress gateway in your environment.

  • <resource-path>: Relative path that defines the resource. For example, /admin/v1/xa-transaction.

Example

An example REST endpoint URL is https://192.0.2.1:443/admin/v1/xa-transaction.

URL Structure for requests in Docker environments

If you have installed MicroTx on Docker Swarm, here's the URL structure for the requests:

https://<Docker-registry-IP-address>:<port>/<resource-path>

Where,

  • <Docker-registry-IP-address>: IP address of the address of the Docker registry that you have created.

  • <port>: Port number that you have entered for the listenAddr property in the tcs.yaml of the MicroTx. For example, 5000. Ensure that you have set up the required networking rules to permit inbound and outbound HTTPS or HTTP traffic over this port.

  • <resource-path>: Relative path that defines the resource. For example, /admin/v1/xa-transaction.

Example

An example REST endpoint URL is https://198.51.100.1:5000/admin/v1/xa-transaction.

Supported Methods

You can view, update, and delete transactions by using standard HTTP method requests, as summarized in the following table.

HTTP Method Description
POST Creates a request by using the JSON-formatted data in the request body.
GET Retrieve information about the specified transaction or transactions.
PUT Update the transaction status by canceling or confirming a Saga transaction; committing an XA transaction; or confirming a TCC transaction.
DELETE Cancels a TCC transaction or rolls back an XA transaction.

Each object for which you can perform API calls is identified uniquely by its URI. Note that some of these methods may not be supported for certain objects. To see the methods that you can invoke for each object, see All REST Endpoints.

Media Types

The following media types are supported by the MicroTx REST API:

  • application/json

Supported Headers

The Oracle Compute Cloud Service REST API supports the following headers that may be passed in the header section of the HTTP request or response.

Header Description Example
Content-Type:

All the content in an HTTP request body sent to the API server must be encoded in JavaScript Object Notation (JSON). The API protocol version is also specified in the Content-Type: header in both request and response messages. The currently used content type is application/json.

The server specifies the expected version of the data in the response in the Content-Type: header.

If the server does not support the version specified by the client in the request, it responds with HTTP status code 415 (Unsupported Media Type). If the server can't provide a response in any of the versions supported by the client, it responds with status code 406 (Not Acceptable).

 Content-Type: application/json
Cookie:

The Cookie: header must be included with every request to the service.

Cookie: $OTMM_COOKIE

OTMM_COOKIE is the name of the variable in which you store the authentication cookie. See Authenticate.