Package com.spotfire.ws.pub


package com.spotfire.ws.pub
The Spotfire Server public SOAP Web Service API.

Note: This is a SOAP Web Service API. The implementing classes may not be called directly from Java code. Use the WSDL files to generate client proxies which will contain all types and methods that may be used.

The services can be accessed at the following location, where ServiceName is the name of the service interface as listed below:

  • http[s]://<host>[:<port>]/spotfire/api/soap/<ServiceName>

Example:

  • https://server.example.com:8443/spotfire/api/soap/LibraryService
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.

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.
    When registering the client you specify what type of client it is, what grants and scopes the client should be able to use etc.
  2. 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 or user_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 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.

Additional information

  • Four client profiles are supported: other, web, native and user_agent. The profile other should be used by a typically headless application performing requests on it’s own behalf. The profile web should be used by a web application performing requests on behalf of an end-user. The profile native should be used by a native client, such as and iOS or Android app, performing requests on behalf of an end-user. The profile user_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 or user_agent can only use the Authorization Code and Refresh Token grants, clients with profile other 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.
    • 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 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 either 127.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).
  • All clients SHOULD implement support for OAuth 2.0 Authorization Server Issuer Identification (RFC 9207).

Generating client proxies

Proxies can be generated using the tool of your choice.

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.

Additional resources

For more information please refer to these resources:

The section Spotfire Server public Web Services API's of the Spotfire© Server and Environment Installation and Administration manual.

The SpotfireDeveloper.ServerApiExample developer example that can be found under Integration in the Spotfire SDK.

The Spotfire Community Wiki.

  • Class
    Description
    Represents an Access Control List entry for an item in the Library.
    Represents a collection of Access Control List entries for an item in the Library.
    Represents a SOAP fault.
    Represents the name of a group principal in the User Directory.
    Represents a user principal in the User Directory.
    Represents a globally unique identifier (GUID).
    Deprecated, for removal: This API element is subject to removal in a future version.
    This service is deprecated and will be removed in a future release.
    Exception thrown by the InformationModelService.
    Represent a conflict resolution strategy used when copying or moving items in the Library.
    Represents an item in the Library.
    Represents a permission on an item in the Library.
    Represents a custom property of an item in the Library.
    Deprecated.
    This service is deprecated and will be removed in a future release.
    Exception thrown by the LibraryService.
    Represents a SOAP fault.
    Deprecated, for removal: This API element is subject to removal in a future version.
    This service is deprecated and will be removed in a future release.
    Exception thrown by the LicenseService.
    Represents the name of a principal (user or group) in the User Directory.
    Represents a principal (user or group) in the User Directory.
    Describes the properties needed to submit an external scheduled update via the dedicated SOAP web service.
    A public SOAP web service used to update a Spotfire Web Player analysis externally.
    Exception thrown by the UpdateAnalysisService.
    Deprecated, for removal: This API element is subject to removal in a future version.
    This service is deprecated and will be removed in a future release.
    Exception thrown by the UserDirectoryService.
    Represents the name of a user principal in the User Directory.
    Represents a user principal in the User Directory.