...

• The REST Web Service API is called by using a 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 a client carries out is a 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 the JS7 - Identity and Access Management article.
    • Permissions apply as explained in the JS7 - Management of User Accounts, Roles and Permissions article.
  • URL  joc/api/* 
    
    • Subsequent calls to URLs can, for example, retrieve the inventory of workflow.
    • The relevant URLs can be found in the Technical Documentation of the REST Web Service API
    • The JS7 REST Web Service API returns the relevant JSON response as indicated in the docs.
  • URL joc/api/authentication/logout
    • The last operation a client carries out 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.
  • Should the idle timeout between two web service requests exceed the JOC Cockpit session timeout then a login has to be performed, see the JS7 - Settings article for more information.

Examples

...

using Curl

• Example: Get the list of orders scheduled until a given date.
  • The attached example order_list_sample.sh is for use with curl. We do not consider curl to be perfect for handling web service requests. However, it shows the building blocks:

    • Code Block
      language bash title Example for use with curl to get list of orders scheduled until a given date linenumbers true collapse true
      #!/bin/sh # ---------------------------------------- # Protocol, host and port of JOC Cockpit JS_URL="http://localhost:7446" # Identification of JS7 instance JS_CONTROLLER_ID="controller" # Date up to that scheduled orders are returned JS_DATE_TO="+1d" # Authentication (default account) JS_USER=root JS_PASSWORD=root # ----------------------------------------- # ----------------------------------------- # Perform login echo "" echo "PERFORMING LOGIN" JS_JSON=$(curl -k -L -s -S -X POST -m 15 --user "$JS_USER:$JS_PASSWORD" -H "Accept: application/json" -H "Content-Type: application/json" $JS_URL/joc/api/authentication/login) JS_ACCESS_TOKEN=$(echo "$JS_JSON" | grep -Po '"accessToken":.*?[^\\]"' | awk -F ':' '{print $2}' | tr -d \" ) # ----------------------------------------- # ----------------------------------------- # Get the list of orders for a date range echo "" echo "Get the list of orders for date range: $JS_DATE_TO" # Execute web service request JS_REST_BODY="{ \"controllerId\": \"$JS_CONTROLLER_ID\", \"compact\": true, \"dateTo\": \"$JS_DATE_TO\" }" JS_JSON=$(curl -k -L -s -S -X POST -m 15 -d "$JS_REST_BODY" -H "X-Access-Token: $JS_ACCESS_TOKEN" -H "Accept: application/json" -H "Content-Type: application/xml" $JS_URL/joc/api/orders) echo "$JS_JSON" # ----------------------------------------- # ----------------------------------------- # Perform logout echo "" echo "PERFORMING LOGOUT" curl -k -L -s -S -X POST -m 15 -H "X-Access-Token: $JS_ACCESS_TOKEN" -H "Accept: application/json" -H "Content-Type: application/json" $JS_URL/joc/api/authentication/logout # ----------------------------------------- echo ""

    • Explanations

      • Line 4: Depending on your JOC Cockpit installation the protocol will be http or https. The default port is 4446 but might have been modified during setup.
      • Line 7: The Controller ID is specified during installation of the Controller and identifies a Controller standalone instance or a Controller cluster.
      • Line 10: Specify the relative date up to which you want the list of scheduled orders to be returned.
      • Line 13, 14: Default credentials after installation include the account "root" and password "root". The credentials might have been changed after setup of the JOC Cockpit.
      • Line 22: Note the use of Basic HTTP authentication
      • Line 23: The request to the /authentication/login web service returns an access token which is used with further requests.
      • Line 32, 33: Note the JSON body created for the request and the URL including the path /joc/api/orders used to return order information.
      • Line 42: Always perform a logout and consider the session idle timeout.

...