1. Overview

Spotfire Server REST API for Information Model elements management.

1.1. Version information

Version : 1

1.2. Tags

  • informationmodel-controller : Spotfire Information Model 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

  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.

2.2. 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 server-side 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).

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/informationmodel/v1/<ServicePath>

Example:

https://example.com:8443/spotfire/api/rest/informationmodel/v1/elements/{id}

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=is. 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 may 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=is

4. Usage

This API is used to update and redirect the Spotfire Information Model element. 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. Information-Model-APIs

5.1.1. Redirects the information model element

POST /elements/{id}/redirect
Description

Redirects the information model element.

Parameters
Type Name Description Schema Example

Path

id
required

The guid of the information model element

string

"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"

Query

dryrun
optional

boolean

Body

Body
required

Information about the content to be updated

InformationModelDataSourceRedirect
Responses
HTTP Code Description Schema

200

Successfully completed information model element redirect

String

401

Unauthorized access

ErrorResponse

403

The user or client does not have sufficient permissions

ErrorResponse

400

The request was invalid or incomplete

ErrorResponse

500

An unexpected error while processing the request

ErrorResponse

404

Information model element not found.

ErrorResponse
Consumes

  • application/json

Produces

  • application/json

Security
Type Name Scope

oauth2

spotfire-api-oauth2

api.information-model.read

oauth2

spotfire-api-oauth2

api.information-model.write

5.1.2. Update Element

PATCH /elements/{id}
Description

Update the information model element

Parameters
Type Name Description Schema Example

Path

id
required

The guid of the information model element

string

"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"

Query

validate
optional

boolean

Body

Body
required

Information about the content to be updated

InformationModelElement
Responses
HTTP Code Description Schema

200

Updated the information model element

InformationModelElement

401

Unauthorized access

ErrorResponse

403

The user or client does not have sufficient permissions

ErrorResponse

400

The request was invalid or incomplete

ErrorResponse

500

An unexpected error while processing the request

ErrorResponse

404

Information model element not found.

ErrorResponse
Consumes

  • application/json

Produces

  • application/json

Security
Type Name Scope

oauth2

spotfire-api-oauth2

api.information-model.read

oauth2

spotfire-api-oauth2

api.information-model.write

6. Definitions

6.1. InformationModelDataSourceRedirect

Defines a datasource redirect request.

Name Description Schema

id
optional

The guid of the information model data source. For example, 2e31a024-6395-4725-b15f-2a4935a9f3df.
Example : "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"

string

fromCatalog
optional

The name of the catalog to change from. If both fromCatalog and toCatalog are null, then the catalog changes will be skipped.

string

toCatalog
optional

The name of the catalog to change to. If both fromCatalog and toCatalog are null, then the catalog changes will be skipped.

string

fromSchema
optional

The name of the schema to change from. If both fromSchema and toSchema are null, then the schema changes will be skipped.

string

toSchema
optional

The name of the schema to change to. If both fromSchema and toSchema are null, then the schema changes will be skipped.

string

6.2. Error

Name Description Schema

code
optional

A predefined error code.
Example : "internal_error"

string

description
optional

A description of the error.
Example : "An error occurred while processing the request"

string

6.3. InformationModelElement

Name Description Schema

type
optional

The information model element (library item) type. Example spotfire.column / spotfire.filter / spotfire.join / spotfire.procedure / spotfire.query / spotfire.datasource

string

id
optional

The guid of the information model data source. For example, 2e31a024-6395-4725-b15f-2a4935a9f3df.
Example : "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"

string

name
optional

The name of the information model element

string

description
optional

The description of the information model element

string

parentId
optional

The guid of the information model data source. For example, 2e31a024-6395-4725-b15f-2a4935a9f3df.
Example : "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"

string

path
optional

The path to the information model element

string

property
optional

The properties for the information model element

<Property> array

reference
optional

The definitions for all parameters referenced by the information model element

<string> array

6.4. Property

Name Description Schema

m_key
optional

string

m_value
optional

string

6.5. InformationModelDataSource

Defines a datasource request.

Name Description Schema

type
optional

The information model element (library item) type. Example spotfire.column / spotfire.filter / spotfire.join / spotfire.procedure / spotfire.query / spotfire.datasource

string

id
optional

The guid of the information model data source. For example, 2e31a024-6395-4725-b15f-2a4935a9f3df.
Example : "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"

string

name
optional

The name of the information model element

string

description
optional

The description of the information model element

string

parentId
optional

The guid of the information model data source. For example, 2e31a024-6395-4725-b15f-2a4935a9f3df.
Example : "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"

string

path
optional

The path to the information model element

string

property
optional

The properties for the information model element

<Property> array

reference
optional

The definitions for all parameters referenced by the information model element

<string> array

dataSourceType
optional

The type of data source, indicating configuration in settings.xml.

string

writeAllowed
optional

Flag for read only datasource. false if read only, true if data source allows writing temporary. NOTE: Data write back via stored procedures ignores this flag.

boolean

fetchSize
optional

Number of cells fetched for each call to database.

integer

batchSize
optional

Number of cells returned in each batch.

integer

dataSourceAuthentication
optional

Flag indicating if database access is controlled via personal login to the database. true if user uses own login, false if all users use same.

boolean

connectionUrl
optional

The connection URL to external data source.

string

userName
optional

The user name used for database connection.

string

password
optional

The password used for database connection.

string

maxConnections
optional

Number of simultaneous connections to database.

integer

minConnections
optional

Initial number of connection to database.

integer

sessionOpenCommands
optional

Commands to be executed when opening a session.

<string> array

sessionCloseCommands
optional

Commands to be executed when closing a session.

<string> array

initializationCommands
optional

Commands to run when creating a connection.

<string> array

preCommands
optional

The pre commands.

<string> array

postCommands
optional

The post commands.

<string> array

pingCommand
optional

The ping command.

string

credentialsTimeout
optional

The credentials timeout time, in seconds.

integer

6.6. ErrorResponse

Name Description Schema

error
optional

The error response with an error code and a description of the error.

Error

7. Security

7.1. spotfire-api-oauth2

Type : oauth2
Flow : application
Token URL : /spotfire/oauth2/token

Name Description

api.information-model.read

Reading from the information model element

api.information-model.write

Writing to the information model element

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: