Introduction

• Any operations that can be performed on orders, workflows, jobs and related objects such as cancelling, suspending and resuming orders are performed by the JS7 REST Web Service API.
  • Note that any operation provided by the JOC Cockpit GUI makes use of the REST Web Service API.
  • Find details from the Technical Documentation of the REST Web Service API
• The JS7 - Unix Shell Command Line Interfacen is offered for frequently used operations based on the 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 any operations performed with the REST Web Service API cannot rely on the previous 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 asynchronously. 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 is not connected to a Controller or if a Controller is not connected to an Agent, 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 becomes available.
    • For example, consider an API call to cancel an existing order. The response to this call will return acceptance/denial of the request. The operation is forwarded to a Controller and to an Agent respectively, however, the result will become available only after acknowledgement by the Agent and the respective response from the Controller.
  • API calls for asynchronous operations pending with the JOC Cockpit Proxy 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 reconnect automatically.
  • A few API calls are handled synchronously, mainly when it comes to operations on the inventory. For example, API calls to store objects with the inventory will immediately return results. However, API calls to remove objects such as a workflow from the inventory are handled asynchronously as this operation requires interaction with a Controller to remove the workflow from its journal and from the journals of respective Agents. REST Clients therefore 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 fail-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 reconnection the Controller instances will reconcile to have the information about changed 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 fail-over or switch-over operations.

Usage

• The REST Web Service API is called by using an HTTP client that sends JSON based requests and receives JSON based responses.
• The following REST Web Service API requests are available:
  • URL joc/api/authentication/login
    • The first operation of a client is call to this URL in order to authenticate and to retrieve an access token.
    • A valid account and password have to be provided by the client for HTTP authentication. For HTTPS connections in addition or alternatively JS7 - Certificate based Authentication can apply, for details see JS7 - Identity and Access Management.
    • Permissions apply as explained by JS7 - Management of User Accounts, Roles and Permissions.
  • URL  joc/api/* 
    
    • Subsequent calls to URLs can, for example, retrieve the inventory of workflow.
    • 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

How To .. PowerShell