Back to Extending Spotfire page
Introduction
TIBCO Spotfire® Server offers several web services APIs that can be used for various tasks. As of TIBCO Spotfire Server 7.13, the current set of Spotfire Server Web Services APIs contains the following services:
- InformationModelService
Updates the configuration of an Information Model data source.
- LibraryService
Manages the TIBCO Spotfire Server Library.
- LicenseService
Manages Licenses and License Functions.
- UserDirectoryService
Manages users and groups. (Tutorial here)
- UpdateAnalysisService
Updates a Spotfire Web Player analysis externally. (Tutorial at this link)
Added in TIBCO Spotfire® Server 7.13, there is a REST API to execute Automation Services jobs.
API Reference
Web Services API in TIBCO Spotfire® Server 7.13
Endpoint
The services can be accessed at the following location, where ServiceName is the name of the service interface:
- http[s]://<host>[:<port>]/spotfire/api/soap/<ServiceName>
Example:
WSDL
The WSDL file for each service can be retrieved by appending /wsdl to the service URL. The WSDL file can be accessed at this location without authentication (unless disabled through configuration). The WSDL file for each service can also be retrieved by appending ?wsdl to the service URL, in which case a valid access token must be included with the call.
Example:
Authentication and authorization
The API uses the OAuth 2.0 protocol for authentication and authorization, with the Spotfire Server itself as Authorization Server. Some services also require additional forms of authorization (see the documentation of each service for details).
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.
Basic steps:
- Register an API client using the register-api-client command to obtain client credentials.
- Obtain an access token by making a request to the Token Endpoint according to the instructions in section 4.4 of RFC 6749.
- The token endpoint can be accessed at: http[s]://<host>[:<port>]/spotfire/oauth2/token
- 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
- The request 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.
Generating client proxies
Proxies can be generated using the tool of your choice. Here is an example on how to do it using the wsimport tool that is included with the Oracle JDK. The tool must be run for each service to be used.
Example on how to generate a proxy, for the LibraryService:
wsimport -d bin -s src https://server.example.com:8443/spotfire/api/soap/LibraryService/wsdl
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 theTIBCO Spotfire© Server and Environment Installation and Administration manual.
Additional resources
For more information please refer to these resources:
The section Spotfire Server public Web Services API of the TIBCO Spotfire© Server and Environment Installation and Administration manual.
The SpotfireDeveloper.ServerApiExample developer example that can be found under Integration in the Spotfire SDK.
Legacy API
The legacy SOAP API, available in TIBCO Spotfire Server 7.12 and previous versions, is still available under /ws/pub/.
Note: The legacy API is deprecated and will be removed in a future version.
The legacy API is disabled by default but can be enabled using the --legacy-soap-enabled flag of the config-web-service-api command.
For more information please refer to the documentation of a previous, supported, version of the Spotfire Server.
Web Services API in TIBCO Spotfire® Server 7.12 and previous versions
Endpoint
The services can be accessed at the following location, where ServiceName is the name of the service interface:
- http[s]://<host>[:<port>]/spotfirews/pub/<ServiceName>
Example:
WSDL
The WSDL for each service can be retrieved by appending ?wsdl to each service URL.
Example:
Sessions
When the web service client performs its first request to the server, a new session is established. The response from the server contains a session cookie called JSESSIONID. The web service client needs to include this session cookie in all further requests to the server made in the context of the session.
CSRF protection
The Web Service API has built-in protection against CSRF attacks. For backwards compatibility reasons, this CSRF protection is not enabled by default. For maximum security, it is strongly recommended to enable it. To do this, export the server configuration from the database, run the config-csrf-protection command and import the updated configuration to the database.
On Windows, open a command prompt, go to the <Spotfire Server installation folder>\tomcat\bin directory and execute the following commands:
- config.bat export-config --force
- config.bat config-csrf-protection --public-web-services=true
- config.bat import-config -c "Enabled the CSRF protection for the public Web Service API"
On Linux, open a command-line shell, go to the <Spotfire Server installation folder>/tomcat/bin directory and execute the following commands:
- config.sh export-config --force
- config.sh config-csrf-protection --public-web-services=true
- config.sh import-config -c "Enabled the CSRF protection for the public Web Service API"
The protection mechanism is based on the synchronizer token pattern. When the web service client first establishes its session on the server, the server returns a CSRF synchronizer token in a cookie called XSRF-TOKEN. The client needs to pick up this cookie value and provide it in an HTTP header called X-XSRF-TOKEN in all requests to the server, for as long as the session is active. If the server returns a new XSRF-TOKEN cookie value, the client must immediately use the new token value. If the client does not provide any token in the X-XSRF-TOKEN header, or if the provided token is invalid, the server responds with the HTTP status code 403 Forbidden. The request should then be repeated with the valid token in the HTTP header.
Generating client proxies
Proxies can be generated using the tool of your choice. Here is an example on how to do it using the wsimport tool that is included with the Oracle JDK. The tool must be run for each service to be used.
Steps:
- Create an authentication file containing the URL of the web service, including a valid username and password of a user that is a member of the API User group
- Generate a proxy by running wsimport for the web service (specifying the authentication file created in the previous step)
Example on how to generate a proxy, for the LibraryService:
- Create an authentication file:
https://user:password@server.example.com:8443/spotfire/ws/pub/LibrarySer...
- Generate a proxy, using the authentication file above:
wsimport -d bin -s src -Xauthfile auth.txt https://server.example.com:8443/spotfire/ws/pub/LibraryService?wsdl
Enabling the Web Services API and Configuring Groups
In order to be able to use the Spotfire Public Web Services API, the following two conditions MUST be met:
- The Spotfire Public Web Services API must be enabled on the Spotfire server. It is disabled by default, for security reasons
- The user that is accessing the API must be a member of the API Users group on the Spotfire server
Enabling the Spotfire Public Web Services API
The instructions for doing this can be found here: Enabling the Web Services API , but here's a practical example:
Adding a User to the API Users Group:
The user that will access the Public Web Services API must be a member of the API Users Group:
You can, of course, nest groups, so one practical way of doing this could be to make the Administrators group be a sub-group of API Users, then all Administrators will be API Users by default.