1. Overview
REST API for executing Automation services jobs.
1.1. Version information
Version : 1
1.2. Tags
-
automation-services-controller : Automation Services Controller
2. Authentication and authorization
The API uses the OAuth 2.0 protocol for authentication and authorization, with the Spotfire Server itself as Authorization Server.
Note: The API does not use HTTP sessions so there is no need to maintain session cookies.
Note: All communication should always be done over HTTPS when using OAuth 2.0.
2.1. Basic steps
-
Register an API client using the
register-api-client
command to obtain client credentials.When registering the client you specify what type of client it is, what grants and scopes the client should be able to use etc.
-
Obtain an access token using one of the following alternatives
-
To use the Authorization Code grant follow the instructions in section 4.1 of RFC 6749.
-
To use the Client Credentials grant follow the instructions in section 4.4 of RFC 6749.
-
To use a Refresh Token follow the instructions in section 6 of RFC 6749.
- Additional information on how to get the access token
-
The OAuth 2.0 Authorization Server Metadata (RFC 8414) can be retrieved from:
http[s]://<host>[:<port>]/spotfire/.well-known/oauth-authorization-server
-
The Authorization Endpoint can be accessed at:
http[s]://<host>[:<port>]/spotfire/oauth2/auth
-
The Token Endpoint can be accessed at:
http[s]://<host>[:<port>]/spotfire/oauth2/token
-
When calling the Token Endpoint the client must authenticate using the HTTP Basic authentication scheme as described in section 2.3.1 of RFC 6749, using the credentials obtained when registering the client (unless the client profile is
native
, in which case no credentials are issued). -
The initial request (to the Authorization Endpoint in the case of the Authorization Code grant, or to the Token Endpoint in the case of the Client Credentials grant) must include any and all scopes required to access the service(s) that the client intend to access (see the documentation of each service for details).
-
-
Include the access token in all requests to the API, in an
Authorization
header as described in section 2.1 of RFC 6750.-
The access token has a limited lifetime, after which a new token must be obtained by repeating step 2.
-
An access token is only valid for the services and operations described in the scope parameter provided when obtaining the access token. The available scopes are described in the documentation for each service.
-
2.2. Additional information
-
Three client profiles are supported:
other
,web
andnative
. The profileother
should be used by a typically headless application performing requests on it’s own behalf. The profileweb
should be used by a web application performing requests on behalf of an end-user. The profilenative
should be used by a native client, such as and iOS or Android app, performing requests on behalf of an end-user. -
The Authorization Code, Client Credentials and Refresh Token grants are supported.
-
Clients with profile
web
ornative
can only use the Authorization Code and Refresh Token grants, clients with profileother
can only use the Client Credentials grant. -
Refresh tokens MAY be issued to allow access also when the end-user isn’t present (useful when for example performing periodic uploads or similar). To request a refresh token to be issued the scope
offline
should be included in the request to the Authorization Endpoint. For more information see section 1.5 of RFC 6749. -
Native clients MUST use PKCE (RFC 7636).
-
Native clients may use any of the three ways of receiving the response listed in section 7 of RFC 8252.
-
To use Private-Use URI Scheme Redirection a custom URI scheme must be registered when registering the client.
-
To use Claimed "https" Scheme URI Redirection an authorized redirect URI must be registered when registering the client.
-
Loopback Interface Redirection is supported for all native clients. The scheme must be
http
. The host must be either127.0.0.1
(IPv4) or[::1]
(IPv6). The path may be either/
or/auth
. The port is variable.
-
-
Native clients SHOULD adhere to the guidelines outlined in OAuth 2.0 for Native Apps (RFC 8252).
3. API Endpoint URLs
All API services can be accessed at the following location, where ServicePath is one of the entries in the Resources listing below:
http[s]://<host>[:<port>]/spotfire/api/<ServicePath>
Example:
https://example.com:8443/spotfire/api/rest/as/job/start-content
A JSON Swagger API definition file is available at http[s]://<host>[:<port>]/spotfire/api/v2/api-docs?group=as
. The Swagger file can be accessed at this location by all authenticated users (unless disabled through configuration). The Swagger file can be used to generate client stubs, which will contain all types and methods that may be used with the API. There is also a Swagger UI available at http[s]://<host>[:<port>]/spotfire/api/swagger-ui.html
4. Resources
4.1. Automation-services-controller
Automation Services Controller
4.1.1. Abort an ongoing Automation Services job
POST /rest/as/job/abort/{jobId}
Description
This method aborts an ongoing Automation Services job based on its job ID
Parameters
Type | Name | Description | Schema |
---|---|---|---|
Path |
jobId |
The ID of the Automation Services job to abort |
string |
Query |
reason |
A text describing the reason for aborting the job |
string |
Responses
HTTP Code | Description | Schema |
---|---|---|
200 |
Job Aborted |
|
404 |
Job not Found |
No Content |
Consumes
-
application/json
Produces
-
application/json
Security
Type | Name | Scopes |
---|---|---|
oauth2 |
api.rest.automation-services-job.execute |
4.1.2. Start an Automation Services job from XML
POST /rest/as/job/start-content
Description
This method starts an Automation Services job from its XML definition
Parameters
Type | Name | Description | Schema |
---|---|---|---|
Query |
path |
The path |
string |
Body |
jobXml |
The Automation Services Job definition |
string |
Responses
HTTP Code | Description | Schema |
---|---|---|
200 |
Job Created |
Consumes
-
application/xml
Produces
-
application/json
Security
Type | Name | Scopes |
---|---|---|
oauth2 |
api.rest.automation-services-job.execute |
4.1.3. Start an Automation Services job from a library file
POST /rest/as/job/start-library
Description
This method starts an Automation Services job from a library file. The identity of the file can be provided using either library path or library ID (GUID). Note that the API client must have sufficient library permissions to access the library item.
Parameters
Type | Name | Description | Schema |
---|---|---|---|
Query |
id |
The library ID of the Automation Services job |
string |
Query |
path |
The library path of the Automation Services job |
string |
Responses
HTTP Code | Description | Schema |
---|---|---|
200 |
Job Created |
Consumes
-
application/json
Produces
-
application/json
Security
Type | Name | Scopes |
---|---|---|
oauth2 |
api.rest.automation-services-job.execute |
4.1.4. Get status of an Automation Services job
GET /rest/as/job/status/{jobId}
Description
This method returns the status of an Automation Services job
Parameters
Type | Name | Description | Schema |
---|---|---|---|
Path |
jobId |
The Automation Services job ID |
string |
Responses
HTTP Code | Description | Schema |
---|---|---|
200 |
OK |
|
404 |
Job not Found |
No Content |
Produces
-
application/json
Security
Type | Name | Scopes |
---|---|---|
oauth2 |
api.rest.automation-services-job.execute |
5. Definitions
5.1. ExecutionStatus
Name | Description | Schema |
---|---|---|
JobId |
The GUID of the job |
string |
Message |
Message |
string |
StatusCode |
Status |
enum (NotSet, Queued, InProgress, Finished, Failed, Missing, Busy, Canceled) |
6. Security
6.1. oauth2
Type : oauth2
Flow : application
Token URL : /spotfire/oauth2/token
Name | Description |
---|---|
api.rest.automation-services-job.execute |
Execute and abort Automation Services jobs |
7. Common Responses
HTTP Code | Description | Reason |
---|---|---|
401 |
Not Authenticated |
The client has not been authenticated |
403 |
Not Authorized |
The client is not authorized to access the requested resource |
500 |
Internal Server Error |
Something went wrong when the processing the request |
8. Configuration
The API is enabled by default. To disable it or to make other configuration changes, use the config-web-service-api
command. For more information see the section Configuration using the command line of the TIBCO Spotfire© Server and Environment Installation and Administration manual.
9. Additional resources
For more information please refer to these resources:
-
The SDK zip contains an example written in C# for how to call the automation services API and on how to authenticate with the Spotfire Server. For more information on the example see the
readme.txt
in the example:<SDK.zip>\Examples\Integration\SpotfireDeveloper.ServerApiExample