REST API to Upload SBDF Files to the Spotfire® Library

Back to Spotfire® Web Services API Overview page

Introduction

NOTE: This page discusses the Spotfire® Library REST API v1 which has now been superseded by the Library REST API v2 which has more functionality. The Library REST API V2 is now the preferred method to use a REST API with the Library.

The Library REST API v1 (available from version 10.2) lets external applications upload Spotfire Binary Data Format files (SBDF files) to the Spotfire library. This allows you to integrate your application directly with the Spotfire eco system. Combined with Spotfire's open source Java and C# libraries for reading and writing sbdf you have everything you need to push data from your applications into Spotfire for visual data discovery and advanced analytics.

This is useful in scenarios where you want to analyze data in Spotfire as part of your workflow but the regular data access capabilities of Spotfire, including data connectors, local file access and custom data sources, cannot be used. For example, you might have data that is produced dynamically in an external analytic tool or the data might be stored in some proprietary database for which there is no Spotfire connector available. The Spotfire library has built-in support for managing access rights for its content. This can be used to control who can access your data files.

New in Spotfire 10.3 is the support for OAuth2 Authorization Code Grant. This allows for calling the API on behalf of the end users rather than by the API client itself. For example, when uploading a file to the Spotfire library, the library privileges of the end users will determine which library folders the API client can upload files to.

Documentation

Library REST API v1

How to use the API

Register API client

Before using the API you need to register an API client to get client credentials. This is done with the register-api-client command, run using the config tool in the Spotfire Server. For the Library REST API the scope parameter must be set to api.rest.library.upload. Before running the command it is important to decide what client profile (?web', 'native', or 'other' depending on what type of application will call the API) and.grant types (see next section) to use. Here are some examples:

 register-api-client --name="Other client" -Sapi.rest.library.upload --clientprofile=other -Gclient_credentials

 register-api-client --name="Web client" -Sapi.rest.library.upload --clientprofile=web -Gauthorization_code -Rhttps://example.com/foo/return

Register a client with the profile 'web' (e.g. a server-side web application), acting on behalf of an end-user, that may use long-lived refresh tokens (for continued access when the end-user isn't present). Note that the offline scope is also needed for refresh tokens:
```
 register-api-client --name="Web client" -Sapi.rest.library.upload -Soffline --client-profile=web -Gauthorization_code -Grefresh_token -Rhttps://example.com/foo/return
```
Register a client with the profile 'native' (e.g. an iOS app), acting on behalf of an end-user, which should be allowed to make requests on behalf of the user without the user's explicit permission:
```
 register-api-client --name="Native client" -Sapi.rest.library.upload --clientprofile=native -Gauthorization_code --require-end-user-consent=false
```

See the Spotfire Server manual for a description of all parameters to the register-api-client command. For managing existing API clients, the following commands are available: delete-oauth2-client, list-oauth2-clients and show-oauth2-client.

Note: In the default server configuration, the public web services (REST and SOAP) are enabled. If they are not enabled on your server instance, they can be enabled by using the config-web-service-api command (see here for more details).

Authentication and authorization

All calls to any of the API Endpoint URLs is authenticated by including an access token which is retrieved by making a request to the token endpoint. If the access token has timed out, you'll need to retrieve a new one.

The OAuth2 support has been extended in Spotfire 10.3 to include Authorization Code grant and Refresh Token in addition to Client Credentials grant (supported from Spotfire 10.2).

An OAuth2 Authorization Code grant allows for calling the API on behalf of the end user to let the library privileges of that user determine where files can be uploaded. This type of authorization flow is typically used for web applications and can optionally be configured to prompt for end user consent.

Refresh Token may be issued to allow access when the end-user isn?t present. This is useful when for example performing periodic uploads or similar.

When using Client Credentials grant it is the library privileges of the API client itself that determine to which library folders it is allowed to upload files. A registered API client can be viewed as a Spotfire user in the Spotfire Library admin UIs, where it also can be assigned appropriate group membership. This type of authentication flow is typically used for a headless application.

See the API documentation for a detailed description of the authentication and authorization flows.

Call the API endpoint URLs to upload a file

Once your application has retrieved an access token, you are ready to call the API endpoint URLs. The basic syntax looks like this:

http://<host>[:<port>]/spotfire/api/<ServicePath>

Where ServicePath represents each API call and is one of the following:

Create upload job

PUT /rest/library/v1/upload

Add data to an upload job

POST /rest/library/v1/upload/{jobId}

Check the status of an upload job

GET /rest/library/v1/upload/{jobId}

Cancel an upload job

DELETE /rest/library/v1/upload/{jobId}

Finish an upload

POST /rest/library/v1/upload/{jobId}/finish

A typical call sequence:

Create upload job
Add data to an upload job
Repeat 2 until all chunks are added
Finish the upload

See the API documentation for a detailed description of each API call

API documentation is also available in the OpenAPI (Swagger) format at:

http://<host>[:<port>]/spotfire/api/v2/api-docs?group=library

API to search and browse the Spotfire Library

An application that uses the Library REST API to upload files may also need to search or browse the Spotfire Library, for instance, to let the user select a destination folder for the upload. Search and browse capabilities are provided by the Library REST API v2 or a separate API, Library Service, a SOAP based web service.

Examples

Java

The attached file, spotfire-library-api-examples-20230123.zip, contains two Java sample programs that illustrate the use the Library REST API, including implementation details related to retrieving the access token and create the HTTP request for each API call.

The first example uses Client Credentials grant and second example uses Authorization Code grant and Refrest Token.

See the README.md file for detailed instructions on how to setup and run the examples.

We recommend that you use an IDE with debugging capabilities. If you don't already have your favourite IDE installed, a good choice would be Microsoft Visual Studio Code, a powerful and Open Source IDE available on multiple platforms. There is a free Java Extension Pack available for developing and running Java applications.

C#

Spotfire SDK includes an example of a standalone C# program that uses the Library REST API and also the SOAP based Library Service.

Instructions on how to download the SDK can be found here.
The example is located in the SDK\Examples\Integration\SpotfireDeveloper.ServerApiExample folder.

Swagger UI

The Spotfire Server provides the Swagger UI, a test tool that allows you to visualize and interact with the API. The Swagger UI is available at:

http://<host>[:<port>]/spotfire/api/swagger-ui.html?urls.primaryName=library

Note: the Swagger UI only support certain calls and does, for example, not allow for adding data to an upload job.

Configuration

The following settings can be changed using Spotfire® Server command line tool:

Maximum number of ongoing upload jobs per client.
Maximum number of ongoing upload jobs allowed per server cluster.
Maximum size for an item to be uploaded

For more information on this, see the Spotfire® Server manual.

spotfire-library-api-examples-20230123.zip

Sign In