TIBCO Spotfire® Web Services API Tutorials and Examples
Last updated:
5:24am Mar 15, 2019

Back to Extending Spotfire page

Overview

SOAP Web Services

TIBCO Spotfire® Server offers the following SOAP web services APIs: 

  • Information Model Service
    Updates the configuration of an Information Model data source.
     
  • Library Service
    Manages the TIBCO Spotfire Server Library. Read more.
     
  • License Service
    Manages Licenses and License Functions.
     
  • User Directory Service
    Manages users and groups. Read more.
     
  • Update Analysis Service
    Updates a Spotfire Web Player analysis externally. Read more.

REST APIs

TIBCO Spotfire® Server offers the following REST APIs: 

    • Automation Services REST API
      Executes Automation Services jobs. Available since version 7.13. Read more.
       
    • Library REST API
      Uploads content to the Spotfire Library. Available since version 10.2. Read more

    API Documentation

    SOAP 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:

    1. Register an API client using the register-api-client command to obtain client credentials.
    2. 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).
    3. 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.

    SOAP 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:

    1. config.bat export-config --force
    2. config.bat config-csrf-protection --public-web-services=true
    3. 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:

    1. config.sh export-config --force
    2. config.sh config-csrf-protection --public-web-services=true
    3. 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:

    1. 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
    2. 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:

    1. Create an authentication file:
      https://user:password@server.example.com:8443/spotfire/ws/pub/LibrarySer...
       
    2. 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:

    1. The Spotfire Public Web Services API must be enabled on the Spotfire server. It is disabled by default, for security reasons
    2. 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.