Date: Fri, 29 Mar 2024 08:00:08 +0000 (UTC)
Message-ID: <528089341.12591.1711699208832@change.sos-berlin.com>
Subject: Exported From Confluence
MIME-Version: 1.0
Content-Type: multipart/related;
boundary="----=_Part_12590_1873027003.1711699208832"
------=_Part_12590_1873027003.1711699208832
Content-Type: text/html; charset=UTF-8
Content-Transfer-Encoding: quoted-printable
Content-Location: file:///C:/exported.html
JS7 - REST Web Service API
JS7 - REST Web Service API
Introduction
- Any operations that can be performed on orders, workflows, jobs and rel=
ated objects such as cancelling, suspending and resuming orders are perform=
ed by the JS7 REST Web Service API.
- In addition, a PowerShell module is available for simplified access to =
the REST Web Service API, see JS7 - PowerShell Module.
Design
- The REST Web Service implements a stateless API.
- Except for the facts that a session is started by logging into the REST=
Web Service API and is terminated either by logging out or by expiration a=
ny operations performed with the REST Web Service API cannot rely on the pr=
evious state of an object.
- For example, retrieving an order at a given time does not prevent this =
order from transitioning to a subsequent state before the next call to the =
API is executed.
- The REST Web Service API is asynchronous for most parts.
- Any operations that affect a Controller or Agent are handled asynchrono=
usly. In fact such operations are managed by the JOC Cockpit Proxy Service =
that forwards them to a Controller, see JS7 - Implementation Architecture.
- The result of an operation is not returned with the response to the API=
call but will become available later on. In a situation when JOC Cockpit i=
s not connected to a Controller or if a Controller is not connected to an A=
gent, e.g. due to network issues, API calls will still work. Such calls are=
handled by the Proxy Service that will forward them when the Controller be=
comes available.
- For example, consider an API call to cancel an existing order. The resp=
onse to this call will return acceptance/denial of the request. The operati=
on is forwarded to a Controller and to an Agent respectively, however, the =
result will become available only after acknowledgement by the Agent and th=
e respective response from the Controller.
- API calls for asynchronous operations pending with the JOC Cockpit Prox=
y Service will be lost if the JOC Cockpit is restarted. There is no need to=
restart JOC Cockpit after a connection loss to a Controller as it will rec=
onnect automatically.
- A few API calls are handled synchronously, mainly when it comes to oper=
ations on the inventory. For example, API calls to store objects with the i=
nventory will immediately return results. However, API calls to remove obje=
cts such as a workflow from the inventory are handled asynchronously as thi=
s operation requires interaction with a Controller to remove the workflow f=
rom its journal and from the journals of respective Agents. REST Clients th=
erefore should not rely on any operation to return synchronous results.
- The REST Web Service API is designed for cluster operation.
- If a Controller cluster is operated then the JOC Cockpit Proxy Service =
will automatically connect to the active Controller instance. In case of fa=
il-over or switch-over the Proxy Service will connect to the cluster member=
instance that is the resulting active instance.
- Any changes to objects caused by API calls are synchronized between the=
active Controller and the passive Controller. In case of later reconnectio=
n the Controller instances will reconcile to have the information about cha=
nged object states synchronized.
- This behavior does not affect a REST Client that makes use of the API, =
therefore REST clients will continue to work even in the case of cluster fa=
il-over or switch-over operations.
Usage
- The REST Web Service API is called by using an HTTP client that sends J=
SON based requests and receives JSON based responses.
- The following REST Web Service API requests are available:
- URL
joc/api/authentication/login
- URL
joc/api/*
- Subsequent calls to URLs can, for example, retrieve the inventory of wo=
rkflow.
- Find the respective URLs from the Technical Documentation of the REST Web Service API
- The JS7 REST Web Service API returns=
the relevant JSON response indicated with the docs.
- URL
joc/api/authentication/logout
- The last operation of a client is a call to this URL in order to logout=
from the REST Web Service API.
- Requirements
- REST Web Service API requests should use HTTP POST or GET operations as=
indicated.
Further Resources
How To .. Shell
-
Page:=
span>
-
Page:=
span>
-
Page:=
span>
-
Page:=
span>
-
Page:=
span>
-
Page:=
span>
-
Page:=
span>
How To .. PowerShell
-
Page:=
span>
-
Page:=
span>
-
Page:=
span>
-
Page:=
span>
-
Page:=
span>
-
Page:=
span>
------=_Part_12590_1873027003.1711699208832--