1. Overview
Spotfire Server REST API to update a Spotfire Web Player analysis.
1.1. Version information
Version : 1
1.2. Tags
-
webPlayer : Spotfire Server Web Player API
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
oruser_agent
, 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 services 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
-
Four client profiles are supported:
other
,web
,native
anduser_agent
. The profileother
should be used by a typically headless application performing requests on its own behalf. The profileweb
should be used by a server-side web application performing requests on behalf of an end-user. The profilenative
should be used by a native client, such as an iOS or Android app, performing requests on behalf of an end-user. The profileuser_agent
should be used by a client-side (JavaScript) web application, performing requests on behalf of an end-user. -
The Authorization Code, Client Credentials and Refresh Token grants are supported.
-
Clients with profile
web
,native
oruser_agent
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 no end-user is 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.-
Refresh tokens that are no longer needed SHOULD be revoked, as described in RFC 7009.
-
-
Public clients (clients without client credentials) MUST use PKCE (RFC 7636). Confidential clients MAY use _PKCE.
-
Native clients can 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 can 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).
-
All clients SHOULD implement support for OAuth 2.0 Authorization Server Issuer Identification (RFC 9207).
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/rest/webplayer/v1/<ServicePath>
Example:
https://example.com:8443/spotfire/api/rest/webplayer/v1/analyses/<itemId>/load
You can download the Open API Specification (OAS) for this REST API as a JSON file from the Spotfire Server at http[s]://<host>[:<port>]/spotfire/api/v2/api-docs?group=web-player
. This OAS file can be accessed at this location by all authenticated users (unless disabled through configuration). The OAS file can be used to generate client stubs, which will contain all types and methods that can be used with the API.
You can also browse the OAS for this REST API using the Swagger UI, available at http[s]://<host>[:<port>]/spotfire/api/swagger-ui.html?urls.primaryName=web-player
4. Usage
This API is used to update a Spotfire Web Player analysis. All calls assume that a successful authentication has been made, see above.
Note
|
Clients should be as resilient as possible, e.g. they should be able to handle any 4XX or 5XX http status codes and not just the ones documented here. |
Note
|
In later versions of this API, additional JSON properties might be added. Make the JSON response parsing done by the API client forgiving, so it can accept unexpected properties and different ordering. |
5. Resources
5.1. Web-player-controller
5.1.1. Update a Spotfire Web Player analysis
POST /analyses/{itemId}/load
Description
Loads an analysis file on the specified resource pool, or according to default routing. Note that the caller must be a member of the Administrator group, or have the Spotfire Consumer → External updates of analysis files in Spotfire web clients license.
Parameters
Type | Name | Description | Schema | Example |
---|---|---|---|---|
Path |
itemId |
Analysis item ID. |
string |
|
Body |
Body |
Optional properties of the analysis to be updated on a Spotfire Web Player. |
Responses
HTTP Code | Description | Schema |
---|---|---|
204 |
Successful. |
|
400 |
One of the arguments is invalid. |
|
403 |
The caller does not have sufficient privileges to perform the request. |
|
500 |
Internal server error. |
|
503 |
Server busy. |
Consumes
-
application/json
Security
Type | Name | Scope |
---|---|---|
oauth2 |
api.web-player.load |
6. Definitions
6.1. Analysis
Properties of the analysis to be updated on a Spotfire Web Player.
Name | Description | Schema |
---|---|---|
clientUpdate |
Optional client update mode. Use the automatic value to update all running web browser clients. Use the manual value to have a normal update where each client should update manually. If no value is provided, the manual behavior is used by default. |
|
keepAliveMinutes |
Optional keep alive minutes. The number of minutes that the Web Player server should keep an inactive analysis before it is recycled. If the value is provided, it must be a non-negative value that is less than 1440 minutes (one day). If no value is provided, the default value used is 10 minutes. |
integer |
resourcePool |
Optional resource pool name. If no resource pool is specified, the default resource pool is used. |
string |
6.2. ClientUpdate
Optional client update mode. Use the automatic value to update all running web browser clients. Use the manual value to have a normal update where each client should update manually. If no value is provided, the manual behavior is used by default.
Enum value | Schema |
---|---|
automatic |
string |
manual |
string |
6.3. Error
Name | Description | Schema |
---|---|---|
code |
A predefined error code. |
string |
description |
A description of the error. |
string |
6.4. ErrorResponse
Name | Description | Schema |
---|---|---|
error |
The error response with an error code and a description of the error. |
7. Security
7.1. spotfire-api-oauth2
Type : oauth2
Flow : application
Token URL : /spotfire/oauth2/token
Name | Description |
---|---|
api.web-player.load |
Load Analysis on Web Player |
8. 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 |
9. Error Codes
A request to the API that results in an ErrorResponse will have a response body with the following format:
{
"error": {
"code": "server_busy",
"description": "The server is currently too busy to handle the request"
}
}
where description
is a description of the error, and code
can be one of the following predefined API error codes:
Error Code | HTTP Status | Description |
---|---|---|
invalid_request |
400 |
The request was invalid or incomplete |
precondition_failed |
400 |
A precondition for the request was not met |
bad_digest |
400 |
The supplied digest is not valid or does not match the digest of the request body |
not_authenticated |
401 |
The API client is not authenticated |
not_authorized |
403 |
The API client is not authorized to access the requested resource |
not_found |
404 |
The requested resource cannot be found |
job_unknown |
404 |
The referenced job does not exist, or the client does not have access to it |
method_not_allowed |
405 |
The HTTP method is not allowed |
already_exists |
409 |
The resource already exists |
limit_exceeded |
413 |
A resource limit has been reached |
unsupported_mediatype |
415 |
The media type of the request payload is unsupported |
rate_limit_exceeded |
429 |
A resource limit has been reached |
internal_error |
500 |
The server encountered an error when processing the request |
server_busy |
503 |
The server is currently too busy to handle the request |
10. 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 Spotfire© Server and Environment Installation and Administration manual.
11. Additional resources
For more information please refer to these resources: