1. Overview

REST API for uploading library content.

1.1. Version information

Version : 1

1.2. Tags

  • library-controller : Library 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, 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

  • Three client profiles are supported: other, web and native. 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 Authorization Code, Client Credentials and Refresh Token grants are supported.

  • Clients with profile web or native 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.

  • Native clients MUST use PKCE (RFC 7636).

  • 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).

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

Example:

https://example.com:8443/spotfire/api/rest/library/v1/upload/<jobId>

A JSON Swagger API definition file is available at http[s]://<host>[:<port>]/spotfire/api/v2/api-docs?group=library. The Swagger file can be accessed at this location by all authenticated users (unless disabled through configuration). The Swagger file can be used to generate client stubs, which will contain all types and methods that may be used with the API. There is also a Swagger UI available at http[s]://<host>[:<port>]/spotfire/api/swagger-ui.html?urls.primaryName=library

4. Usage

This API is used to upload files to the TIBCO Spotfire library. All calls assume that a successful authentication has been made, see above. The upload of a file is made through a number of calls. Code examples are available which show how to use the API.

First an initial call is made to start the upload. This call contains information about the file, e.g. its title, path, and file type. This creates an upload job with a unique job id which is used in subsequent calls to upload the file. If the file cannot be uploaded to the specified location in the library, e.g. because the parent folder does not exist, then an error is returned. Even if the initial check is OK things can change while the upload is in progress; for instance it can still fail if the parent directory is removed during the upload.

The file can be uploaded in one or more chunks. This makes it possible to start the upload of a file before the entire file content has been produced. It is also possible to upload different chunks simultaneously. Smaller chunks are often advantageous from a network perspective - if the upload of a single chunk fails it is easier to resend a small chunk rather than a huge one.

When the initial call is made, it possible to also specify the number of chunks that will be sent, or the total number of bytes that will be sent. If these do not match what has been received by the API server when the upload job is finished, it is assumed that something has gone wrong and the upload will be rejected.

The response to an API call will contain links that are specific to an upload job, and that can be used for subsequent calls to the API, c.f. HATEOAS. These links correspond to the API paths shown below. Note that some links require parameters to be supplied before they can be used.

After the initial call the actual payload is uploaded through one or more requests. The content goes in the body of the upload requests. The payload should not be encoded.

It is recommended to provide a digest of the payload via HTTP headers, for verification by the API server. The Content-MD5 header can be used to provide a base64 encoded MD5 digest of the request body, e.g. Content-MD5: Q2hlY2sgSW50ZWdyaXR5IQ== (RFC 1864), while the Digest header can be used to provide one (or more) base64 encoded other checksum (SHA, SHA-256, SHA-512), e.g. Digest: SHA=thvDyvhfIqlvFe+A9MYgxAfm1q5= (RFC 3230).

It is also good practice to set the Content-Length HTTP header to signal the size of the chunk to upload. The administrator of the API server may impose size restrictions on uploads, for instance minimum chunk size (applicable to all chunks except the last one), or maximum upload size.

When all chunks have been uploaded, a call is made to signal that the upload is finished and the contents from the different chunks is combined into one file in the TIBCO Spotfire library. When uploading data, there is an option to set a finished parameter on the request. In this case the upload job is automatically finished when the last chunk has been uploaded.

It is possible to cancel an ongoing upload job. It is also possible to check the status of an ongoing or recent upload job.

Note
 There is a restriction on which file types that can be uploaded. Currently only Spotfire Binary Data Format (SBDF) files are supported (with library filetype spotfire.sbdf).
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. Library-controller

Library Controller

5.1.1. Create upload job

PUT /rest/library/v1/upload
Description

Starts a library upload job.

Parameters
Type Name Description Schema

Body

envelope
required

Information about the content to be uploaded.

Envelope«LibraryUpload»
Responses
HTTP Code Description Schema

201

Upload job created

Envelope«UploadResponse»

400

Invalid or incomplete request

ErrorResponse

403

Insufficient library permissions

ErrorResponse

404

Folder not found or insufficient library permissions

ErrorResponse

409

Item already exists

ErrorResponse

413

Job size limit exceeded

ErrorResponse

429

Job number limit exceeded

ErrorResponse

500

Internal server error

ErrorResponse

503

Server busy

ErrorResponse
Consumes

  • application/json

Produces

  • application/json

Security
Type Name Scopes

oauth2

oauth2

api.rest.library.upload

5.1.2. Add data to an upload job

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

Uploads data to an upload job.

Parameters
Type Name Description Schema Default

Header

Content-Length
required

The content length

integer (int64)

Header

Content-MD5
optional

An MD5 digest, according to RFC 1864, of the uploaded data that can be used to verify data integrity.

string

Header

Digest
optional

A digest, according to RFC 3230 and RFC 5843, of the uploaded data that can be used to verify data integrity. Supported algorithms are MD5, SHA, SHA-256 and SHA-512.

string

Path

jobId
required

The job id

string

Query

chunk
required

The chunk number

integer (int32)

Query

finish
optional

Indicates whether the upload should be immediately finished after this request

boolean

"false"

Body

Body
required

The data to append to the upload job

integer (int32)
Responses
HTTP Code Description Schema

200

Content added to upload job

Envelope«UploadResponse»

400

Invalid or incomplete request

ErrorResponse

403

Insufficient library permissions

ErrorResponse

404

Job not found

ErrorResponse

413

Job size limit exceeded

ErrorResponse

415

Invalid content

ErrorResponse

500

Internal server error

ErrorResponse

503

Server busy

ErrorResponse
Consumes

  • */*

Produces

  • application/json

Security
Type Name Scopes

oauth2

oauth2

api.rest.library.upload

5.1.3. Check the status of an upload job

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

Can be used to see if the job succeeded or not, and what chunks have been successfully uploaded

Parameters
Type Name Description Schema

Path

jobId
required

The job id

string
Responses
HTTP Code Description Schema

200

OK

Envelope«UploadResponse»

400

Invalid or incomplete request

ErrorResponse

404

Job not found

ErrorResponse

500

Internal server error

ErrorResponse
Produces

  • application/json

Security
Type Name Scopes

oauth2

oauth2

api.rest.library.upload

5.1.4. Cancel an upload job

DELETE /rest/library/v1/upload/{jobId}
Parameters
Type Name Description Schema

Path

jobId
required

jobId

string
Responses
HTTP Code Description Schema

200

OK

Envelope«UploadResponse»

400

Invalid or incomplete request

ErrorResponse

404

Job not found

ErrorResponse

500

Internal server error

ErrorResponse
Produces

  • application/json

Security
Type Name Scopes

oauth2

oauth2

api.rest.library.upload

5.1.5. Finish an upload

POST /rest/library/v1/upload/{jobId}/finish
Parameters
Type Name Description Schema

Path

jobId
required

jobId

string
Responses
HTTP Code Description Schema

200

OK

Envelope«UploadResponse»

400

Invalid or incomplete request

ErrorResponse

403

Insufficient library permissions

ErrorResponse

404

Job not found

ErrorResponse

500

Internal server error

ErrorResponse

503

Server busy

ErrorResponse
Consumes

  • application/json

Produces

  • application/json

Security
Type Name Scopes

oauth2

oauth2

api.rest.library.upload

6. Definitions

6.1. Envelope«LibraryUpload»

The payload of an API exchange. Content will vary depending on the API method.

Name Schema

data
required

LibraryUpload

6.2. Envelope«UploadResponse»

The payload of an API exchange. Content will vary depending on the API method.

Name Schema

data
required

UploadResponse

6.3. Error

Name Description Schema

code
required

A predefined error code.
Example : "internal_error"

string

description
required

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

string

6.4. ErrorResponse

Name Description Schema

error
required

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

Error

6.5. LibraryItem

Name Description Schema

description
optional

A description of the item.
Example : "My data file."

string

keywords
optional

A list of searchable keywords associated with the item.
Example : [ "keyword1", "keyword2" ]

< string > array

parentPath
required

The parent library folder of the item.
Example : "/my-analyses/"

string

title
required

The title of the item.
Example : "my-data-file"

string

type
required

The type of the item.
Example : "spotfire.sbdf"

string

6.6. LibraryUpload

Defines a library upload request.

Name Description Schema

item
required

Information about the library item to upload.

LibraryItem

numberOfBytes
optional

The size of the data that will be uploaded, if known.
Example : 1234

integer (int64)

numberOfChunks
optional

The number of chunks in which the data will be uploaded, if known.
Example : 1

integer (int32)

overwriteIfExists
optional

Sets whether or not the item should be overwritten if it already exists.
Example : true

boolean

6.7. UploadResponse

Defines the result of a request to the upload API. The response contains properties to checkstatus of the upload job, and job specific links to API operations concerning the specific upload job.

Name Description Schema

cancelLinkAbs
optional

An absolute link to the API operation for cancelling the specific upload job.

string

cancelLinkRel
optional

A relative link to the API operation for cancelling the specific upload job.

string

cancelledAt
optional

The time at which the upload job was cancelled.

string

finishLinkAbs
optional

An absolute link to the API operation for finishing the specific upload job.

string

finishLinkRel
optional

A relative link to the API operation for finishing the specific upload job.

string

finishedAt
optional

The time at which the upload job was finished.

string

getStatusLinkAbs
optional

An absolute link to the API operation for getting the status of the specific upload job.

string

getStatusLinkRel
optional

A relative link to the API operation for getting the status of the specific upload job.

string

uploadLinkBaseAbs
optional

An absolute link to the API operation for uploading data chunks to the specific upload job.

string

uploadLinkBaseRel
optional

A relative link to the API operation for uploading data chunks to the specific upload job.

string

uploadedChunks
optional

A list containing the numbers of the already uploaded chunks.

< integer (int32) > array

7. Security

7.1. oauth2

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

Name Description

api.rest.library.upload

Upload content to the library

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 TIBCO Spotfire© Server and Environment Installation and Administration manual.

11. Additional resources

For more information please refer to these resources:

  • The TIBCO Community Wiki.

  • The SDK zip contains an example written in C# for how to call the automation services API and on how to authenticate with the Spotfire Server. For more information on the example see the readme.txt in the example: <SDK.zip>\Examples\Integration\SpotfireDeveloper.ServerApiExample