1. Overview
Spotfire Server REST API for Library items management.
1.1. Version information
Version : 2
1.2. Tags
-
library-upload : Spotfire Library Upload API
-
library-items : Spotfire Library API
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
-
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.
-
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
oruser_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 services that the client intend to access (see the documentation of each service for details).
-
-
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
anduser_agent
. The profileother
should be used by a typically headless application performing requests on its own behalf. The profileweb
should be used by a server-side web application performing requests on behalf of an end-user. The profilenative
should be used by a native client, such as an iOS or Android app, performing requests on behalf of an end-user. The profileuser_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
oruser_agent
can only use the Authorization Code and Refresh Token grants. Clients with profileother
can only use the Client Credentials grant. -
Refresh tokens MAY be issued to allow access also when no end-user is 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 can 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 either127.0.0.1
(IPv4) or[::1]
(IPv6). The path can 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/library/v2/<ServicePath>
Example:
https://example.com:8443/spotfire/api/rest/library/v2/upload/<jobId>
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=library-v2
. 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 can 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=library-v2
4. Usage
This API is used to upload & browse files of the 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.
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-upload
5.1.1. Create upload job
POST /upload
Description
Starts a library upload job
Parameters
Type | Name | Description | Schema | Example |
---|---|---|---|---|
Body |
Body |
Information about the content to be uploaded |
Responses
HTTP Code | Description | Schema |
---|---|---|
201 |
Upload job created |
Consumes
-
application/json
Produces
-
application/json
Security
Type | Name | Scope |
---|---|---|
oauth2 |
api.library.write |
5.1.2. Finish an upload
POST /upload/{jobId}/finish
Description
Finishes a started upload job
Parameters
Type | Name | Description | Schema | Example |
---|---|---|---|---|
Path |
jobId |
The job id |
string |
|
Responses
HTTP Code | Description | Schema |
---|---|---|
200 |
The finished job |
Produces
-
application/json
Security
Type | Name | Scope |
---|---|---|
oauth2 |
api.library.write |
5.1.3. Check the status of an upload job
GET /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 | Example |
---|---|---|---|---|
Path |
jobId |
The job id |
string |
|
Responses
HTTP Code | Description | Schema |
---|---|---|
200 |
The status of the job |
Produces
-
application/json
Security
Type | Name | Scope |
---|---|---|
oauth2 |
api.library.write |
5.1.4. Add data to an upload job
POST /upload/{jobId}
Description
Uploads data to an upload job
Parameters
Type | Name | Description | Schema | Example |
---|---|---|---|---|
Header |
Content-MD5 |
An MD5 digest, according to RFC 1864, of the uploaded data that can be used to verify data integrity. |
string |
|
Header |
Digest |
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 |
The job id |
string |
|
Query |
chunk |
The chunk number |
integer |
|
Query |
finish |
Indicates whether the upload should be immediately finished after this request |
boolean |
Responses
HTTP Code | Description | Schema |
---|---|---|
200 |
Content added to upload job |
Produces
-
application/json
Security
Type | Name | Scope |
---|---|---|
oauth2 |
api.library.write |
5.1.5. Cancel an upload job
DELETE /upload/{jobId}
Description
Cancels an upload job
Parameters
Type | Name | Description | Schema | Example |
---|---|---|---|---|
Path |
jobId |
The job id |
string |
|
Responses
HTTP Code | Description | Schema |
---|---|---|
200 |
The cancelled job |
Produces
-
application/json
Security
Type | Name | Scope |
---|---|---|
oauth2 |
api.library.write |
5.2. Library-items
5.2.1. Get library item versions
GET /items/{itemId}/versions
Description
Returns all stored versions of a library item.
Parameters
Type | Name | Description | Schema | Example |
---|---|---|---|---|
Path |
itemId |
string |
|
Responses
HTTP Code | Description | Schema |
---|---|---|
200 |
The library item’s versions. |
|
404 |
Library item not found. |
Produces
-
application/json
Security
Type | Name | Scope |
---|---|---|
oauth2 |
api.library.write |
|
oauth2 |
api.library.read |
5.2.2. Retrieves library item
GET /items/{itemId}
Description
Retrieves library item meta data.
Parameters
Type | Name | Description | Schema | Example |
---|---|---|---|---|
Path |
itemId |
The Library item unique ID. |
string |
|
Query |
attributes |
Optional: A comma separated list of item properties to fetch. Can be one or more of (all, path, permissions, properties, versions). |
string |
Responses
HTTP Code | Description | Schema |
---|---|---|
200 |
The library item’s meta data. |
|
404 |
Library item not found. |
Produces
-
application/json
Security
Type | Name | Scope |
---|---|---|
oauth2 |
api.library.write |
|
oauth2 |
api.library.read |
5.2.3. Update a library item
PATCH /items/{itemId}
Description
Update a library item
Parameters
Type | Name | Description | Schema | Example |
---|---|---|---|---|
Path |
itemId |
The library item ID. |
string |
|
Query |
conflictResolution |
The conflict resolution strategy to use, can be one of (KeepNew, KeepOld, KeepBoth). If no value is provided, then the default will be KeepBoth. |
string |
|
Body |
Body |
Responses
HTTP Code | Description | Schema |
---|---|---|
200 |
The updated library item’s meta data |
|
404 |
Library item not found. |
Consumes
-
application/json
Produces
-
application/json
Security
Type | Name | Scope |
---|---|---|
oauth2 |
api.library.write |
5.2.4. Delete library item
DELETE /items/{itemId}
Description
Deletes a library item.
Parameters
Type | Name | Description | Schema | Example |
---|---|---|---|---|
Path |
itemId |
The Library item ID. |
string |
|
Responses
HTTP Code | Description | Schema |
---|---|---|
204 |
Delete successful. |
|
404 |
Library item not found. |
Security
Type | Name | Scope |
---|---|---|
oauth2 |
api.library.write |
5.2.5. Get library item version
GET /items/{itemId}/versions/{versionId}
Description
Returns a specified library item version.
Parameters
Type | Name | Description | Schema | Example |
---|---|---|---|---|
Path |
itemId |
string |
|
|
Path |
versionId |
string |
|
Responses
HTTP Code | Description | Schema |
---|---|---|
200 |
The library item version. |
|
404 |
Library item not found. |
Produces
-
application/json
Security
Type | Name | Scope |
---|---|---|
oauth2 |
api.library.write |
|
oauth2 |
api.library.read |
5.2.6. Update library item version
PATCH /items/{itemId}/versions/{versionId}
Description
Updates a library item version.
Parameters
Type | Name | Description | Schema | Example |
---|---|---|---|---|
Path |
itemId |
string |
|
|
Path |
versionId |
string |
|
|
Body |
Body |
Responses
HTTP Code | Description | Schema |
---|---|---|
200 |
The updated version. |
|
404 |
Library item not found. |
Consumes
-
application/json
Produces
-
application/json
Security
Type | Name | Scope |
---|---|---|
oauth2 |
api.library.write |
5.2.7. Delete library item version
DELETE /items/{itemId}/versions/{versionId}
Description
Deletes a library item version.
Parameters
Type | Name | Description | Schema | Example |
---|---|---|---|---|
Path |
itemId |
string |
|
|
Path |
versionId |
string |
|
Responses
HTTP Code | Description | Schema |
---|---|---|
204 |
Delete successful. |
|
404 |
Library item not found. |
Security
Type | Name | Scope |
---|---|---|
oauth2 |
api.library.write |
5.2.8. Get information about the library
GET /info
Description
Get library’s root item, supported item types, limits and parameters
Responses
HTTP Code | Description | Schema |
---|---|---|
200 |
Information about the library. |
Produces
-
application/json
Security
Type | Name | Scope |
---|---|---|
oauth2 |
api.library.write |
|
oauth2 |
api.library.read |
5.2.9. Download library item content
GET /items/{itemId}/contents
Description
Downloads the content of a library item. Note that the downloaded file should be seen as an opaque object that may not be introspected or edited in any way, unless it’s in a publicly documented format (such as SBDF).
Parameters
Type | Name | Description | Schema | Example |
---|---|---|---|---|
Path |
itemId |
string |
|
Responses
HTTP Code | Description | Schema |
---|---|---|
200 |
The content of the library item |
byte |
404 |
Library item not found. |
Produces
-
application/octet-stream
Security
Type | Name | Scope |
---|---|---|
oauth2 |
api.library.write |
|
oauth2 |
api.library.read |
5.2.10. Get library folder items
GET /items/{itemId}/children
Description
Get library folder items' meta data.
Parameters
Type | Name | Description | Schema | Example |
---|---|---|---|---|
Path |
itemId |
The library folder ID. |
string |
|
Query |
attributes |
A comma separated list of optional item properties to fetch. Can be one or more of (all, path, permissions, properties, versions) |
string |
Responses
HTTP Code | Description | Schema |
---|---|---|
200 |
The library folder items' meta data. |
|
404 |
Folder not found. |
Produces
-
application/json
Security
Type | Name | Scope |
---|---|---|
oauth2 |
api.library.write |
|
oauth2 |
api.library.read |
5.2.11. Query library items
GET /items
Description
Returns all items, up to the provided limit, in the given location that matches the given search expression. Only items that the calling user has access to will be returned. The parameters searchExpression, locationId and maxResults can be used together. Otherwise, the parameters path and type can be used together. The parameter attributes can be used with both parameter combinations described above.
Parameters
Type | Name | Description | Schema | Example |
---|---|---|---|---|
Query |
attributes |
A comma separated list of optional item properties to fetch. Can be one or more of (all, path, permissions, properties, versions). Can be combined with all other parameters. |
string |
|
Query |
locationId |
Unique ID of a folder (and all sub-folders) in which to search, or null if the entire library should be searched. Can be combined with searchExpression and maxResults parameters. |
string |
|
Query |
maxResults |
The maximum number of items to be returned or a number less than or equal to 0 if all matching items should be returned. If no value is set then the server will set a default maximum number of results.Can be combined with searchExpression and locationId parameters. |
integer |
|
Query |
path |
The location of the item, a path starts with a slash and each component is separated with a slash as well, may not be empty or null. Can be combined with type parameter. |
string |
|
Query |
searchExpression |
Library search expression. Can be combined with locationId and maxResults parameters. |
string |
|
Query |
type |
The type of the item. Can be combined with path parameter. |
string |
Responses
HTTP Code | Description | Schema |
---|---|---|
200 |
List of items in the given location which match the search expression |
|
404 |
No matching items found or user has no access to read them. |
Produces
-
application/json
Security
Type | Name | Scope |
---|---|---|
oauth2 |
api.library.write |
|
oauth2 |
api.library.read |
5.2.12. Create a new library item
POST /items
Description
Create a new library item. Can be a new folder, or a copy of an existing library item
Parameters
Type | Name | Description | Schema | Example |
---|---|---|---|---|
Query |
conflictResolution |
The conflict resolution strategy to use, can be one of (KeepNew, KeepOld, KeepBoth). This is only used when copying an item. If no value is provided, then the default will be KeepBoth. |
string |
|
Query |
copyOf |
The id of a library item to clone |
string |
|
Query |
copyOfVersion |
The id of a library item version to clone |
string |
|
Body |
Body |
The folder to create (type, title, description and parentId). To copy an item only parentId is needed/utilized. |
Responses
HTTP Code | Description | Schema |
---|---|---|
201 |
The newly created library folder |
|
401 |
The user is not authorized to create folder |
|
404 |
Parent folder not found |
Consumes
-
application/json
Produces
-
application/json
Security
Type | Name | Scope |
---|---|---|
oauth2 |
api.library.write |
6. Definitions
6.1. UploadInfo
Library info data including root library item and library item types.
Name | Description | Schema |
---|---|---|
allowedItemTypes |
Item types allowed to be uploaded |
<string> array |
maxConcurrentJobsPerClient |
The maximum number of concurrent jobs per client |
integer |
maxUploadSizeBytes |
The maximum uploadable item size |
integer |
6.2. LibraryItem
An item in the library.
Name | Description | Schema |
---|---|---|
id |
Unique ID of the item. |
string |
title |
Title of the item. |
string |
path |
Path of the item |
string |
description |
Description of the item, or null if there is no description. |
string |
type |
Type of the item. |
string |
createdBy |
The user that created the item, or null if not known. |
|
created |
The date and time when the item was created. |
string |
modifiedBy |
The user that last modified the item, or null if not known. |
|
modified |
The date and time when the item was last modified. |
string |
accessed |
The date and time when the item was last accessed. |
string |
parentId |
Unique ID of the parent item. |
string |
size |
The size of the item in bytes. |
integer |
properties |
Properties set on the item. |
<LibraryProperty> array |
permissions |
Permissions for the item. |
<AclEntry> array |
versionId |
Represents the unique ID of a library item versions. |
string |
itemVersions |
The list of library item versions. |
<LibraryItemVersion> array |
isFavorite |
True if the item is set as favorite by the current user. |
boolean |
favoriteCount |
how many times this item has been set as favorite |
integer |
6.3. LibraryItemVersions
A collection of library item versions.
Name | Description | Schema |
---|---|---|
itemVersions |
The collection of library item versions. |
<LibraryItemVersion> array |
6.4. LibraryInfo
Library info data including root library item and library item types.
Name | Description | Schema |
---|---|---|
rootItem |
The ID of the library root item. |
string |
itemTypes |
Defined library types. |
<string> array |
uploadInfo |
Information about library uploads |
|
downloadInfo |
Information about library downloads |
6.5. LibraryItemVersion
Library item version details.
Name | Description | Schema |
---|---|---|
id |
ID of the version. |
string |
created |
The date and time when the item was created. |
string |
createdBy |
The user that created the version, or null if not known. |
|
formatVersion |
The format version, if any, of the content of the version. |
string |
size |
The size of the content of the version in bytes. |
integer |
name |
The name of the version, if any. |
string |
comment |
Comment on the version, if any. |
string |
restoredFromVersionId |
The ID of the version from which this version was restored from, or null if this version was not created by restoring from another version. |
string |
restoredFromTimestamp |
The date and time when the version from which this version was restored was created, or null. |
string |
6.6. AclEntry
Represents an Access Control List entry for an item in the Library. Many ACL entries may be associated with a library item , each representing the permissions set for one user or group.
Name | Description | Schema |
---|---|---|
principalId |
Unique id of the principal for which the permissions are set. |
string |
principalName |
The name of the principal for which the permissions are set. |
string |
domainName |
The domain name of the principal for which the permissions are set. |
string |
principalType |
The type of the principal (user or group). |
|
permissions |
The list of permissions. |
<LibraryPermission> array |
inheritedFromId |
The id of the folder from which the permissions have been inherited. Absence of a value indicates that the permissions are set on the requested item itself. |
string |
6.7. Error
Name | Description | Schema |
---|---|---|
code |
string |
|
description |
string |
6.8. LibraryItems
A collection of library items.
Name | Description | Schema |
---|---|---|
items |
The list of library items. |
<LibraryItem> array |
6.9. LibraryProperty
A property of an item in the Library.
Name | Description | Schema |
---|---|---|
key |
Property key. |
string |
values |
Property Value. |
<string> array |
versioned |
Indicates if property is versioned or not. |
boolean |
6.10. UserPrincipal
A user principal in the User Directory.
Name | Description | Schema |
---|---|---|
id |
ID of the principal. |
string |
name |
The name of the principal. |
string |
domainName |
The domain name of the principal. If no domain has been set, then the name of the internal SPOTFIRE domain is returned. |
string |
displayName |
The display name of the principal. |
string |
6.11. ErrorResponse
Name | Description | Schema |
---|---|---|
error |
6.12. LibraryUploadJob
A library upload job.
Name | Description | Schema |
---|---|---|
numberOfChunks |
The number of chunks in which the data will be uploaded, if known. |
integer |
numberOfBytes |
The size of the data that will be uploaded, if known. |
integer |
jobId |
ID of the upload job. |
string |
item |
The library item uploaded. |
|
uploadedChunks |
A list of the chunks already uploaded. |
<integer> array |
finishedAt |
The time at which the upload job was finished. |
string |
cancelledAt |
The time at which the upload job was cancelled. |
string |
6.13. DownloadInfo
Information about downloads in the public Library REST API
Name | Description | Schema |
---|---|---|
allowedItemTypes |
Item types allowed to be downloaded |
<string> array |
6.14. LibraryItemNew
Represents a new folder or a copied item. For copied items, only parent ID is used.
Name | Description | Schema |
---|---|---|
title |
Title of the item. Required if creating a new folder. |
string |
description |
Description of the item, or null if no description has been set. |
string |
type |
Type of the item. Required if creating a new folder. |
string |
parentId |
The ID of the parent item. Required if creating a new folder or cloning an item. |
string |
6.15. LibraryItemUpload
Library item details.
Name | Description | Schema |
---|---|---|
title |
Title of the item. |
string |
description |
Description of the item, or null if there is no description. |
string |
type |
Type of the item. |
string |
parentId |
Unique ID of the parent item. |
string |
6.16. LibraryUploadJobRequest
A library upload job request.
Name | Description | Schema |
---|---|---|
numberOfChunks |
The number of chunks in which the data will be uploaded, if known. |
integer |
numberOfBytes |
The size of the data that will be uploaded, if known. |
integer |
item |
Information about the library item to upload. |
|
overwriteIfExists |
Indicates whether or not the item should be overwritten if it already exists. |
boolean |
6.17. PrincipalType
Represents principal type (user or group).
Enum value | Schema |
---|---|
user |
string |
group |
string |
6.18. LibraryPermission
Represents a permission on an item in the Library. Note that all permissions are independent of each other and that users that are granted WRITE access in most cases also should have READ and EXECUTE access. Possible values are: Read, Write, Owner & Execute.
Enum value | Schema |
---|---|
Read |
string |
Write |
string |
Owner |
string |
Execute |
string |
7. Security
7.1. spotfire-api-oauth2
Type : oauth2
Flow : application
Token URL : /spotfire/oauth2/token
Name | Description |
---|---|
api.library.read |
Reading from the library |
api.library.write |
Writing 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 Spotfire© Server and Environment Installation and Administration manual.
11. Additional resources
For more information please refer to these resources: