Standard Request¶

A number of endpoints require a request packet in order to work properly.

The request is a JSON string containing two or three values:

command
options
data

The request must always contain a command key-value pair and one or both of the options and data pairs.

Command¶

The request must always contain a command key-value pair. The value identifies the desired operation. For example:

{
    "command": "get"
}

Possible values include:

Value	Description
get	Get data from a Repository, Entity or Business Rule
add	Add data to a Repository, Entity or Business Rule
edit	Update data in a Repository, Entity or Business Rule
run	Run an analysis of data in a Repository, Entity or Business Rule

Options¶

The value will be a JSON string containing options for the operation specified by the Command. The contents of this value are particular to each endpoint and operation, but many include items like a where clause, or key patterns.

Endpoints that return non-trivial amounts of data conform to a standard set of options. These options allow filtering (where clause), sorting, paging, and clearing the cache. They can be used together in any combination to achieve the desired results. These options are described in more detail below.

Paging¶

The paging options allow the data to be returned in smaller chunks. This is essential when processing tables that contain non-trivial datasets. Paging the data increases responsiveness and performance, and allows the data to be processed without restrictions on memory size. These page options are also available in the URL, but we recommend that users keep their URLs as simple as possible and specify page information using this method instead. The paging options are:

Value	Description
pageStart	The row number to start the page from.
pageSize	The maximum number of rows to return starting from the row specified in the page option.

For example - get the first 65 rows of data:

{
    "command": "get",
    "options": {
        "pageStart": "1",
        "pageSize": "65",
    }
}

Filtering¶

Where Clause¶

The ‘where’ option allows a predicate to be specified that will filter the underlying data. The predicate is specified in terms of the TSS Server’s expression builder language, and all expression builder functions are available. Attribute names are to be specified in their humanised form.

Examples:

Display only those rows that have ‘Threshold’ (humanised name) greater than or equal to 10.

{
    "command": "get",
    "options": {
        "where": "Threshold >= 10"
    }
}

Using attributes where the humanised name has a space.

{
    "command": "get",
    "options": {
        "where": "'Fail Count' > 0"
    }
}

Using literal strings in the expression.

{
    "command": "get",
    "options": {
        "where": "Result = \"failed\""
    }
}

Using expression builder functions.

{
    "command": "get",
    "options": {
        "where": "CONTAINS(UPPER('Result'), \"FAIL\")"
    }
}

Keypattern Clause¶

The effect of ‘keypattern’ clause is to filter selected records to be those that match the specified keypattern pattern (i.e. to limit the output by specifying a keypattern.). It is desirable to allow the client to have more control over exactly which records are selected. This can be also improve the performance of the query by limiting the scope of the query. The pattern must form part of the primary key of the source.

For example - display only those rows that have keypattern “1 0 2” (i.e EntityID = 1, AttributeID = 0, SeqNo/RuleID = 2).

{
    "command": "get",
    "options": {
        "keypattern": "1 0 2"
    }
}

Keypatternlist Clause¶

The ‘keypatternlist’ clause filters selected records in similar way to the above ‘keypattern’, but allows clients to supply multiple key patterns to filter.

For example - display only those rows that match all of the following keypatterns:

{
    "command": "get",
    "options": {
        "keypatternlist": ["1", "2 0 1", "4", "5 0 1"]
    }
}

Keypatterns	Matching Rows
1	Rows where EntityID = 1
2 0 1	Rows where EntityID = 2 AttributeID = 0 and SeqNo/RuleID = 1
4	Rows where EntityID = 4
5 0 3	Rows where EntityID = 5 AttributeID = 0 and SeqNo/RuleID = 3

In Clause¶

The ‘in’ clause can also be used to limit the output.

For example - display only those rows where column name ‘actual_priority’ is set to 1 and ‘_actual_threshold’ is set to 10:

{
    "command": "get",
    "options": {
        "in": ["actual_priority 1", "_actual_threshold 10"]
    }
}

Columns¶

The ‘columns’ option allows the consumer to restrict or reorder the set of columns they want returned in the dataset. Restricting the number of columns can improve performance, especially for very wide views (e.g. business_rules), and can be used to structure the data more closely to the format required. The columns parameter requires each column’s columnised name to be specified in a JSON list. NOTE: If columns are specified, the HATEOAS URL links will be disabled, because it cannot be guaranteed the returned data will contain the information required to build these URLs.

For example:

{
    "command": "get",
    "options": {
        "columns": ["_ename", "actual_name", "_result","_actual_fraction"],
    }
}

Sorting¶

The ‘sort’ option allows the data to be sorted using one or more columns. The sort option contains a list of sort specifications that will be executed in the order they are specified. Each sort specification requires the columnName (columnised name) at a minimum, and will default to sorting ascending by each value. The full set of options is:

Value	Description	Default
columnName	The columnised name of the field to sort. This is the only mandatory field.	N/A
type	Whether to sort the data by its “value” or by its “length”	“value”
order	Whether to sort in “ascending” or “descending” order	“ascending”
unique	The resultset will contain only one record per value	false

For example:

{
    "command": "get",
    "options": {
        "sort": [
            {
                "columnName": "RULE_ID",
                "type": "value",
                "order": "ascending",
                "unique": true
            },
            {
                "columnName": "ENTITY_ID",
                "type": "length",
                "order": "descending",
                "unique": false
            }
        ]
    }
}

Cache¶

The cache option has only one valid argument: flush. When specified, the underlying cached information relating to the endpoint is deleted and recreated. This should be used whenever sorted or filtered data needs to be regenerated in order to pick up changes made to the database. This option should be used with care, as it can greatly increase the time taken to return the response.

For example:

{
    "command": "get",
    "options": {
        "where": "('Threshold'=100)",
        "cache": "flush"
    }
}

External JSON Format¶

A number of endpoints now support returning the underlying data rows in a JSON key/value pairs format. This allows access by different tools that requires the JSON data in a key/value pair instead of standard array of row data with columns names defined separately.

For example - get list of entities in external JSON format:

GET /api/repositories/test/entities?external=1

{
    "command": "get",
    "options": {
        "external": 1
    }
}

Parameter	Type	Purpose
external	int	Return rows as key/value pairs if set to 1 to support external clients; returns normal view data if not set.

When external JSON format is selected, the row data will be returned as JSON key/value pair.

Data¶

The value will be a JSON string containing the data for the operation specified by the Command. The contents of the value are particular to each endpoint and operation.

For example:

{
    "data": {
        "NAME": "January",
        "ENTITY": "1",
        "THRESHOLD": "10",
        "EXPRESSION": "<expr><text>'Sales Person' = 14</text><eq><var>Sales_person</var><int>14</int></eq></expr>",
        "ENABLED": "0"
    }
}

TSS REST API

Standard Request¶

Command¶

Options¶

Paging¶

Filtering¶

Where Clause¶

Keypattern Clause¶

Keypatternlist Clause¶

In Clause¶

Columns¶

Sorting¶

Cache¶

External JSON Format¶

Data¶

Table Of Contents