Introduction

The REST API allows programmatic access to Situate™ automation software server. To use the REST API, you will need a login and password just as if you were logging into the Situate Viewer. Use of SSL is supported and strongly encouraged as communications into Situate can be configured to initiate outside corporate firewalls. The REST API uses cookies to establish session management. Each part of a request and response is meaningful, including the request method (GET/POST, etc.), the individual headers (Location, Content-Type, Accept, etc.), and the response status code (200, 400, 404, etc.). Use of this API assumes a working knowledge of these HTTP components, and general use of RESTful web APIs.

Authentication

The REST API uses a basic authentication scheme based a login and password. User of the API must first authenticate or successfully login, which will return a valid HTTP session is created. The session will contain an authenticated Situate security context, if the login and password are valid. To avoid having to authenticate with every call, the client interface using the REST api must implement the use of cookies. Here is an example using curl:

curl -k -v -H "Content-Type: application/json" -X POST -c cookies.txt -d '{"user":"mylogin","password":"mypassword"}' https://localhost/situate/auth/login

Response Codes

The following response codes apply to all requests. Check each request type in the list below for more response codes specific to that request.

REST api response codes
Status Code Meaning Description
200 OK The request was processed successfully
201 OK Resource was created and processed successfully
400 Bad Request Your request contained invalid or missing data
401 Unauthorized Authentication failed or the authenticated session was not provided
404 Not Found The URI does not match any of the recognized resources, or, if you are asking for a specific resource with an ID, that resource does not exist
415 Unsupported Media Type The Content-Type header is not supported by the REST API
500 Internal Server Error The server was unable to process request or downstream system failed

Request and Response Formats

You can specify the formats you want to use for request and response data.

Supported Request Formats

Use the Content-Type header to specify the format your data is in.
  • JSON:application/json
  • XML:application/xml

Supported Response Formats

Use the Accept header to specify the output desired format. Not all resources will support all formats. Please review specific resource for more information.
  • JSON:application/json
  • XML:application/xml

Resources

The following resources are available via the REST API. The allowed request methods for each resource are listed below.

workflow

Description

Returns the list of workflow resources for the given state and queue specified by the query parameters described below. If no query parameters are specified then all workflow resources found in the server will be returned.

Query Parameters
Parameter Data Type Description
state String Can be either submitted or approved
queue String Defines which workflow queue to use. Default is all.

Description

Returns a workflow resource as specified by the path parameter id. A query parameter can be specified to filter the a submitted or approved version.

Path Parameters
Parameter Data Type Description
id String Defines the globally unique id for the workflow resource
Query Parameters
Parameter Data Type Description
state String Can be either submitted or approved

Description

Executes a specific workflow resource using the specified trigger name id.

Path Parameters
Parameter Data Type Description
id String Defines the globally unique id for the workflow resource
Query Parameters
Parameter Data Type Description
trigger String The trigger name that will be used to initiate workflow.

Description

Creates and submits a new workflow resource to Situate id.

Description

Approves a workflow resource that is in the submitted state. id.

Path Parameters
Parameter Data Type Description
id String Defines the globally unique id for the workflow resource

Description

Deletes a specified workflow resource in the specified state. id.

Path Parameters
Parameter Data Type Description
id String Defines the globally unique id for the workflow resource
Query Parameters
Parameter Data Type Description
state String Can be either submitted or approved

workflowInstance

Description

Returns the list of workflowInstance resources for the given state and queue specified by the query parameters described below. If no query parameters are specified then all workflowInstance resources found in the server will be returned.

Query Parameters
Parameter Data Type Description
state String Can be one of running, canceling or unconfirmed
queue String Defines which workflow queue to use. Default is all.

Description

Returns a workflowInstance resource as specified by the path parameter id.

Path Parameters
Parameter Data Type Description
id String Defines the globally unique id for the workflowInstance resource

Description

Cancels a workflowInstance resource that is in the running state. id.

Path Parameters
Parameter Data Type Description
id String Defines the globally unique id for the workflowInstance resource

Description

Deletes a specified workflowInstance resource in the specified state. id.

Path Parameters
Parameter Data Type Description
id String Defines the globally unique id for the workflowInstance resource