The Soda API

Soda has a REST API that gives web clients access to its facilities. This page gives some general information about the API, followed by descriptions of the commands that the API can execute.

General

Invocation

API methods are invoked by sending HTTP GET or POST requests to the API URL, which is /home/.api relative to the base URL of the Soda installation. For example, for a Soda system installed at https://www.example.com the API URL would be https://www.example.com/home/.api. Note that the protocol MUST be https, not http.

The HTTP request has a command parameter that defines what processing is to be performed, and may optionally also have a sodaapp parameter that identifies a Soda application that will do the processing, a plugin parameter that identifies a block plugin to handle block-related processing, or a sodaplugin parameter that identifies a view plugin to handle view-related processing. A POST request other than invoke_agent can also have an auth parameter giving authorizarion information. Depending on the command, the request may have other parameters giving further information. The command, sodapp, plugin and sodaplugin parameters are always passed as application/x-www-form-urlencoded query strings in the URL. The auth parameter is always passed as a multipart/form-data body part in the body of the request. In GET requests, any other parameters are also passed as application/x-www-form-urlencoded query strings. In POST requests other than requests to Execute Virtual Data Lake Commands, to invoke an agent (see below) or to perform an authorized get request (see below), parameters other than the command parameter and the sodaapp parameter are passed as multipart/form-data body parts in the body of the request.

Commands that are not processed by Soda applications are described on this page. To invoke them, omit the sodaapp parameter. Commands that are processed by Soda applications are described on the pages for the applications.

If the request succeeds (HTTP response code 200) then any data returned as the content of the response is a text string, a piece of HTML text, or the textual representation of a JSON object or array.

Virtual Data Lake Requests

The API enables the client to query and update the virtual data lake using the query and update commands. The client HTTP requests for these commands have a particular form. They are POST requests with multipart form encoded content conveying a set of values, optionally some metadata, optionally a reference URL, and optionally a one-time key. They do not have application/x-www-form-urlencoded query string parameters other than command.

One of the parts is named json and is a utf-8 string representation of a JSON object. For each parameter there is an attribute of this object whose name is the parameter's name.
Each non-binary value is represented by a JSON object with two attributes: type and value. They give the type of the object, which may be ITEM, BOOLEAN, INTEGER, REAL or TEXT, and a string representation of its value.
Each binary value is represented in the request by a value of the JSON object that is a string of the form bn where n is an integer. There is then a part named bn with application/octet-stream encoding that contains the binary value.
If metadata is supplied, then there is a part named meta that contains it.
If a reference URL is supplied, then there is a part named refurl that contains it.
If a one-time key is supplied, then there is a part named one-time-key that contains it.

Authorization

There are two ways that an API request can be authorized.

It can be made within an authorized session. This is a session in which a user has logged in, established their identity, and successfully claimed to work at a particular access level. The request is processed at this access level. Such a request is typically made by a script executing in the user's web client.
The request parameters can include a valid credential and key supplied in the auth parameter. The request is processed at the access level associated with the credential. Such a request is typically made by a program that is not executing under direct control of a user.

Add Block

Add an empty block to a page at the end of a set of blocks.

Method

POST

Command

add_block

Other Parameters

page - the identifier of the page that will contain the block
blocks - the identifier of the set of blocks on the page that the block is to be added to
width - the block width
app - the app that displays the content of the block. This parameter need not be present. If it is absent, the block content consists of text, graphics, and views.
auth - a string representation of a JSON object containing a credential attribute whose value is the item identifier of a credential, and a key attribute whose value is the base-64 encoding of a key for the credential. Not required if the request is made in an authorized session.

Response

If the request succeeds a status of 200 is returned and the response is the HTML code of the div containing the block, with views expanded.

If the request is recognized but the content cannot be posted (for example because the session does not have access permission) an appropriate HTTP status code is returned and the response is a JSON object with one attribute:

error - a message describing the problem.

If the request is not recognized, for example because a parameter is missing, a status of 400 is returned.

Authorized Get Request

Perform an API call that could be invoked by an HTTPS GET request, possibly outside an authorized session. Authorization can be supplied in the request parameters. If authorization is not supplied then the request is performed at the lowest (public) level. Any API method described on this page that can be invoked by an HTTP GET request can be invoked by an Authorized Get Request.

Method

POST

Command

get

Other URL-Encoded Parameters

authorized_command - the command to be processed
the parameters taken by the authorized command

Multipart Form Data Parameters

The following can be supplied to authorize the request:

auth - a string representation of a JSON object containing a credential attribute whose value is the item identifier of a credential, and a key attribute whose value is the base-64 encoding of a key for the credential. Not required if the request is made in an authorized session.

Response

The response returned by the authorized command.

Copy Source Workspace

Copy a workspace of a source (not a subworkspace of another workspace) to another source or to a workspace in the same or another source.

Method

POST

Command

copy_source_workspace

Other Parameters

page - the identifier of the page on which the workspaces of the source are displayed
view - the identifier of the view showing the workspaces
segment - the identifier of the row of the view showing the workspace
targetparent - the identifier of the item representing the source or workspace to which the workspace is to be copied.
targetname - the name that the copied workspace is to have.
auth - a string representation of a JSON object containing a credential attribute whose value is the item identifier of a credential, and a key attribute whose value is the base-64 encoding of a key for the credential. Not required if the request is made in an authorized session.

Response

If the request succeeds a status of 200 is returned.

error - a message describing the problem.

If the request is not recognized, for example because a parameter is missing, a status of 400 is returned.

Copy Workspace Member

Copy a member of a workspace (a page, view, file or sub-workspace) to another workspace, or to the same workspace with another name or, if it is a sub-workspace, to create a main workspace of a source.

Method

POST

Command

copy_workspace_member

Other Parameters

page - the identifier of the page on which the workspace members are displayed
view - the identifier of the view showing the workspace members
segment - the identifier of the row of the view showing the member
targetparent - the identifier of the item representing the workspace to which the member is to be copied or, if it is a sub-workspace to be copied to a source, the identifier of the item representing te source.
targetname - the name that the copy is to have in the target workspace.
auth - a string representation of a JSON object containing a credential attribute whose value is the item identifier of a credential, and a key attribute whose value is the base-64 encoding of a key for the credential. Not required if the request is made in an authorized session.

Response

If the request succeeds a status of 200 is returned.

error - a message describing the problem.

If the request is not recognized, for example because a parameter is missing, a status of 400 is returned.

Create Item

Create an item.

Method

POST

Command

create_item

Other Parameters

source - the identification number of the source containing the item
pub - whether the item is to be public. If true, the item is created with the public access level, otherwise it is created with the access level of the requesting session.
auth - a string representation of a JSON object containing a credential attribute whose value is the item identifier of a credential, and a key attribute whose value is the base-64 encoding of a key for the credential. Not required if the request is made in an authorized session.

Response

If the request succeeds a status of 200 is returned and the response is a JSON object with one attribute:

item - the identifier of the created item. For example: { "item": "1_-9223372036854775772" }

If the request is recognized but the content cannot be returned an appropriate HTTP status code is returned and the response is a JSON object with one attribute:

error - a message describing the problem.

If the request is not recognized, for example because a parameter is missing, a status of 400 is returned.

Create Triple

Create a triple that does not already exist. If a triple with the given subject, verb, and object already exists, no action will be taken and the request will succeed. Otherwise, an attempt will be made to create a triple with the given subject, verb, and object, and the request will succeed if the triple is created.

Method

POST

Command

create_triple

Other Parameters

subject - the identifier of the item that is to be the subject of the triple
verb - the identifier of the item that is to be the verb of the triple
object_type - the type of the object of the triple: ITEM, BOOLEAN, INTEGER, REAL, TEXT, or BINARY
object - the object of the triple. How it is represented depends on its type. ITEM objects are represented by their identifiers. True BOOLEAN objects are represented by "true" (ignoring case); false boolean objects are represented by any other values. INTEGER and REAL objects are represented by their base 10 textual representations. TEXT objects are represented by text strings. BINARY objects are represented by byte arrays.
auth - a string representation of a JSON object containing a credential attribute whose value is the item identifier of a credential, and a key attribute whose value is the base-64 encoding of a key for the credential. Not required if the request is made in an aurgorized session.

Response

If the request succeeds a status of 200 is returned.

If the request is recognized but the content cannot be returned an appropriate HTTP status code is returned and the response is a JSON object with one attribute:

error - a message describing the problem.

If the request is not recognized, for example because a parameter is missing, a status of 400 is returned.

Create Unique Triple

Ensure that there is only one triple with the given subject and verb, and that it has the given object. If a triple with the given subject, verb, and object already exists, any other triples with that subject and verb will be deleted, and the request will succeed. Otherwise, an attempt will be made to create a triple with the given subject, verb, and object, and to delete any other triples with that subject and verb, and the request will succeed if the triple is created and the other triples (if any) are deleted.

Method

POST

Command

create_uniuque_triple

Other Parameters

subject - the identifier of the item that is to be the subject of the triple
verb - the identifier of the item that is to be the verb of the triple
object_type - the type of the object of the triple: ITEM, BOOLEAN, INTEGER, REAL, TEXT, or BINARY
object - the object of the triple. How it is represented depends on its type. ITEM objects are represented by their identifiers. True BOOLEAN objects are represented by "true" (ignoring case); false boolean objects are represented by any other values. INTEGER and REAL objects are represented by their base 10 textual representations. TEXT objects are represented by text strings. BINARY objects are represented by byte arrays.
auth - a string representation of a JSON object containing a credential attribute whose value is the item identifier of a credential, and a key attribute whose value is the base-64 encoding of a key for the credential. Not required if the request is made in an authorized session.

Response

If the request succeeds a status of 200 is returned.

If the request is recognized but the content cannot be returned an appropriate HTTP status code is returned and the response is a JSON object with one attribute:

error - a message describing the problem.

If the request is not recognized, for example because a parameter is missing, a status of 400 is returned.

Delete Block

Delete a block. If the block has a draft, this is deleted also.

Method

POST

Command

delete_block

Other Parameters

block - the identifier of the block
auth - a string representation of a JSON object containing a credential attribute whose value is the item identifier of a credential, and a key attribute whose value is the base-64 encoding of a key for the credential. Not required if the request is made in an authorized session.

Response

If the request succeeds a status of 200 is returned.

If the request is recognized but the block cannot be deleted (for example because the session does not have access permission) an appropriate HTTP status code is returned and the response is a JSON object with one attribute:

error - a message describing the problem.

If the request is not recognized, for example because a parameter is missing, a status of 400 is returned.

Delete Block Draft

Delete the draft of a block if it has one. If the block does not have a draft, no action is taken and the request succeeds.

Method

POST

Command

delete_block_draft

Other Parameters

block - the identifier of the block
auth - a string representation of a JSON object containing a credential attribute whose value is the item identifier of a credential, and a key attribute whose value is the base-64 encoding of a key for the credential. Not required if the request is made in an authorized session.

Response

If the request succeeds a status of 200 is returned.

If the request is recognized but the draft cannot be deleted (for example because the session does not have access permission) an appropriate HTTP status code is returned and the response is a JSON object with one attribute:

error - a message describing the problem.

If the request is not recognized, for example because a parameter is missing, a status of 400 is returned.

Delete Item

Delete an item.

Method

POST

Command

delete_item

Other Parameters

item - the identifier of the item to be deleted
auth - a string representation of a JSON object containing a credential attribute whose value is the item identifier of a credential, and a key attribute whose value is the base-64 encoding of a key for the credential. Not required if the request is made in an authorized session.

Response

If the request succeeds a status of 200 is returned

If the request is recognized but the content cannot be returned an appropriate HTTP status code is returned and the response is a JSON object with one attribute:

error - a message describing the problem.

If the request is not recognized, for example because a parameter is missing, a status of 400 is returned.

Execute Virtual Data Lake Commands

Execute a list of virtual data lake commands.

Method

POST

Command

vdl_exec

Other Parameters

The request body is an input stream containing the UTF-8 text of a JSON array, which is passed to a Virtual Data Lake Executor.

Response

If the request succeeds a status of 200 is returned and the response is a JSON array giving the map of values assigned to handles returned by the Executor. Each member of the array is a JSON object with three attributes:

name - the handle that is the key to a map entry
type: the type of the datum that is the value of the map entry
value: the value of the datum (an item identifier, boolen, number, string, or byte array, depending on the type).

If the request is not recognized, for example because the request body is not a JSON array, a status of 400 is returned.

If the request is recognized but cannot be executed, a status of 409 is returned.

Get Block Draft

Get the stored draft of a block.

Method

GET

Command

get_block_draft

Other Parameters

block - the identifier of the block

Response

If the request succeeds a status of 200 is returned and the response is the HTML code of the div containing the draft of the block. If the block content is generated by an app, its format depends on the app. If it is not generated by an app, it is the HTML code to display the block content, with views expanded.

If the request is recognized but the content cannot be returned an appropriate HTTP status code is returned and the response is a JSON object with one attribute:

error - a message describing the problem.

In particular, if the block does not have a stored draft, a status of 404 (not found) is returned.

If the request is not recognized, for example because a parameter is missing, a status of 400 is returned.

Get Help Text

Get the help text for a topic.

Method

GET

Command

get_help_text

Other Parameters

topic - the title of the topic

Response

If the request succeeds a status of 200 is returned and the response is the HTML code of the help text for the topic.

If the request is recognized but the content cannot be returned an appropriate HTTP status code is returned and the response is a JSON object with one attribute:

error - a message describing the problem.

If the request is not recognized, for example because a parameter is missing, a status of 400 is returned.

Get Named Item

Get the identifier of a named item.

Method

GET

Command

get_named_item

Other Parameters

source - the identification number of the source containing the item
name - the name of the item

Response

If the request succeeds a status of 200 is returned and the response is a JSON object with one attribute:

item - the identifier of the named item. For example: { "item": "1_-9223372036854775772" }

If the request is recognized but the content cannot be returned an appropriate HTTP status code is returned and the response is a JSON object with one attribute:

error - a message describing the problem.

If the request is not recognized, for example because a parameter is missing, a status of 400 is returned.

Get Rows From View

List the rows of a view, in display order.

Method

GET

Command

get_rows_from_view

Other Parameters

page - the identifier of a page on which a view is displayed
view - the identifier of the view

Response

If the request succeeds a status of 200 is returned and the response is a JSON array of JSON objects, each of which has two attributes:

id - the identifier of a row
fields - the fields of the row.

Each fields attribute is a JSON object with two attributes:

name - the name of the field
values - the values of the field.

Each values attribute is a JSON array of objects, each of which gives a datum that is a value of the field, and has two attributes:

type: the type of the datum
value: the value of the datum (an item identifier, boolen, number, string, or byte array, depending on the type).

If the request is recognized but cannot be actioned (for example because the session does not have access permission) an appropriate HTTP status code is returned and the response is a JSON object with one attribute:

error - a message describing the problem.

If the request is not recognized, for example because a parameter is missing, a status of 400 is returned.

Invoke Agent

Invoke an agent to perform an action. The agent must be one that is registered in the Soda system, and the caller's access level must be superior to the access level registered for the agent.

Method

POST

Command

invoke_agent

Parameters

request_url - the url to invoke the agent. This MUST take the form agent_URL/[action_name][:port] where action_name is a string of alphanumeric characters and port is a port number.
The parameters required by the agent to perform the action.

The request_url parameter is passed as an application/x-www-form-urlencoded query string in the URL The parameters required by the agent are passed as multipart/form-data body parts in the body of the request.

Response

If the agent invocation succeeds a status of 200 is returned, and the response is the textual response returned by the agent. (Depending on the agent, this might be plain text, HTML text, the textual representation of a JSON object, or text in some other format.) If the agent invocation fails, because the agent rejects or fails to process the input, or if communication with the agent fails, a suitable error status is returned, and the response is a message describing the problem.

List Access Levels

List the access levels that are visible to the requester. The access levels are listed with their names in alphabetical order.

Method

GET

Command

list_access_levels

Other Parameters

None.

Response

A JSON array of objects, each with three attributes:

id - the identifier of an access level
name - the name of the identified access level
writable - true if the requester has write access to the access level.

List Files In Workspace

List the files in a given workspace that are visible to the requester. The files are listed with their names in alphabetical order.

Method

GET

Command

list_workspace_files

Other Parameters

workspace - the identifier of a workspace

Response

A JSON array of objects, each with three attributes:

id - the identifier of an uploaded file that is a member of the workspace
name - the name of the identified file
writable - true if the requester has write access to the file.

List Identity Providers

List the identity providers that are visible to the requester. The identity providers are listed with their names in alphabetical order.

Method

GET

Command

list_identity_providers

Other Parameters

None.

Response

A JSON array of objects, each with two attributes:

id - the identifier of an identity provider
name - the name of the identity provider

List Images In Workspace

List the images in a given workspace that are visible to the requester. The images are listed with their names in alphabetical order. A thumbnail is supplied for each image.

Method

GET

Command

list_workspace_images

Other Parameters

workspace - the identifier of a workspace

Response

A JSON array of objects, each with three attributes:

id - the identifier of an uploaded file that is an image and is a member of the workspace
name - the name of the identified file
thumbnail - a Base64-encoded image that is a thumbnail of the identified image.

List Item Types

List the item types that are visible to the requester. The types are listed with their names in alphabetical order.
An item type is defined either a by source or by a view that defines items. For a type defined by a source, the items of the type are the named items of the source. For a type defined by a view, the items of the type are the items defined by the view.

Method

GET

Command

list_item_types

Other Parameters

None.

Response

A JSON array of objects, each with two attributes:

id - the identifier of an item type. For a type defined by a source, this is the identifier of the source item of the source, and its source number is the long integer that identifies the source. For a type defined by a view, this is the identifier of the item that represents the view.
name - the name of the item type. For a type defined by a source, this is the name of the source. For a type defined by a view, it is the name of the view.

List Items of Type

List the items of a given item type that are visible to the requester, who is using a page to enter data. The items are listed with their names in alphabetical order.

Method

GET

Command

list_items_of_type

Other Parameters

type - the identifier of an item type
page - the identifier of the item representing the page that the user is using to enter data

Response

A JSON array of objects, each with two attributes:

id - the identifier of an item of the given type
name - the name of the item.

List Named Items

List the named items that are visible to the requester. The named items are listed with their names in alphabetical order.

Method

GET

Command

list_named_items

Other Parameters

None.

Response

A JSON array of objects, each with two attributes:

id - the identifier of a named item
name - the name of the named item

List Pages In Workspace

List the pages in a given workspace that are visible to the requester. The pages are listed with their names in alphabetical order.

Method

GET

Command

list_workspace_pages

Other Parameters

workspace - the identifier of a workspace

Response

A JSON array of objects, each with three attributes:

id - the identifier of a page that is a member of the workspace
name - the name of the identified page
writable - true if the requester has write access to the page.

List Registered Apps

List the names of the apps that are registered in the system. The names are listed in alphabetical order.

Method

GET

Command

list_registered_apps

Other Parameters

None

Response

A JSON array of strings, which are the names of the apps that are registered in the system.

List Sub-workspaces of a Workspace

List the sub-workspaces of a given workspace that are visible to the requester. The sub-workspaces are listed with their names in alphabetical order.

Method

GET

Command

list_workspace_workspaces

Other Parameters

workspace - the identifier of a workspace

Response

A JSON array of objects, each with three attributes:

id - the identifier of a workspace that is a member of the workspace (and therefore a sub-workspace of it)
name - the name of the identified sub-workspace
writable - true if the requester has write access to the sub-workspace.

List View Actions

List the actions of a view that are visible to the requester. The actions are listed with their names in alphabetical order.

Method

GET

Command

list_view_actions

Other Parameters

view - the identifier of a view

Response

A JSON array of strings, which are the names of the actions of the view.

List View Unknowns

List the unknowns of a view that are visible to the requester. The unknowns are listed with their names in alphabetical order.

Method

GET

Command

list_view_unknowns

Other Parameters

view - the identifier of a view

Response

A JSON array of strings, which are the names of the unknowns of the view.

List View Unknowns and Actions

List the unknowns and actions of a view that are visible to the requester. The unknowns are listed first, with their names in alphabetical order, then the actions are listed, with their names in alphabetical order.

Method

GET

Command

list_view_unknowns_and_actions

Other Parameters

view - the identifier of a view

Response

A JSON array of strings, which are the names of the unknowns and actions of the view.

List Views In Workspace

List the views in a given workspace that are visible to the requester. The views are listed with their names in alphabetical order.

Method

GET

Command

list_workspace_views

Other Parameters

workspace - the identifier of a workspace

Response

A JSON array of objects, each with three attributes:

id - the identifier of a view that is a member of the workspace
name - the name of the identified view
writable - true if the requester has write access to the view.

List Workspace Members

List the members of a given workspace that are visible to the requester. The members are listed with their names in alphabetical order.

Method

GET

Command

list_workspace_members

Other Parameters

workspace - the identifier of a workspace

Response

A JSON array of objects, each with three attributes:

id - the identifier of a view that is a member of the workspace
name - the name of the identified view
writable - true if the requester has write access to the view.

List Workspaces

List the workspaces that are visible to the requester. All visible workspaces are listed, including workspaces that are sub-workspaces of other workspaces. The workspaces are listed with their names in alphabetical order.

Method

GET

Command

list_workspaces

Other Parameters

None.

Response

A JSON array of objects, each with three attributes:

id - the identifier of a workspace
name - the name of the identified workspace
writable - true if the requester has write access to the workspace.

Log In

Log the user in.

Method

POST

Command

Other Parameters

provider - the identifier of the item representing the identity provider that is to establish the user's identity. This parameter must be present.
level - the identifier of the access level that the user should have after his identity is established. This parameter need not be present: if it is absent then the user will have the public access level.
auth - a string representation of a JSON object containing a credential attribute whose value is the item identifier of a credential, and a key attribute whose value is the base-64 encoding of a key for the credential. This is not usually required, as the user will be be authenticated by the identity provider when the request is processed, but will be required if the provider or level item is not publicly visible and the request is not made in an authorized session.

Response

If the request succeeds a status of 200 is returned, and the response is a JSON object with zero or more of the following attributes. The othercontent attribute may only be present if the viewcontent attribute is present. If no attributes are present, the client should reload the page.

title - text to be set as the page title.
viewcontent - the HTML text of the view to be displayed.
othercontent - A JSON array giving HTML text to replace other page content.
goto - a URL from which a new page is to be loaded (this may be a redirect to an identity provider).

Each element of the othercontent array is a JSON object with two attributes:

divid - the identifier of an HTML div whose content is to be replaced
content - the replacement HTML text.

error - a message describing the problem.

If the request is not recognized, for example because a parameter is missing, a status of 400 is returned.

Move Block

Move a block to a position just before another block of the same class, or to the end of the blocks of that class.

Method

POST

Command

move_block

Other Parameters

block - the identifier of the item representing the block to be moved
insert_before_block - the identifier of the item representing the block that the moved block is to be inserted before, or zero if the block is to be moved to the end of the set of blocks of its class
auth - a string representation of a JSON object containing a credential attribute whose value is the item identifier of a credential, and a key attribute whose value is the base-64 encoding of a key for the credential. Not required if the request is made in an authorized session.

Response

If the request succeeds a status of 200 is returned.

If the request is recognized but the block cannot be moved (for example because the session does not have access permission) an appropriate HTTP status code is returned and the response is a JSON object with one attribute:

error - a message describing the problem.

If the request is not recognized, for example because a parameter is missing, a status of 400 is returned.

Move Row

Move a row of a ranked displayed view to a position just before another row of the view, or to the end of the view.

The view must be a view that defines items and have a rank unknown, whose values are integers that are the display ranks of the values of its item definition key.

Method

POST

Command

move_row

Other Parameters

page - the identifier of the page on which the view containing the rows is displayed
view - the identifier of the view containing the row
row - the identifier of the row to be moved
insert_before_row - the identifier of the row that the moved row is to be inserted before, or zero if the row is to be moved to the end of the view
auth - a string representation of a JSON object containing a credential attribute whose value is the item identifier of a credential, and a key attribute whose value is the base-64 encoding of a key for the credential. Not required if the request is made in an authorized session.

Response

If the request succeeds a status of 200 is returned.

If the request is recognized but the row cannot be moved (for example because the session does not have access permission) an appropriate HTTP status code is returned and the response is a JSON object with one attribute:

error - a message describing the problem.

If the request is not recognized, for example because a parameter is missing, a status of 400 is returned.

Move Workspace Member

Move a member of a workspace (a page, view, file or sub-workspace) to another workspace, or to the same workspace with another name.

Method

POST

Command

move_workspace_member

Other Parameters

page - the identifier of the page on which the workspace members are displayed
view - the identifier of the view showing the workspace members
segment - the identifier of the row of the view showing the member
targetworkspace - the identifier of the item representing the workspace to which the member is to be moved.
targetname - the name that the moved member is to have in the target workspace or source.
auth - a string representation of a JSON object containing a credential attribute whose value is the item identifier of a credential, and a key attribute whose value is the base-64 encoding of a key for the credential. Not required if the request is made in an authorized session.

Response

If the request succeeds a status of 200 is returned.

error - a message describing the problem.

If the request is not recognized, for example because a parameter is missing, a status of 400 is returned.

Post File to Workspace

Post a file to a workspace.

Method

POST

Command

post_workspace_file

Other Parameters

workspace - the identifier of the workspace
file_name - the name of the file in the workspace
file - the uploaded file
auth - a string representation of a JSON object containing a credential attribute whose value is the item identifier of a credential, and a key attribute whose value is the base-64 encoding of a key for the credential. Not required if the request is made in an authorized session.

Response

If the request succeeds a status of 200 is returned and the response is a JSON object with one attribute:

link - the location of the uploaded file. For example: { "link": "/path/to/image.jpg" }

If the request is recognized but the file cannot be added (for example because a workspace member with the given name already exists) a status of 409 is returned and the response is a JSON object with one attribute:

error - a message describing the problem.

If the request is not recognized, for example because a parameter is missing, a status of 400 is returned.

Prepare Move Or Copy

Obtain a form for copying a source main workspace or for moving or copying a workspace member.

Method

GET

Command

prepare_move_or_copy

Other Parameters

segment - the identifier of the row showing the main workspace on the source home page or showing the workspace member on the workspace page.

Response

If the request succeeds a status of 200 is returned and the response is the HTML code of a form for specifying the move or copy operation. The form will, when submitted, generate a Copy Source Workspace API request, a Move Workspace Member API request, or a Copy Workspace Member API request,.

error - a message describing the problem.

If the request is not recognized, for example because a parameter is missing, a status of 400 is returned.

Query

Perform a virtual data lake query.

The request is passed to the virtual data lake, and the response returned by the virtual data lake is returned to the caller. They are as defined for the Virtual Data Lake API.

Method

POST

Command

query

Save Block Draft

Save a draft of a block.

Method

POST

Command

save_block_draft

Other Parameters

block - the identifier of the block
content - if the block content is generated by an app, its format depends on the app. If it is not generated by an app, it is the HTML code to display the block, with view specifications instead of expanded views.
width - the block width
auth - a string representation of a JSON object containing a credential attribute whose value is the item identifier of a credential, and a key attribute whose value is the base-64 encoding of a key for the credential. Not required if the request is made in an authorized session.

Response

If the request succeeds a status of 200 is returned.

If the request is recognized but the draft cannot be saved (for example because the session does not have access permission) an appropriate HTTP status code is returned and the response is a JSON object with one attribute:

error - a message describing the problem.

If the session has public access level, which will happen if it has expired due to inactivity, a status of 403 is returned with the error message "Not logged in".

If the request is not recognized, for example because a parameter is missing, a status of 400 is returned.

Set Access Level

Set the user's access level.

Method

POST

Command

set_access_level

Other Parameters

level - the identifier of the access level to be set.
auth - a string representation of a JSON object containing a credential attribute whose value is the item identifier of a credential, and a key attribute whose value is the base-64 encoding of a key for the credential. Not required if the request is made in an authorized session.

Response

title - text to be set as the page title.
viewcontent - the HTML text of the view to be displayed.
othercontent - A JSON array giving HTML text to replace other page content.

Each element of the content array is a JSON object with two attributes:

divid - the identifier of an HTML div whose content is to be replaced
content - the replacement HTML text.

error - a message describing the problem.

If the request is not recognized, for example because a parameter is missing, a status of 400 is returned.

Source Connect

Connect a source

Method

POST

Command

source_connect

Other Parameters

source - the identifier of the row showing the source on the sources page.
auth - a string representation of a JSON object containing a credential attribute whose value is the item identifier of a credential, and a key attribute whose value is the base-64 encoding of a key for the credential. Not required if the request is made in an authorized session.

Response

If the request succeeds a status of 200 is returned.

error - a message describing the problem.

If the request is not recognized, for example because a parameter is missing, a status of 400 is returned.

Source Disconnect

Disconnect a source

Method

POST

Command

source_disconnect

Other Parameters

source - the identifier of the row showing the source on the sources page.
auth - a string representation of a JSON object containing a credential attribute whose value is the item identifier of a credential, and a key attribute whose value is the base-64 encoding of a key for the credential. Not required if the request is made in an authorized session.

Response

If the request succeeds a status of 200 is returned.

error - a message describing the problem.

If the request is not recognized, for example because a parameter is missing, a status of 400 is returned.

Update

Perform a virtual data lake update.

The request is passed to the virtual data lake, and the response returned by the virtual data lake is returned to the caller. They are as defined for the Virtual Data Lake API.

Method

POST

Command

update

Update Block

Update a block by changing its content or width.

Method

POST

Command

update_block

Other Parameters

block - the identifier of the block
content - if the block content is generated by an app, its format depends on the app. If it is not generated by an app, it is the HTML code to display the block, with view specifications instead of expanded views.
width - the block width
auth - a string representation of a JSON object containing a credential attribute whose value is the item identifier of a credential, and a key attribute whose value is the base-64 encoding of a key for the credential. Not required if the request is made in an authorized session.

Response

If the request succeeds a status of 200 is returned and the response is the HTML code of the div containing the block, with views expanded.

error - a message describing the problem.

If the request is not recognized, for example because a parameter is missing, a status of 400 is returned.

View Add

Add data using a view.

Note that, as well as adding data shown by user-defined views, this method can add sources, source workspaces, and workspace members, which are shown by the sys/sources view, the sys/workspaces view, and the sys/workspace-members view.

Method

POST

Command

view_add

Other Parameters

page - the identifier of the page on which the view is displayed
view - the identifier of the view. This will either be the identifier of the item that represents the view, or a string such as "unknowns" or "constraints" identifying a system view.
segment - the identifier of the part of the view that is to have data added to it. This might for example identify a set of fields that are to have values added in a tabular view that does not require all fields to have values. It may be null if there is only one part of the view that can have data added to it.
auth - a string representation of a JSON object containing a credential attribute whose value is the item identifier of a credential, and a key attribute whose value is the base-64 encoding of a key for the credential. Not required if the request is made in an authorized session.
data values - the data values to be added using the view. The name of each such parameter is the name of a field of the view prefixed by "val". (This avoids conflict in case a field is named "page", "block", etc.)

Response

title - text to be set as the page title.
viewcontent - the HTML text of the view to be displayed.
othercontent - A JSON array giving HTML text to replace other page content.

Each element of the othercontent array is a JSON object with two attributes:

divid - the identifier of an HTML div whose content is to be replaced
content - the replacement HTML text.

error - a message describing the problem.

If the request is not recognized, for example because a parameter is missing, a status of 400 is returned.

View Delete

Delete data using a view.

Note that, as well as deleting data shown by user-defined views, this method can delete sources, source workspaces, and workspace members, which are shown by the sys/sources view, the sys/workspaces view, and the sys/workspace-members view.

Method

POST

Command

view_delete

Other Parameters

page - the identifier of the page on which the view is displayed
view - the identifier of the view. This will either be the identifier of the item that represents the view, or a string such as "unknowns" or "constraints" identifying a system view.
segment - the identifier of the part of the view that is to have data deleted. This might for example identify a row of a tabular view or a set of fields in a row. It MUST clearly define which values are to be deleted. It can only be null if the view has only one set of values that can be deleted.
auth - a string representation of a JSON object containing a credential attribute whose value is the item identifier of a credential, and a key attribute whose value is the base-64 encoding of a key for the credential. Not required if the request is made in an authorized session.

Response

If the request succeeds a status of 200 is returned, and the response is a JSON object with zero or more of the following attributes. The othercontent attribute may only be present if the viewcontent attribute is present. If no attributes are present, the client should reload the page.

title - text to be set as the page title.
viewcontent - the HTML text of the view to be displayed.
othercontent - A JSON array giving HTML text to replace other page content.

Each element of the othercontent array is a JSON object with two attributes:

divid - the identifier of an HTML div whose content is to be replaced
content - the replacement HTML text.

error - a message describing the problem.

If the request is not recognized, for example because a parameter is missing, a status of 400 is returned.

View Edit

Update data using a view.

Note that, as well as updating data shown by user-defined views, this method can update sources, source workspaces, and workspace members, which are shown by the sys/sources view, the sys/workspaces view, and the sys/workspace-members view.

Method

POST

Command

view_edit

Other Parameters

page - the identifier of the page on which the view is displayed
view - the identifier of the view. This will either be the identifier of the item that represents the view, or a string such as "unknowns" or "constraints" identifying a system view.
segment - the identifier of the part of the view that is to have data updated. This might for example identify a row of a tabular view or a set of fields in a row. It MUST clearly define which values are to be replaced by the posted values. It can only be null if the view has only one set of values that can be updated.
auth - a string representation of a JSON object containing a credential attribute whose value is the item identifier of a credential, and a key attribute whose value is the base-64 encoding of a key for the credential. Not required if the request is made in an authorized session.
data values - the updated data values to be posted using the view. The name of each such parameter is the name of a field of the view prefixed by "val". (This avoids conflict in case a field is named "page", etc.)

Response

title - text to be set as the page title.
viewcontent - the HTML text of the view to be displayed.
othercontent - A JSON array giving HTML text to replace other page content.

Each element of the othercontent array is a JSON object with two attributes:

divid - the identifier of an HTML div whose content is to be replaced
content - the replacement HTML text.

error - a message describing the problem.

If the request is not recognized, for example because a parameter is missing, a status of 400 is returned.

View Prepare Add

Obtain a form for adding data using a view

Method

GET

Command

view_prepare_add

Other Parameters

page - the identifier of the page on which the view is displayed
view - the identifier of the view. This will either be the identifier of the item that represents the view, or a string such as "unknowns" or "constraints" identifying a system view.
sodawritelevel - the identifier of the access level that a user must have in order to change data using the view.
segment - the identifier of the part of the view that is to have data added to it. This might for example identify a set of fields that are to have values added in a tabular view that does not require all fields to have values. It may be null if there is only one part of the view that can have data added to it.
sodaviewselector - a parameter that can be set as a page assignment to affect the view display.

Response

If the request succeeds a status of 200 is returned and the response is the HTML code of a form for entry of the data. The form will, when submitted, generate a view_add API request.

error - a message describing the problem.

If the request is not recognized, for example because a parameter is missing, a status of 400 is returned.

View Prepare Edit

Obtain a form for updating data using a view

Method

GET

Command

view_prepare_edit

Other Parameters

page - the identifier of the page on which the view is displayed
view - the identifier of the view. This will either be the identifier of the item that represents the view, or a string such as "unknowns" or "constraints" identifying a system view.
sodawritelevel - the identifier of the access level that a user must have in order to change data using the view.
segment - the identifier of the part of the view that is to have data updated. This might for example identify a row of a tabular view or a set of fields in a row. It MUST clearly define which values would be replaced by posted values. It can only be null if the view has only one set of values that can be updated.
sodaviewselector - a parameter that can be set as a page assignment to affect the view display.

Response

If the request succeeds a status of 200 is returned and the response is the HTML code of a form for entry of the data. The form will, when submitted, generate a view_edit API request.

error - a message describing the problem.

If the request is not recognized, for example because a parameter is missing, a status of 400 is returned.