1. Introduction

This is the REST API documentation for TermWeb 4.0.6-5. Here you’ll find how to work with API, common techniques and what to expect to receive from endpoints.

For more TermWeb information see the interverbumtech.com.
For high level information and installation instructions please see the documentation site.
For a demo of TermWeb 4 please write to us info@interverbumtech.com.

2. Assumptions

This documentation assumes a basic knowledge of how REST APIs work. For basic tutorials on REST API we recommend visiting REST API Tutorial.

3. Getting started

This API provides access to a variety of different resources including the following:

Terms
Users
Dictionaries
Projects
Workflows
Stemming
Term decoration
…​etc

To start using it, you need to build your own REST API client. You can start building client by generating it. To generate client you can use our web services definition swagger.yml (for backward compatibility you can use old format swagger v2 swagger.json).

Service definition has been described by using OpenAPI Specification ver.3 (known as Swagger). For more information about this format please read this specification.

For better presentation of service definition you can use online swagger editor, which converts JSON or YAML files to human readable format https://editor.swagger.io/.

4. Authentication

TermWeb is using authentication token for securing API requests. This token for now must be sent in http header X-Auth-Token to all endpoints, except for /api/v4/login and /api/v4/system/features.

To obtain that token you need to use login endpoint.

POST /api/v4/login

Example request
curl 'https://localhost:8080/api/v4/login' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  --data-raw 'client=admin&username=alexey&password=secret&language=eng' \
  --compressed
Response
{
  "token": {
    "token": "0000111100001111000011110001110", (1)
    "expirationTime": 1601363809513 (2)
  },
  "errorMessage": null
}
1 token here is value which must be sent as header X-Auth-Token with each next request.
2 expirationTime date and time up to which the token will be valid. Value is number of milliseconds since Unix Epoch.

5. Data pagination

Almost all top-level API endpoints have support for bulk fetches via "list" API methods.

These list API methods share a common signature, taking some of these parameters: page, size, and sort.

By default, TermWeb is configured to limit requested page size by 500. To change that value you can configure TermWeb server, see TermWeb configuration.

Parameters
Parameter Description

size number

<optional>, default is 20
Page size, represents how many of objects can be returned

page number

<optional>, default is 0
Page number, represents from which position to start loading data, in other words offset equal to size * page.

sort string

<optional>, default is null
Order direction of returned data by some attribute, can accept most of object attributes for specific endpoint. For example: 'name', 'name,ASC', 'name,DESC'.

List response
Page object
{
  "content": [
    {
      "id": 12,
      "name": "Medical reference terminology"
    },
    {
      "id": 40,
      "name": "Wiki"
    },
    {
      "id": 61,
      "name": "Demo glossary"
    },
    {
      "id": 107,
      "name": "Wiki copy"
    },
    {
      "id": 108,
      "name": "Archive"
    }
  ],
  "last": false,
  "totalElements": 44,
  "totalPages": 9,
  "sort": null,
  "numberOfElements": 5,
  "first": true,
  "size": 5,
  "number": 0
}
Property Description

content Object[]

requested resources from endpoint

last boolean

indicates if this page is last with current search params

totalElements number

total amount of objects accessible from this endpoint

totalPages number

total number of pages available with current page size and total elements

sort string

current sort params, like 'name,ASC'

numberOfElements number

amount of objects returned with this page

first boolean

indicates if this page is first with current search params

size number

current page size

number number

current page number

6. Old objects vs. New objects

TermWeb right now is a hybrid app containing some old pages in Administration view.

Because of that we have two structures of Data Transfer Objects (DTO).

Old objects always have values for the following attributes:

  • oid, string

  • id, number

New objects don’t have the oid attribute (or it can be set to null). Additionally, new objects have another extra attribute: version.

Most of the DTOs containing converted attributes, like dictionary_oid, or client_oid will be represented by dictionary_id and client_id.

The oid attribute is mostly provided for backward compatibility and should not be used in most cases.

7. Versioning

To avoid concurrent modifications problems, we’re using optimistic locking method.

To achieve that we’re providing "version" attribute with our DTOs. This "version" attribute must be sent always with update requests.

For new objects please use attribute version, for old objects please use value of changed.time.

When object has been updated on server, and you’re updating old version of it, you’ll receive response with http code: 409 (Conflict).

8. Metadata

Most of objects provided by API endpoints have information when it was created and by whom or when it was changed.

Also worth to mention that all top level objects have client_id attribute which is always has same value for single tenant installations, but has different values in multi tenant installations. client_id must always present in objects metadata.

Metadata attributes
Object attribute Properties Description

created Object

id number

User id created that object

name string

User login created that object

fullName string

User full name created that object

time number

Created date and time in milliseconds since Unix Epoch

oid string

User oid created that object (provided for backward compatibility)

changed Object

id number

User id changed that object

name string

User login changed that object

fullName string

User full name changed that object

time number

Last change date and time in milliseconds since Unix Epoch

oid string

User oid changed that object (provided for backward compatibility)

client_id number

Client id where object is stored

9. Errors and status codes

TermWeb uses standard HTTP response codes to provide the status of an API request. In general: Codes in the 2xx range indicate success. Codes in the 4xx range indicate an error during processing of request (e.g., a required parameter was omitted, user don’t have enough of permissions, JSON object can’t be processed, etc.). Codes in the 5xx range indicate an error with TermWeb’s servers.

Some 4xx errors can be handled programmatically. Response body may include an error code and message which explains the error reported.

For security and privacy reasons some of endpoint methods can return 404 code instead of 403 to not disclose data stored in TermWeb.

HTTP code Description

200 - OK

Everything worked as expected

201 - Created

Create request has been successfully completed

202 - Accepted

Everything worked as expected, operation will continue in async mode

204 - No content

Object deletion complete, nothing to return

400 - Bad Request

Incorrect data has been submitted to endpoint method.

401 - Unauthorized

To process this request, request must contain authentication token. See Authentication.

403 - Forbidden

Current user doesn’t have enough permissions to perform this operation.

404 - Not found

Requested object with specific id or anything related to that object has not been found.
Requested objects which are marked as deleted, also will return 404 code unless, include-deleted param is not specified

405 - Method not allowed

Server can return this when you’re accessing a deleted experimental feature or providing an unsupported parameter.

409 - Conflict

Cannot update current version of object. Please merge your changes into new version of object and try to update it again. See Versioning.

422 - Unprocessable Entity

Can be returned when the server understands the request but cannot process it because an equal object already exists.

10. Date and time

All values representing date and time in JSON response sent from server is a number of milliseconds since January 1, 1970, 00:00:00 UTC represented by this value, or simply called Unix time (or milliseconds since Unix Epoch).

For example, to get proper value in JavaScript just create a new Date object:

const numberSinceUnixEpoch = 1601363809513;
const date = new Date(numberSinceUnixEpoch);
console.log(date.toString());

Date values must be provided as simple strings. Default format for dates is yyyy-MM-dd, e.g. 2020-07-20

Filters conditions can accept multiple formats: yyyy-MM-dd HH:mm:ss, yyyy-MM-dd HH:mm, yyyy-MM-dd, yyyyMMdd. Please note that these dates will be converted to the server’s time zone which is UTC by default.

11. User roles

TermWeb has four kinds of roles:

  • System Administrator - owner of installation with access to all clients. Can create new clients and doesn’t have any permission restrictions within any client.

  • Client Administrator - administrator for a single client. Can create and edit all other users except System administrators within their own client. Doesn’t have any permission restrictions within the client.

  • Dictionary Administrator - allows a user to administrate a specified dictionary. Allows user to change dictionary structure, workflows, projects etc.

  • User editor - allows the user to edit and update non-administrator user accounts.

Roles doesn’t have any database entities, only constant values: SYSADMIN, ADMIN, USEREDITOR, and dynamic values for dictionary administrators which combined from constant prefix and dictionary oid: DICTIONARY_ADMIN@ + <dictionary_oid>.

12. Object response formats

API endpoints can return objects in four different formats. Pick your format according to your needs.

Format key Description

ID

Search results will only contain object id and nothing else

SHORT

Search results will contain object id and some information like name and description. Useful for autocomplete searches and other things like this.

FULL Default

Search results will have all attributes, including id, name and metadata.

EDIT

Includes everything from FULL format plus extra objects needed for editing. This allows to speed up loading of all required objects for editing in one request.

13. API Reference

13.1. Authentication

13.1.1. Login

POST /api/v4/login

Description

Authenticates user in TermWeb and returns token.

Request documentation
Headers

Content-Type

application/x-www-form-urlencoded

Path parameters

Query parameters

Payload fields

client

<optional>, default is 'admin', or any other client login name in case of multitenant installation

username

user login

password

user password

language

<optional>, default is 'eng'

Example request
curl 'https://localhost:8080/api/v4/login' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  --data-raw 'client=admin&username=alexey&password=secret&language=eng' \
  --compressed
Response documentation
Headers

Content-Type

application/json;charset=UTF-8

Payload fields

token Object

{
  "token": "0000111100001111000011110001110", (1)
  "expirationTime": 1601363809513 (2)
}
1 token value which must be sent as header X-Auth-Token with each next request.
2 expirationTime date and time up to which the token will be valid. Value is number of milliseconds since Unix Epoch.

errorMessage string

Message in case of error

13.1.2. Logout

POST /api/v4/logout

Description

Ends user session in TermWeb and releases authentication token.

Request documentation
Headers

X-Auth-Token

Unexpired authentication token

13.1.3. Validate

GET /api/v4/validate

Description

Checks validity of current authentication token and returns result of that validation.

Request documentation
Headers

X-Auth-Token

Unexpired authentication token

Response documentation
Headers

Content-Type

application/application/json;charset=UTF-8

Payload fields

tokenValid boolean

true when token is still valid

13.1.4. Extend session

POST /api/v4/extend-session

Description

Checks if requested token is still valid and returns new expiration time in case of success, otherwise HTTP code 403.

Request documentation
Headers

X-Auth-Token

Unexpired authentication token

Response documentation
Headers

Content-Type

application/json;charset=UTF-8

Payload fields

expires number

date and time up to which the token will be valid. Value is number of milliseconds since Unix Epoch.

13.1.5. Switching client

POST /api/v4/switch-client

Description

In case of multitenant installation to start working with data from different client then current client you need switch that client for current authentication token or authenticate with different credentials.

To be able to switch client for user, that user must be mapped to that client or must be a system administrator.

Request documentation
Headers

X-Auth-Token

Unexpired authentication token

Content-Type

application/json;charset=UTF-8

Payload

Request body

Body must contain only one value – client_id

Response documentation
Headers

Content-Type

application/json;charset=UTF-8

Payload

User data Object

User data object specific to current user search settings for requested client

Example of User data from response
{
    "activeClientIds": [15],
    "clients": [{"oid": "1b5uct", "id": 34,…},…],
    "dictionaries": [{"oid": "eu5qu", "id": 181,…}, {"oid": "dr3sf", "id": 173,…}],
    "filters": [{"oid": "eq46e", "id": 583,…}],
    "isSystem": true,
    "permissions": {"filtersEnabled": true, "searchModesEnabled": true,…},
    "preferences": {"id": 111, "version": 0, "userId": 96,…},
    "roles": [{"oid": "ADMIN", "id": 1, "version": 1,,…},…],
    "selectedTermNames": {},
    "settings": {"oid": "doogf", "id": 96, "userOid": "doogc",…},
    "stagingAreas": [{"id": 231, "version": 4,…}, {"id": 232, "version": 4,…},…],
    "user": {"oid": "doogc", "id": 96, "created": {"time": 1571742852639, "fullName": ""},…}
}

13.2. System configuration

13.2.1. Clients endpoint

Description

Client object represents a set of data available only to users related to it. Users from other clients won’t be able to access that data unless system administrators provide it to them by giving mapping to that.

For single tenant installation this endpoint will provide only ability to edit default client object.

Major functions provided by this endpoint:

  • Only system administrators can edit clients

  • loginName - can contain only letters and digits, other values are not allowed.

  • loginName - should be unique for whole system

  • For existing client sysadmin can change only next fields: name, login name, max concurrent users, max concurrent guests, max user accounts, status.

  • For new client sysadmin also should be able to specify new administrator user credentials (login, full name, email, password). Interface should validate user password like in User editor component. Default values for login: admin, full name: Administrator.

  • API key should be shown as readonly string for existing client (for new client hide it).

  • System administrator should be able to generate new API key, for that render button right after API key with name 'Generate new API key'. When user presses on it, UI shows warning dialog which contains message, that all further connections with old API key won’t be able to login.

  • If Server license has limit on user accounts, then UI should not allow specify Max accounts value greater than available user limit.

  • If during Client creation maximum user value has been changed, then server will decrease max accounts automatically.

Clients list:
  • Filtering by name should work on two fields: login and full name.

  • System administrator should be able to sort list by Client name, login, users count, maxconcusers, maxconcguests, max accounts, status, created, modified.

  • System should be able to create new client

  • System administrator should be able to delete selected clients or client.

  • Deletion of client of current session should be not allowed.

DevNote:

to validate client login use /clients/find?loginName=

to generate new API key use /clients/generate-new-api-key/{clientId}

to get max possible value for max user count check property 'availableUserSlots' of License object.

Client DTO
Object attribute Description

name string

Unique name of client.

active boolean

Current status of client.

loginName string

Unique login name for client. May contain only Latin letters and numbers.

apiKey string

API key for current client. Used in integrations via webservices.
Visible only to system and client administrators.

maxUsers number

Maximum number of users which can be created in that client.

maxGuests number

Maximum number of current guests which can login and work to that client.

maxConcurrentUsers number

Maximum number of users in total (names users + guests) which can login and work concurrently with that client.

currentUsersNumber number

Current number of named users for that client.

adminUser User

Can be used only with create method. Administrator login for new client. Simplified version of User.
You can specify for that User only this attributes: username, email, and password.

id number

Client id.

oid string

Client oid. This is object id from old objects.

created Object

Metadata object containing information about creation

created.id number

User id created that object

created.name string

User login created that object

created.fullName string

User full name created that object

created.time number

Created date and time in milliseconds since Unix Epoch

created.oid string

User oid created that object (provided for backward compatibility)

changed Object

Metadata object containing information about last modification

changed.id number

User id changed that object

changed.name string

User login changed that object

changed.fullName string

User full name changed that object

changed.time number

Last change date and time in milliseconds since Unix Epoch

changed.oid string

User oid changed that object (provided for backward compatibility)

Available

GET /api/v4/clients/available

Description

Returns list of clients available for current authentication token.

Request documentation
Headers

X-Auth-Token

Unexpired authentication token

Response documentation
Headers

Content-Type

application/json;charset=UTF-8

Payload

body Client[]

Array of available clients of type Client DTO.

Generate new API key

POST /api/v4/clients/generate-new-api-key/{client-id}

Description

Resets old API key for client and creates new one.

Request documentation

Path parameters

client-id number

client id value

Response documentation

Headers

Content-Type

application/json;charset=UTF-8

Payload

body Client

JSON object of Client.

Find

GET /api/v4/clients/

Description

Finds clients with specified query parameters available to current user.

Request documentation

Query parameters

login-name string

<optional>, default is null
Filters clients with login name starting with provided value. Search will be case insensitive.

login-name-eq string

<optional>, default is null
Filters clients with login name equal to provided value ignoring case.

max-concurrent-users number

<optional>, default is null.
Looks for clients where maximum of concurrent users is equal to provided value.

max-user-accounts number

<optional>, default is null.
Looks for clients where maximum of user accounts is equal to provided value.

name string

<optional>, default is null
Filters clients with name starting with provided value. Search will be case insensitive.

name-eq string

<optional>, default is null
Filters clients with name equal to provided value ignoring case.

format enum

<optional>, default is 'FULL'
Response format for client objects, possible values are ID, SHORT, FULL, EDIT. See Formats.

include-deleted boolean

<optional>, default is false
When value is true TermWeb will include softly deleted objects to search results.
This function is available only to System or client administrators.

size number

<optional>, default is 20
Page size, represents how many of objects can be returned

page number

<optional>, default is 0
Page number, represents from which position to start loading data, in other words offset equal to size * page.

sort string

<optional>, default is null
Order direction of returned data by some attribute, can accept most of object attributes for specific endpoint. For example: 'name', 'name,ASC', 'name,DESC'.

Response documentation
Headers

Content-Type

application/json;charset=UTF-8

Payload

content Client[]

Found clients of type Client DTO.

last boolean

indicates if this page is last with current search params

totalElements number

total amount of objects accessible from this endpoint

totalPages number

total number of pages available with current page size and total elements

sort string

current sort params, like 'name,ASC'

numberOfElements number

amount of objects returned with this page

first boolean

indicates if this page is first with current search params

size number

current page size

number number

current page number

Row number

GET /api/v4/clients/rownum/{id}

Description

Finds rownumber of client with specified filter and sort parameters. Useful when you need to determine page where object is located after creation or update.

Request documentation

Path parameters

id number

Client id to look for

sort string

<optional>, default is null
Order direction of returned data by some attribute, can accept most of object attributes for specific endpoint. For example: 'name', 'name,ASC', 'name,DESC'.

Query parameters

login-name string

<optional>, default is null
Filters clients with login name starting with provided value. Search will be case insensitive.

login-name-eq string

<optional>, default is null
Filters clients with login name equal to provided value ignoring case.

max-concurrent-users number

<optional>, default is null.
Looks for clients where maximum of concurrent users is equal to provided value.

max-user-accounts number

<optional>, default is null.
Looks for clients where maximum of user accounts is equal to provided value.

name string

<optional>, default is null
Filters clients with name starting with provided value. Search will be case insensitive.

name-eq string

<optional>, default is null
Filters clients with name equal to provided value ignoring case.

format enum

<optional>, default is 'FULL'
Response format for client objects, possible values are ID, SHORT, FULL, EDIT. See Formats.

include-deleted boolean

<optional>, default is false
When value is true TermWeb will include softly deleted objects to search results.
This function is available only to System or client administrators.

Response documentation
Headers

Content-Type

application/json;charset=UTF-8

Payload

body number

Found row number for specified parameters, in case when nothing found return 0.

Get

GET /api/v4/clients/{id}

Description

Looks for client with specified id.

Request documentation

Path parameters

id number

Client id to look for

format enum

<optional>, default is 'FULL'
Response format for client objects, possible values are ID, SHORT, FULL, EDIT. See Formats.

include-deleted boolean

<optional>, default is false
When value is true TermWeb will include softly deleted objects to search results.
This function is available only to System or client administrators.

Response documentation

Headers

Content-Type

application/json;charset=UTF-8

Payload

body Client

JSON object of Client.

Create

POST /api/v4/clients/

Description

Creates new client from JSON data sent in payload.

Request documentation

Payload

body Client

JSON object of type Client DTO.

format enum

<optional>, default is 'FULL'
Response format for client objects, possible values are ID, SHORT, FULL, EDIT. See Formats.

Response documentation
Headers

Content-Type

application/json;charset=UTF-8

Payload

body Client

Created object of client.

Update

PUT /api/v4/clients/{id}

Description

Updates existing client from JSON data sent in payload.

Request documentation

Headers

Content-Type

application/json

Path parameters

id number

Id of Client which need to be updated

Payload

body Client

JSON object of type Client DTO. Value of id and oid attribute specified in payload will be ignored by server.
Don’t forget to include "version" attribute value.
Missing attributes in JSON object or null values will erase that value on server side.

format enum

<optional>, default is 'FULL'
Response format for client objects, possible values are ID, SHORT, FULL, EDIT. See Formats.

Response documentation
Headers

Content-Type

application/json;charset=UTF-8

Payload

body Client

Updated client object.

Partial update

PUT /api/v4/clients/partial/{id}

Description

It updates only specified parts of client from JSON data sent in payload. Unlike method Update, patch will only update values of object which are present in JSON without modifying other fields which are not present in JSON.

Request documentation

Path parameters

id number

Id of Client which need to be updated

Payload

body Client

JSON object of type Client DTO. Value of id and oid attribute specified in payload will be ignored by server.
Missing attributes in JSON object will be omitted. Fields in JSON object with null will be cleared.
Don’t forget to include "version" attribute value.

format enum

<optional>, default is 'FULL'
Response format for client objects, possible values are ID, SHORT, FULL, EDIT. See Formats.

Response documentation
Headers

Content-Type

application/json;charset=UTF-8

Payload

body Client

Patched client object.

Delete

DELETE /api/v4/clients/{id}

Description

Deletes client with specified id.

Request documentation

Path parameters

id number

Client id to delete

Response documentation
Headers

Content-Type

text/plain;charset=UTF-8

Status

code number

204 No Content in case of successful deletion

Delete async

DELETE /api/v4/clients/async/{id[]}

Description

Deletes clients with specified ids.
This operation may run asynchronous when deletion takes more than 15 seconds. In that case server will return http status code 202 Accepted.

Request documentation

Path parameters

id number[]

Client ids of clients to delete

Response documentation
Headers

Content-Type

application/json;charset=UTF-8

Status

code number

200 OK in case of successful deletion or 204 Accepted when operation is still deleting.

Payload attributes InvocationResult

result Map<number,boolean>

When operation has completed successfully, this result will contain map with entries where key is client id and value is boolean flag indicating result of deletion.

jobTaskId number

When operation went to asynchronous deletion, this value will have id of running job task. See JobTask.

13.2.2. API Synchronization settings endpoint

Description

In this UI administrators will be able to select a dictionary and see list of relevant languages/language variants with checkboxes. They will be able to select there which of these languages/language variants that are to be synchronized to the TermWeb Integrator and apply this setting to user groups.

A translator would thus install the TermWeb Integrator, enter the credentials and as they select dictionary for synchronization, only receive the relevant languages/language variants (locales) in Multiterm DB format (based on the setting in TermWeb as presented above). This will guarantee that they only see what they need to.

APISyncSettings DTO
Object attribute Description

name string

Unique name of API sync settings object.

description string

Description for API sync settings object.

active boolean

Current status of API sync settings object.

dictionaryId number

Dictionary id of the corresponding dictionary.

languages LangMapping[]

List of languages to which this API sync settings applied. See LangMapping.

groups GroupMapping[]

List of groups to which this API sync settings applied. See GroupMapping.

filter Filter

<optional>, Set of conditions applied to this API sync settings. See Filter.

clientId number

Client DTO id to which object belongs

id number

API synchronization settings id.

version number

API synchronization settings version number. Represents latest modification counter.

created Object

Metadata object containing information about creation

created.id number

User id created that object

created.name string

User login created that object

created.fullName string

User full name created that object

created.time number

Created date and time in milliseconds since Unix Epoch

created.oid string

User oid created that object (provided for backward compatibility)

changed Object

Metadata object containing information about last modification

changed.id number

User id changed that object

changed.name string

User login changed that object

changed.fullName string

User full name changed that object

changed.time number

Last change date and time in milliseconds since Unix Epoch

changed.oid string

User oid changed that object (provided for backward compatibility)

LangMapping
Object attribute Description

langCode string

Code of one of the languages from dictionary related to API sync settings.

regionCode string

Code of one of the region from language of dictionary related to API sync settings.

scriptCode string

Code of one of the script from language of dictionary related to API sync settings.

GroupMapping
Object attribute Description

groupId number

Group id.

Find

GET /api/v4/sync-settings/

Description

Finds API sync settings with specified query parameters available to current user.

Request documentation

Query parameters

dictionary_id number

<optional>, default is null.
Provide an id when you need to filter API sync settings objects related to specific dictionary.

client_id number

<optional>, default is equal to current client id related to authentication token.
[TIP] Reserved for future releases and can be omitted for now.

name string

<optional>, default is null
Filters API sync settings with name starting with provided value. Search will be case insensitive.

name-eq string

<optional>, default is null
Filters API sync settings with name equal to provided value ignoring case.

format enum

<optional>, default is 'FULL'
Response format for API sync settings objects, possible values are ID, SHORT, FULL, EDIT. See Formats.

include-deleted boolean

<optional>, default is false
When value is true TermWeb will include softly deleted objects to search results.
This function is available only to System or client administrators.

size number

<optional>, default is 20
Page size, represents how many of objects can be returned

page number

<optional>, default is 0
Page number, represents from which position to start loading data, in other words offset equal to size * page.

sort string

<optional>, default is null
Order direction of returned data by some attribute, can accept most of object attributes for specific endpoint. For example: 'name', 'name,ASC', 'name,DESC'.

Response documentation
Headers

Content-Type

application/json;charset=UTF-8

Payload

content APISyncSetting[]

Found API sync settings of type APISyncSettings.

last boolean

indicates if this page is last with current search params

totalElements number

total amount of objects accessible from this endpoint

totalPages number

total number of pages available with current page size and total elements

sort string

current sort params, like 'name,ASC'

numberOfElements number

amount of objects returned with this page

first boolean

indicates if this page is first with current search params

size number

current page size

number number

current page number

Row number

GET /api/v4/sync-settings/rownum/{id}

Description

Finds rownumber of API sync settings with specified filter and sort parameters. Useful when you need to determine page where object is located after creation or update.

Request documentation

Path parameters

id number

API synchronization settings id to look for

sort string

<optional>, default is null
Order direction of returned data by some attribute, can accept most of object attributes for specific endpoint. For example: 'name', 'name,ASC', 'name,DESC'.

Query parameters

dictionary_id number

<optional>, default is null.
Provide an id when you need to filter API sync settings objects related to specific dictionary.

client_id number

<optional>, default is equal to current client id related to authentication token.
[TIP] Reserved for future releases and can be omitted for now.

name string

<optional>, default is null
Filters API sync settings with name starting with provided value. Search will be case insensitive.

name-eq string

<optional>, default is null
Filters API sync settings with name equal to provided value ignoring case.

format enum

<optional>, default is 'FULL'
Response format for API sync settings objects, possible values are ID, SHORT, FULL, EDIT. See Formats.

include-deleted boolean

<optional>, default is false
When value is true TermWeb will include softly deleted objects to search results.
This function is available only to System or client administrators.

Response documentation
Headers

Content-Type

application/json;charset=UTF-8

Payload

body number

Found row number for specified parameters, in case when nothing found return 0.

Get

GET /api/v4/sync-settings/{id}

Description

Looks for API sync settings with specified id.

Request documentation

Path parameters

id number

API synchronization settings id to look for

format enum

<optional>, default is 'FULL'
Response format for API sync settings objects, possible values are ID, SHORT, FULL, EDIT. See Formats.

include-deleted boolean

<optional>, default is false
When value is true TermWeb will include softly deleted objects to search results.
This function is available only to System or client administrators.

Response documentation

Headers

Content-Type

application/json;charset=UTF-8

Payload

body APISyncSetting

JSON object of API synchronization settings.

Create

POST /api/v4/sync-settings/

Description

Creates new API sync settings from JSON data sent in payload.

Request documentation

Payload

body APISyncSetting

JSON object of type APISyncSettings.

format enum

<optional>, default is 'FULL'
Response format for API sync settings objects, possible values are ID, SHORT, FULL, EDIT. See Formats.

Response documentation
Headers

Content-Type

application/json;charset=UTF-8

Payload

body APISyncSetting

Created object of API sync settings.

Update

PUT /api/v4/sync-settings/{id}

Description

Updates existing API sync settings from JSON data sent in payload.

Request documentation

Headers

Content-Type

application/json

Path parameters

id number

Id of API synchronization settings which need to be updated

Payload

body APISyncSetting

JSON object of type APISyncSettings. Value of id and oid attribute specified in payload will be ignored by server.
Don’t forget to include "version" attribute value.
Missing attributes in JSON object or null values will erase that value on server side.

format enum

<optional>, default is 'FULL'
Response format for API sync settings objects, possible values are ID, SHORT, FULL, EDIT. See Formats.

Response documentation
Headers

Content-Type

application/json;charset=UTF-8

Payload

body APISyncSetting

Updated API sync settings object.

Partial update

PUT /api/v4/sync-settings/partial/{id}

Description

It updates only specified parts of API sync settings from JSON data sent in payload. Unlike method Update, patch will only update values of object which are present in JSON without modifying other fields which are not present in JSON.

Request documentation

Path parameters

id number

Id of API synchronization settings which need to be updated

Payload

body APISyncSetting

JSON object of type APISyncSettings. Value of id and oid attribute specified in payload will be ignored by server.
Missing attributes in JSON object will be omitted. Fields in JSON object with null will be cleared.
Don’t forget to include "version" attribute value.

format enum

<optional>, default is 'FULL'
Response format for API sync settings objects, possible values are ID, SHORT, FULL, EDIT. See Formats.

Response documentation
Headers

Content-Type

application/json;charset=UTF-8

Payload

body APISyncSetting

Patched API sync settings object.

Delete

DELETE /api/v4/sync-settings/{id}

Description

Deletes API sync settings with specified id.

Request documentation

Path parameters

id number

API synchronization settings id to delete

Response documentation
Headers

Content-Type

text/plain;charset=UTF-8

Status

code number

204 No Content in case of successful deletion

Delete async

DELETE /api/v4/sync-settings/async/{id[]}

Description

Deletes API sync settings with specified ids.
This operation may run asynchronous when deletion takes more than 15 seconds. In that case server will return http status code 202 Accepted.

Request documentation

Path parameters

id number[]

API synchronization settings ids of API sync settings to delete

Response documentation
Headers

Content-Type

application/json;charset=UTF-8

Status

code number

200 OK in case of successful deletion or 204 Accepted when operation is still deleting.

Payload attributes InvocationResult

result Map<number,boolean>

When operation has completed successfully, this result will contain map with entries where key is API sync settings id and value is boolean flag indicating result of deletion.

jobTaskId number

When operation went to asynchronous deletion, this value will have id of running job task. See JobTask.

13.2.3. Job tasks endpoint

Description

Endpoint provides information about asynchronous tasks launched by current user.

JobTask DTO
Object attribute Description

jobId number

Job object id to which this task is related. Internal use only.

ordinal number

Serial number of this task in job. Internal use only. Internal use only.

parentTaskId number

Job task parent id. Tasks can launch subtasks. Internal use only.

launchedAt number

Launch date and time in milliseconds since Unix Epoch.

launchedBy number

User id launched this job.

launchedByLocale number

Locale used by user during launch of job.

finishedAt number

Finish date and time in milliseconds since Unix Epoch

stoppedBy number

User id which stopped this job. Filled only when job has been interrupted.

processed number

Number of processed objects by this task.

processedSuccessfully LangMapping[]

Number of successfully processed objects without failures by this task.

total GroupMapping[]

Total amount of objects to process by this task.

status enum

Job task status. Possible values are CREATED, RUNNING, PAUSED, HALTED, FAILURE, STOPPED, FINISHED, TERMINATED. See Job Task Statuses.

id number

Job task id.

version number

Job task version number. Represents latest modification counter.

JobTaskStatus
Status Description

CREATED string

JobTask has been created for execution. Params are stored in DB.

RUNNING string

JobTask is executed by one of the ExecutorService. In case of crash job can stuck in that status.

PAUSED string

JobTask has been paused by user call.

HALTED string

JobTask has been halted by system call (e.g. shutdown). TermWeb will restore halted tasks on next run.

FAILURE string

During execution of code in JobTask something went wrong. Execution has been stopped.

STOPPED string

JobTask has been stopped by user call.

FINISHED string

JobTask has been successfully completed.

TERMINATED string

JobTask execution has been interrupted by another JobTask (e.g. sequential update of Dictionary ES index).

JobTaskResult DTO
Object attribute Description

jobId number

Job object id to which this task is related to. Internal use only.

jobTaskId number

Job task id to which this results related to.

parentJobTaskId number

Job task parent id. Tasks can launch subtasks. Internal use only.

createdAt number

Launch date and time in milliseconds since Unix Epoch.

results Map<string,Object>

User id launched this job.

id number

Job task id.

version number

Job task version number. Represents latest modification counter.

Active

GET /api/v4/jobtasks/active

Description

Looks for running asynchronous tasks launched by current user.

Request documentation
Headers

X-Auth-Token

Unexpired authentication token

Response documentation

Headers

Content-Type

application/json;charset=UTF-8

Payload

body JobTask[]

An array of found job tasks.

Status

GET /api/v4/jobtasks/status/{id}

Description

Looks for status of job task with specified id.

Request documentation

Path parameters

id number

Job task id to look for

Response documentation

Headers

Content-Type

application/json;charset=UTF-8

Payload

body JobTask

JSON object of Job task.

Results

GET /api/v4/jobtasks/results/{id}

Description

Looks for results of job task with specified id.
Internal use only.

Request documentation

Path parameters

id number

Job task id to look for

Response documentation

Headers

Content-Type

application/json;charset=UTF-8

Payload

body JobTaskResult[]

An array JSON objects of type Job Task Result.

13.2.4. License endpoint

The endpoint provides two methods to view license and to update it.

License DTO
Object attribute Description

validLicense boolean

true when license is valid. false will be returned when license has expired or user entered invalid or expired license text in update method.

owner string

Name of owner for that license, like Big Company Name

expireDate number

Expiration date and time in milliseconds since Unix Epoch until license is valid.

clients number

Number of clients which can be created in this installation by using this license. 0 means "Unlimited"

guestAccount boolean

true when this installation allows to use guest account.

maxAccounts number

Maximum number of named users. 0 means "Unlimited"

maxConcurrentUsers number

Maximum number of users which can use system concurrently (including guest users).

maxConcurrentGuests number

Maximum number of guest users which can use system concurrently.

xmlRpcApi boolean

true when TermWeb can provide XML-RPC API.

soapApi boolean

true when TermWeb can provide SOAP webservices API.

ldapSupport boolean

true when TermWeb can authenticate users via LDAP.

samlSupport boolean

true when TermWeb support SSO authentication with SAML2.0 support.

availableUserSlots number

Left number of users for current license which can be created in the system.

• Get license information

GET /api/v4/system/license

Request documentation
Headers

X-Auth-Token

Unexpired authentication token

Response documentation
Headers

Content-Type

application/json;charset=UTF-8

Payload

body License

JSON object of License.

• Update license

POST /api/v4/system/license

Request documentation
Payload

body string

license text

Response documentation
Headers

Content-Type

application/json;charset=UTF-8

Payload

body License

JSON object of License.

Http status

200 OK

License is valid and successfully applied

400 Bad request

License is invalid or expired.

13.2.5. Features endpoint

This endpoint provides single method with information about what is enabled and what settings in current TermWeb installation.
Mostly in use by TermWeb UI client.
Unauthorized access allowed here.

GET /api/v4/system/features

Response documentation
Headers

Content-Type

application/json;charset=UTF-8

Payload attributes

DEVELOPMENT boolean

true when current installation is running in development mode.

SESSION_TIMEOUT number

Server setting for how long authentication token will be valid. Value in seconds.

GUEST_AUTO_DISABLED boolean

true when login is enabled for anonymous guests.

GUEST_LOGIN_ENABLED Map<string,Map<string,Object>

When TermWeb has anonymous guests enabled, here will be values about that guests.
Internal use only.

MULTIPLE_CLIENT boolean

true when installation is multitenant.

MULTIVALUED_SEPARATOR string

Separator for multivalued picklists.

ALWAYS_WILDCARD boolean

Default search mode for input string. When true search results will always do substring search.

MAX_FILE_SIZE number

Maximum file size accepted by TermWeb. Size in bytes.

VERSION string

Version of running TermWeb.

BUILD_DATETIME number

Date when build has been made of running TermWeb.

13.3. Users administration

13.3.1. Users endpoint

Description

Edit user component:

Only system administrators can edit clients section for users (clients section for sysadmins is not available because sysadmin always can login to any client).

System administrator can’t edit their own set of clients or roles.

Client administrator can’t edit their own set of roles.

Client administrator can’t assign 'System administrator role'.

Client administrator can’t change System administrator users.

Normal users should not be able to edit or create users at all. An exception are normal API users that should be able to update at least their own object (password, fullname, email).

In the interface for new users there should be an option 'send password reset link in email'. In the case that password fields should remain unknown, server should send email with reset link after successfully saving changes.

When editing existing user should present checkbox 'User must change password at next logon' (even for current, just for case when two administrators sharing account).

Password requirement is configured on server side and should be validated by UI client and by server. (Server should provide api method for password strength setting, see System → Administrator Tools → Password strength)

Users list:

Filtering by name should work on two fields: username and full name.

User must be able to sort list by username, fullname, user roles, status, created/modified dates.

List should include external users from other clients as well.

Guest users should not be visible in the list.

System administrator should be able to assign client to multiple users from list.

Client or system administrator should be able to delete multiple or single users from list.

User should not be able to delete himself.

System or client administrator should not be able to delete last client administrator.

Client administrator should not be able to delete any system administrator

Users with role 'Edit users' should be able to edit users, but not delete or create.

DevNote:

don’t allow modification of user type through api.

for expireDate server is waiting format 'YYYY-MM-DD'

to get password settings from server use /users/password-settings

to assign multiple clients for multiple users use PUT /users/clients and dto AssignClientRequest.

To summarise what users can do. User edit component: Self edit for every type of user:

full name

username

email

password

change password at next logon System administrator:

full name

username

email

password

expires on

active status

change password at next logon

clients

roles (all roles accessible) Client administrator cannot edit System administrator Client administrator can edit next properties for client admins and regular users

full name

username

email

password

expires on

active status

change password at next logon

roles (Administrator, User editor, dictionary admin) User editor cannot edit Client administrators or System administrators User editor:

full name

username

email

password

expires on

active status

change password at next logon

User list actions:

User cannot delete himself or change clients for himself

System administrator can change other users clients

Client administrator can’t delete system administrators or change their clients

User editor cannot create or delete users

User editor cannot export or import users

User DTO
Object attribute Description

username string

Unique username per client of user used as login. May contain only Latin letters and numbers.

fullName string

Full name of user.

email string

User email.

title string

User’s title.

expDate number

Expiration date and time in milliseconds since Unix Epoch when user be deactivated.

type enum

User type. Usually you cannot specify it on creation or update.
Internal use mostly.
Possible values are: NORMAL, GUEST, GUEST_AUTOLOGIN, GUEST_CLIENT_AUTOLOGIN, EXTSYSADMIN, LEGACY, ROLEBASED.

active boolean

Status of user. When false user cannot access TermWeb.

password string

[Edit format] provide new value when you need to change password. Otherwise, send this string: ****** to keep password unchanged.
Password must fulfill validation password, otherwise server will reject new value, see Password settings.

confirmPassword string

[Edit format] provide new value when you need to change password. Otherwise, send this string: ****** to keep password unchanged.
Password must fulfill validation password, otherwise server will reject new value, see Password settings.

roles string[]

[Edit format] Role oids assigned to this user. See User roles.

clientIds number[]

[Edit format] List client ids to which user is mapped to.

groups Group[]

[Edit format] An array of Group objects to which user belongs to.

sendNotificationEmail true

[Edit format] Set to true when user need to reset password. User will receive reset link via email.

forcePasswordChange boolean

[Edit format] Set to true when user must change it on next login.
Visible to user which forced to change password.

clientId number

Client DTO id to which object belongs

id number

User id.

oid string

User oid. This is object id from old objects.

deleted number

true when object has been marked as deleted in database.

created Object

Metadata object containing information about creation

created.id number

User id created that object

created.name string

User login created that object

created.fullName string

User full name created that object

created.time number

Created date and time in milliseconds since Unix Epoch

created.oid string

User oid created that object (provided for backward compatibility)

changed Object

Metadata object containing information about last modification

changed.id number

User id changed that object

changed.name string

User login changed that object

changed.fullName string

User full name changed that object

changed.time number

Last change date and time in milliseconds since Unix Epoch

changed.oid string

User oid changed that object (provided for backward compatibility)

Import users and groups

POST /api/v4/users/import

Description

Imports users and groups from compatible XML file with specified settings.

Request documentation

Headers

Content-Type

multipart/form-data

Payload fields

file (binary)

Multipart data containing file contents.

fileName string

Name of uploaded file

overwrite-user boolean

<optional>, default is false, set to true when you want to override existing users with same username.
When false TermWeb will create new user with name having index in the end, like 'username_1'.

overwrite-group boolean

<optional>, default is false, set to true when you want to override existing groups with same name.
When false TermWeb will create new group with name having index in the end, like 'Group name _1'.

Response documentation

Headers

Content-Type

application/json;charset=UTF-8

Payload UserImportResult

userCount number

Number of user created with import.

groupCount number

Number of groups created with import.

Export users and groups

GET /api/v4/users/export

Description

Returns all users with password hashes and groups, and their mappings in XML file.

Request documentation
Headers

X-Auth-Token

Unexpired authentication token

Response documentation
Headers

Content-Type

application/xml

Content-Disposition

attachment; filename="some_file_name"

Content-Length

Generated file length

Payload

body

XML file containing

Assign clients

PUT /api/v4/users/assign-clients/

Description

Updates client mapping for specified users in request.
Any previous existing mappings will be removed with completion of that operation.

Request documentation

Headers

Content-Type

application/json

X-Auth-Token

Unexpired authentication token

Payload fields

users number[]

An array of users ids to update their client mappings.

clients number[]

An array of clients ids to which users must me mapped.

Response documentation

Headers

Content-Type

application/json;charset=UTF-8

Payload

body number

number of successfully updated users

Password settings

GET /api/v4/users/password-settings

Description

Returns password settings for this TermWeb installation.
This settings are configured by system administrator in Admin view → System → Administrator tools → Password strength.

Request documentation
Headers

X-Auth-Token

Unexpired authentication token

Response documentation
Headers

Content-Type

application/json;charset=UTF-8

Payload fields

regExp string

String containing regular expression for password validation.

msg string

String message for user when password is not matching to regular expression.

GuestSettings DTO
Object attribute Description

enabled boolean

true when guest user authentication is enabled.

username string

Login name for guest user.

password string

Password for guest user.
Password must fulfill validation password, otherwise server will reject new value, see Password settings.

loginMethod enum

Setting which configures how guests will login into TermWeb. Possible values are: NORMAL, GUEST_AUTOLOGIN, GUEST_CLIENT_AUTOLOGIN.

autoAlwaysDisabled boolean

true when login method GUEST_AUTOLOGIN is not available for current client (only Default Client can have this setting).

enableFilters boolean

true when guests can create filters. Filters created by guests will be temporary and deleted after logout.

enableSearchModes boolean

true when guests can modify search settings in Search View.

enableGridView boolean

true when guests can access to Grid Views.

enableCommenting boolean

true when guests can leave comments on Concepts and Terms.

Get guest settings

GET /api/v4/users/guest

Description

Returns guest settings for current client of authentication token.

Guests page should repeat functionality of old one. Here are the major functions:

  • guest login can be enabled or disabled

  • guest password should be validated as any other password in the system. Except one thing - it should be visible as regular text field.

  • guest login can be changed to other value, user name should be unique for current client.

  • login method one of three possible values (Automatic (always), Automatic (client), Normal

  • "Automatic (always)" should be visible and can be enabled only for default client (Admin).

loginMethod value mapping:

  • UserType.GUEST_AUTOLOGIN – Automatic (Always)

  • UserType.GUEST_CLIENT_AUTOLOGIN – Automatic (when client is specified in URL)

  • UserType.NORMAL – Normal

to disable selection of "Automatic (always)" check the property in GuestSettings.autoAlwaysDisabled

Request documentation
Headers

X-Auth-Token

Unexpired authentication token

Response documentation
Headers

Content-Type

application/json;charset=UTF-8

Payload

body GuestSettings

JSON object of GuestSettings.

Update guest settings

PUT /api/v4/users/guest

Description

Updates guest settings for current client of authentication token.
See Get guest settings for description.

Request documentation
Headers

X-Auth-Token

Unexpired authentication token

Payload

body GuestSettings

Updates for Guest settings in JSON object of GuestSettings.

Response documentation

Status

code number

200 OK in case of successful update.

Find

GET /api/v4/users/

Description

Finds users with specified query parameters available to current user.

Request documentation

Query parameters

login string

<optional>, default is null
Synonym for username attribute.
Filters users with username name starting with provided value. Search will be case insensitive.

full-name string

<optional>, default is null
Filters users with full name starting with provided value ignoring case.

client_id number

<optional>, default is equal to current client id related to authentication token.
[TIP] Reserved for future releases and can be omitted for now.

name string

<optional>, default is null
Filters users with username starting with provided value. Search will be case insensitive.

name-eq string

<optional>, default is null
Filters users with username equal to provided value ignoring case.

format enum

<optional>, default is 'FULL'
Response format for user objects, possible values are ID, SHORT, FULL, EDIT. See Formats.

include-deleted boolean

<optional>, default is false
When value is true TermWeb will include softly deleted objects to search results.
This function is available only to System or client administrators.

size number

<optional>, default is 20
Page size, represents how many of objects can be returned

page number

<optional>, default is 0
Page number, represents from which position to start loading data, in other words offset equal to size * page.

sort string

<optional>, default is null
Order direction of returned data by some attribute, can accept most of object attributes for specific endpoint. For example: 'name', 'name,ASC', 'name,DESC'.

Response documentation
Headers

Content-Type

application/json;charset=UTF-8

Payload

content User[]

Found users of type User.

last boolean

indicates if this page is last with current search params

totalElements number

total amount of objects accessible from this endpoint

totalPages number

total number of pages available with current page size and total elements

sort string

current sort params, like 'name,ASC'

numberOfElements number

amount of objects returned with this page

first boolean

indicates if this page is first with current search params

size number

current page size

number number

current page number

Row number

GET /api/v4/users/rownum/{id}

Description

Finds rownumber of user with specified filter and sort parameters. Useful when you need to determine page where object is located after creation or update.

Request documentation

Path parameters

id number

User id to look for

sort string

<optional>, default is null
Order direction of returned data by some attribute, can accept most of object attributes for specific endpoint. For example: 'name', 'name,ASC', 'name,DESC'.

Query parameters

login string

<optional>, default is null
Synonym for username attribute.
Filters users with username name starting with provided value. Search will be case insensitive.

full-name string

<optional>, default is null
Filters users with full name starting with provided value ignoring case.

client_id number

<optional>, default is equal to current client id related to authentication token.
[TIP] Reserved for future releases and can be omitted for now.

name string

<optional>, default is null
Filters users with username starting with provided value. Search will be case insensitive.

name-eq string

<optional>, default is null
Filters users with username equal to provided value ignoring case.

format enum

<optional>, default is 'FULL'
Response format for user objects, possible values are ID, SHORT, FULL, EDIT. See Formats.

include-deleted boolean

<optional>, default is false
When value is true TermWeb will include softly deleted objects to search results.
This function is available only to System or client administrators.

Response documentation
Headers

Content-Type

application/json;charset=UTF-8

Payload

body number

Found row number for specified parameters, in case when nothing found return 0.

Get

GET /api/v4/users/{id}

Description

Looks for user with specified id.

Request documentation

Path parameters

id number

User id to look for

format enum

<optional>, default is 'FULL'
Response format for user objects, possible values are ID, SHORT, FULL, EDIT. See Formats.

include-deleted boolean

<optional>, default is false
When value is true TermWeb will include softly deleted objects to search results.
This function is available only to System or client administrators.

Response documentation

Headers

Content-Type

application/json;charset=UTF-8

Payload

body User

JSON object of User.

Create

POST /api/v4/users/

Description

Creates new user from JSON data sent in payload.

Request documentation

Payload

body User

JSON object of type User.

format enum

<optional>, default is 'FULL'
Response format for user objects, possible values are ID, SHORT, FULL, EDIT. See Formats.

Response documentation
Headers

Content-Type

application/json;charset=UTF-8

Payload

body User

Created object of user.

Update

PUT /api/v4/users/{id}

Description

Updates existing user from JSON data sent in payload.

Request documentation

Headers

Content-Type

application/json

Path parameters

id number

Id of User which need to be updated

Payload

body User

JSON object of type User. Value of id and oid attribute specified in payload will be ignored by server.
Don’t forget to include "version" attribute value.
Missing attributes in JSON object or null values will erase that value on server side.

format enum

<optional>, default is 'FULL'
Response format for user objects, possible values are ID, SHORT, FULL, EDIT. See Formats.

Response documentation
Headers

Content-Type

application/json;charset=UTF-8

Payload

body User

Updated user object.

Partial update

PUT /api/v4/users/partial/{id}

Description

It updates only specified parts of user from JSON data sent in payload. Unlike method Update, patch will only update values of object which are present in JSON without modifying other fields which are not present in JSON.

Request documentation

Path parameters

id number

Id of User which need to be updated

Payload

body User

JSON object of type User. Value of id and oid attribute specified in payload will be ignored by server.
Missing attributes in JSON object will be omitted. Fields in JSON object with null will be cleared.
Don’t forget to include "version" attribute value.

format enum

<optional>, default is 'FULL'
Response format for user objects, possible values are ID, SHORT, FULL, EDIT. See Formats.

Response documentation
Headers

Content-Type

application/json;charset=UTF-8

Payload

body User

Patched user object.

Delete

DELETE /api/v4/users/{id}

Description

Deletes user with specified id.

Request documentation

Path parameters

id number

User id to delete

Response documentation
Headers

Content-Type

text/plain;charset=UTF-8

Status

code number

204 No Content in case of successful deletion

Delete async

DELETE /api/v4/users/async/{id[]}

Description

Deletes users with specified ids.
This operation may run asynchronous when deletion takes more than 15 seconds. In that case server will return http status code 202 Accepted.

Request documentation

Path parameters

id number[]

User ids of users to delete

Response documentation
Headers

Content-Type

application/json;charset=UTF-8

Status

code number

200 OK in case of successful deletion or 204 Accepted when operation is still deleting.

Payload attributes InvocationResult

result Map<number,boolean>

When operation has completed successfully, this result will contain map with entries where key is user id and value is boolean flag indicating result of deletion.

jobTaskId number

When operation went to asynchronous deletion, this value will have id of running job task. See JobTask.

13.3.2. Groups endpoint

Description
Group DTO
Object attribute Description

name string

Unique name per client of group.

description string

Text describing that group.

timeout number

Session timeout setting for users of this Group.

pwdChange number

Number of days till the next password change for users of this Group.

viewsMap Map<number,Set<number>

A map containing assigned Views to Dictionary. One dictionary can have multiple assigned views. Map structure is: Map<dictionary_id, Set<view_id>>.

filterMap Map<number,number>

A map containing Filter applied to search results from <<doc-dto-dictionary,Dictionary> for users of that Group}.

type enum

A group type. System attribute. Can’t be changed via API. Possible values are: NORMAL, ALL_USERS, GUEST. Default value is: NORMAL. ALL_USERS and GUEST is created by TermWeb automatically.

Groups of type GUEST always don’t have access to API.

langCode3 string

When group is Language Group, this value will have three-letter code from ISO 639.

hasApiAccess boolean

true when members of that group can have API access.

currentUsersNumber number

[Edit format] Number of group members.

groupMembers User[]

[Edit format] An array of Users in short format assigned to that group.

clientId number

Client DTO id to which object belongs

id number

Group id.

oid string

Group oid. This is object id from old objects.

deleted number

true when object has been marked as deleted in database.

created Object

Metadata object containing information about creation

created.id number

User id created that object

created.name string

User login created that object

created.fullName string

User full name created that object

created.time number

Created date and time in milliseconds since Unix Epoch

created.oid string

User oid created that object (provided for backward compatibility)

changed Object

Metadata object containing information about last modification

changed.id number

User id changed that object

changed.name string

User login changed that object

changed.fullName string

User full name changed that object

changed.time number

Last change date and time in milliseconds since Unix Epoch

changed.oid string

User oid changed that object (provided for backward compatibility)

Find

GET /api/v4/groups/

Description

Finds groups with specified query parameters available to current user.

Request documentation

Query parameters

include-all boolean

<optional>, default is true
Includes "All users" group to search results.

include-guest boolean

<optional>, default is true
Includes "Guests" group to search results.

include-private boolean

<optional>, default is false
Includes "Owner" group to search results (used mostly in visibility settings).

client_id number

<optional>, default is equal to current client id related to authentication token.
[TIP] Reserved for future releases and can be omitted for now.

name string

<optional>, default is null
Filters groups with name starting with provided value. Search will be case insensitive.

name-eq string

<optional>, default is null
Filters groups with name equal to provided value ignoring case.

format enum

<optional>, default is 'FULL'
Response format for group objects, possible values are ID, SHORT, FULL, EDIT. See Formats.

include-deleted boolean

<optional>, default is false
When value is true TermWeb will include softly deleted objects to search results.
This function is available only to System or client administrators.

size number

<optional>, default is 20
Page size, represents how many of objects can be returned

page number

<optional>, default is 0
Page number, represents from which position to start loading data, in other words offset equal to size * page.

sort string

<optional>, default is null
Order direction of returned data by some attribute, can accept most of object attributes for specific endpoint. For example: 'name', 'name,ASC', 'name,DESC'.

Response documentation
Headers

Content-Type

application/json;charset=UTF-8

Payload

content Group[]

Found groups of type Group.

last boolean

indicates if this page is last with current search params

totalElements number

total amount of objects accessible from this endpoint

totalPages number

total number of pages available with current page size and total elements

sort string

current sort params, like 'name,ASC'

numberOfElements number

amount of objects returned with this page

first boolean

indicates if this page is first with current search params

size number

current page size

number number

current page number

Row number

GET /api/v4/groups/rownum/{id}

Description

Finds rownumber of group with specified filter and sort parameters. Useful when you need to determine page where object is located after creation or update.

Request documentation

Path parameters

id number

Group id to look for

sort string

<optional>, default is null
Order direction of returned data by some attribute, can accept most of object attributes for specific endpoint. For example: 'name', 'name,ASC', 'name,DESC'.

Query parameters

include-all boolean

<optional>, default is true
Includes "All users" group to search results.

include-guest boolean

<optional>, default is true
Includes "Guests" group to search results.

include-private boolean

<optional>, default is false
Includes "Owner" group to search results (used mostly in visibility settings).

client_id number

<optional>, default is equal to current client id related to authentication token.
[TIP] Reserved for future releases and can be omitted for now.

name string

<optional>, default is null
Filters groups with name starting with provided value. Search will be case insensitive.

name-eq string

<optional>, default is null
Filters groups with name equal to provided value ignoring case.

format enum

<optional>, default is 'FULL'
Response format for group objects, possible values are ID, SHORT, FULL, EDIT. See Formats.

include-deleted boolean

<optional>, default is false
When value is true TermWeb will include softly deleted objects to search results.
This function is available only to System or client administrators.

Response documentation
Headers

Content-Type

application/json;charset=UTF-8

Payload

body number

Found row number for specified parameters, in case when nothing found return 0.

Get

GET /api/v4/groups/{id}

Description

Looks for group with specified id.

Request documentation

Path parameters

id number

Group id to look for

format enum

<optional>, default is 'FULL'
Response format for group objects, possible values are ID, SHORT, FULL, EDIT. See Formats.

include-deleted boolean

<optional>, default is false
When value is true TermWeb will include softly deleted objects to search results.
This function is available only to System or client administrators.

Response documentation

Headers

Content-Type

application/json;charset=UTF-8

Payload

body Group

JSON object of Group.

Create

POST /api/v4/groups/

Description

Creates new group from JSON data sent in payload.

Request documentation

Payload

body Group

JSON object of type Group.

format enum

<optional>, default is 'FULL'
Response format for group objects, possible values are ID, SHORT, FULL, EDIT. See Formats.

Response documentation
Headers

Content-Type

application/json;charset=UTF-8

Payload

body Group

Created object of group.

Update

PUT /api/v4/groups/{id}

Description

Updates existing group from JSON data sent in payload.

Request documentation

Headers

Content-Type

application/json

Path parameters

id number

Id of Group which need to be updated

Payload

body Group

JSON object of type Group. Value of id and oid attribute specified in payload will be ignored by server.
Don’t forget to include "version" attribute value.
Missing attributes in JSON object or null values will erase that value on server side.

format enum

<optional>, default is 'FULL'
Response format for group objects, possible values are ID, SHORT, FULL, EDIT. See Formats.

Response documentation
Headers

Content-Type

application/json;charset=UTF-8

Payload

body Group

Updated group object.

Partial update

PUT /api/v4/groups/partial/{id}

Description

It updates only specified parts of group from JSON data sent in payload. Unlike method Update, patch will only update values of object which are present in JSON without modifying other fields which are not present in JSON.

Request documentation

Path parameters

id number

Id of Group which need to be updated

Payload

body Group

JSON object of type Group. Value of id and oid attribute specified in payload will be ignored by server.
Missing attributes in JSON object will be omitted. Fields in JSON object with null will be cleared.
Don’t forget to include "version" attribute value.

format enum

<optional>, default is 'FULL'
Response format for group objects, possible values are ID, SHORT, FULL, EDIT. See Formats.

Response documentation
Headers

Content-Type

application/json;charset=UTF-8

Payload

body Group

Patched group object.

Delete

DELETE /api/v4/groups/{id}

Description

Deletes group with specified id.

Request documentation

Path parameters

id number

Group id to delete

Response documentation
Headers

Content-Type

text/plain;charset=UTF-8

Status

code number

204 No Content in case of successful deletion

Delete async

DELETE /api/v4/groups/async/{id[]}

Description

Deletes groups with specified ids.
This operation may run asynchronous when deletion takes more than 15 seconds. In that case server will return http status code 202 Accepted.

Request documentation

Path parameters

id number[]

Group ids of groups to delete

Response documentation
Headers

Content-Type

application/json;charset=UTF-8

Status

code number

200 OK in case of successful deletion or 204 Accepted when operation is still deleting.

Payload attributes InvocationResult

result Map<number,boolean>

When operation has completed successfully, this result will contain map with entries where key is group id and value is boolean flag indicating result of deletion.

jobTaskId number

When operation went to asynchronous deletion, this value will have id of running job task. See JobTask.

13.4. Permissions administration

13.4.1. Access rules endpoint

This endpoint provides information about user permissions

GET /api/v4/access/dictionary-permissions

Request documentation

Query parameters

dictionary_id number[]

{txt-object-c} an array of dictionary ids for which we’re retrieving permissions information.

Response documentation
Headers

Content-Type

application/json;charset=UTF-8

Payload attributes

dictionaryId number

Dictionary id to which this set of permissions related.

permissions Map<DictionaryPermission,boolean>

Map of top-level permissions for dictionary. When users have permission to work with any dictionary section, this value will be true.
Keys is one of values from enum Dictionary permissions.

sectionPermissions Map<number,Map<DictionaryPermission,boolean>>

Permissions related to specific section in dictionary. Parent map will have Section id as key, and value will be a map with permissions. Nested map will have only permissions with suffix 'CONCEPT_'.

sectionOidPermissions Map<string,Map<DictionaryPermission,boolean>>

Same as sectionPermissions except the key in parent map will be Section oid.

Dictionary permissions enum
Value Description

DICT_READ string

User can read dictionary metadata and concepts with terms from it.

DICT_UPDATE string

User can update dictionary metadata.

DICT_DELETE string

User able to delete dictionary.

CONCEPT_CREATE string

User can create a new concept, and restore deleted concepts from history

CONCEPT_PRINT string

User can print concepts.

CONCEPT_IMPORT string

User can import concepts.

CONCEPT_EXPORT string

User can export concepts.

13.4.2. Permission schemes endpoint

Description

TBD

Please note this endpoint is subject to change in future. It will be merged with Concepts endpoint.

Permission Scheme DTO
Object attribute Description

name string

Domain name.

description string

Domain description.

TBD number

TBD

clientId number

Client DTO id to which object belongs

id number

Permission scheme id.

oid string

Permission scheme oid. This is object id from old objects.

created Object

Metadata object containing information about creation

created.id number

User id created that object

created.name string

User login created that object

created.fullName string

User full name created that object

created.time number

Created date and time in milliseconds since Unix Epoch

created.oid string

User oid created that object (provided for backward compatibility)

changed Object

Metadata object containing information about last modification

changed.id number

User id changed that object

changed.name string

User login changed that object

changed.fullName string

User full name changed that object

changed.time number

Last change date and time in milliseconds since Unix Epoch

changed.oid string

User oid changed that object (provided for backward compatibility)

Find by client

GET /api/v4/permissionschemes/find-permissionschemes-by-client

Description

Finds permission schemes for specified client.

Request documentation

Query parameters

client_id number

Client DTO id to look for

Response documentation
Headers

Content-Type

application/json;charset=UTF-8

Payload

body PermissionScheme[]

An array of found permission schemes of type Permission scheme.

13.5. Dictionaries administration

13.5.1. Dictionaries endpoint

Description
Please note

Dictionaries endpoint right now working in read-only mode. Only one edit function is available is language replace.

Dictionary is terms data definition.

It defines languages used for terms and metadata stored with terms.

Terms of same meaning can be grouped into a Concept and mostly is. Concept consists of synonyms of term in same language and translations in other languages.

Languages
  • Using ISO 639-2 three letter codes by default (eng - English, swe - Swedish, etc). You may specify custom language code, but this code must not be the same as real language code or geographical/orthographical variant.

  • For all languages you may customise writing direction (LTR or RTL). By default TermWeb is using common writing directions for languages (like LTR for English, RTL for Arabic).

  • For each language you may specify geographical variant, e.g.: US - United States, UK - Great Britain, CA - Canada, AU - Australia etc, or any other existing country you may wish. For special cases you may create custom region.

  • For each language you may specify orthographical variant to mark specific writing script of term. For example for Japanese you can choose scripts Hiragana (hira), Katakana (kana) or even combined Hiragana + Katakana (hrkt).

Metadata

You may use predefined fields (TBX-Default based) or custom fields for Concept or Term.

Custom fields can be created for Concept or Term level, here you may find description of supported data types:

Table 1. Custom fields
Type Description

Singleline

Text, will be presented as single line text input. Max symbol length is 16 383 (216-1).

Multiline

Text, will be presented as multi line text input. Max symbol length is 16 383 (216-1).

Date

Date, input will accept only valid date values without time.

Picklist

List of predefined values to be selected. User may select only one value.

Multivalued

List of predefined values to be selected. User may select multiple values.

Incremental

Number value, TermWeb will generate new incremented number after last used value. E.g. when we have field with value 500, TermWeb create automatically number 501 for new Term or Concept.

For all field types is possible

To specify that field is required. User won’t be able to save Concept or Term without providing value to that field (including predefined fields).

For all text fields (including predefined) you may specify:
  1. Encoding (Unicode or Latin letters with numbers only).

  2. Regular expression, TermWeb will validate input to be matching that expression.

  3. Number presentation, will accept only valid integer numbers (range of valid numbers is from -231 to 231-1).

  4. Minimal and maximum length limit. Max limit can’t be bigger than 216-1.

Table 2. Concept predefined fields
Type TBX name Description

Concept origin

conceptOrigin

Customer subset

customerSubset

Definition

definition

Environment subset

environmentSubset

Example

example

Explanation

explanation

Product subset

productSubset

Project subset

projectSubset

Source

source

Table 3. Term predefined fields
Type TBX name Description

Animacy

animacy

Context

context

Customer subset

customerSubset

Definition

definition

Environment subset

environmentSubset

Example

example

Grammatical gender

grammaticalGender

Grammatical number

grammaticalNumber

Picklist: singular, plural, dual, mass, or otherNumber

Part of speech

partOfSpeech

Process status

processStatus

Product subset

productSubset

Project subset

projectSubset

Sample sentence

sampleSentence

Source

source

Source language

sourceLanguage

Term location

termLocation

Term type

termType

Usage note

usageNote

Usage status

administrativeStatus

For every predefined field is possible to change standard name. For standard TBX values of picklists is possible to change names too.

Dictionary DTO
Object attribute Description

name string

Dictionary name.

description string

Description of dictionary.

sections Section[]

List of Dictionary sections of type Section available for reading by current user.

allSections Section[]

List of all Dictionary sections of type Section created in Dictionary.

languages Language[]

List of Dictionary languages of type Language.

conceptFields Field[]

List of Dictionary concept fields of type Field.

termFields Field[]

List of Dictionary term fields of type Field.

emailRecipientId number

User id of email recipient.

layoutId boolean

Id of layout object. Layots non in use anymore.

sortIndex number

Order number for displaying in user specified order

clientId number

Client DTO id to which object belongs

id number

Dictionary id.

oid string

Dictionary oid. This is object id from old objects.

created Object

Metadata object containing information about creation

created.id number

User id created that object

created.name string

User login created that object

created.fullName string

User full name created that object

created.time number

Created date and time in milliseconds since Unix Epoch

created.oid string

User oid created that object (provided for backward compatibility)

changed Object

Metadata object containing information about last modification

changed.id number

User id changed that object

changed.name string

User login changed that object

changed.fullName string

User full name changed that object

changed.time number

Last change date and time in milliseconds since Unix Epoch

changed.oid string

User oid changed that object (provided for backward compatibility)

Section DTO
Object attribute Description

name string

Section name.

viewId number

View id which assigned to section.

numberOfConcepts number

Number of concepts created in this section

deletable boolean

true when section can be deleted.

sortIndex number

Order number for displaying in user specified order

dictionaryId number

Dictionary id to which section related.

clientId number

Client DTO id to which object belongs

id number

Section id.

oid string

Section oid. This is object id from old objects.

deleted number

true when object has been marked as deleted in database.

created Object

Metadata object containing information about creation

created.id number

User id created that object

created.name string

User login created that object

created.fullName string

User full name created that object

created.time number

Created date and time in milliseconds since Unix Epoch

created.oid string

User oid created that object (provided for backward compatibility)

changed Object

Metadata object containing information about last modification

changed.id number

User id changed that object

changed.name string

User login changed that object

changed.fullName string

User full name changed that object

changed.time number

Last change date and time in milliseconds since Unix Epoch

changed.oid string

User oid changed that object (provided for backward compatibility)

Language DTO
Object attribute Description

name string

Language name.

dictionaryId number

Dictionary id in which that language has been created.

clientId number

Client DTO id in which that language has been created.

code string

BCP47 code for language, region and script

code2 string

The ISO639-1 code (2 chars) to be used for Locale creation, e.g sv, en, pt, de. Can be empty string.

code3 string

The ISO639-2 code (3 chars) e.g. swe, eng, por, deu, haw.

idStr string

combination of ids of language, geographical and orthographical variants separated with hyphen -.

iso boolean

Flag which indicates if this language is defined in ISO639-2.

custom boolean

rtl boolean

true when language has Right-to-left writing direction of script.

sortIndex number

Order number for displaying in user specified order

variants LanguageVariant[]

List of geographical and orthographical variants of type Language Variant.

id number

Language id.

oid string

Language oid. This is object id from old objects.

deleted number

true when object has been marked as deleted in database.

Language Variant DTO
Object attribute Description

name string

Language variant name.

variantType number

0 for Geographical, 1 for Orthographical

variantCode string

Variant code string

predefined boolean

true when code of this value from list of TermWeb predefined values

languageId number

Language id to which this variant belongs to.

sortIndex number

Order number for displaying in user specified order

id number

Language variant id.

oid string

Language variant oid. This is object id from old objects.

deleted number

true when object has been marked as deleted in database.

Field DTO
Object attribute Description

name string

Field name.

specifiedName string

The user specified name of the field if any.

dataCategory enum

GENERIC in case of custom field.
In case of TBX compatible field, values are: DEFINITION, EXAMPLE, GRAMMATICAL_GENDER, GRAMMATICAL_NUMBER, PROCESS_STATUS, SOURCE, SOURCE_LANGUAGE, USAGE_NOTE, CONTEXT, USAGE_STATUS, TERM_TYPE, CONCEPT_ORIGIN, CUSTOMER_SUBSET, ENVIRONMENT_SUBSET, EXPLANATION, PRODUCT_SUBSET, PROJECT_SUBSET, ANIMACY, PART_OF_SPEECH, SAMPLE_SENTENCE, TERM_LOCATION.
In case of system type field, values are: DOM - concepts domain,
DICT - dictionary,
SECT - dictionary sections,
SUBC - subclass, not in use,
CONID - Concept ID (serial number in dictionary),
CREBY - concept created by,
CREDATE - concept creation date,
CHGBY - last author of concept changes,
CHGDATE - concept last modification date,

TERM - term name,
LANG - term language,
GVAR - geographical variant,
OVAR - orthographical variant,
TERM_CONFIG - internal use only,
TCREBY - term created by,
TCREDATE - term creation date,
TCHGBY - term last author of term changes,
TCHGDATE - term last modification date,
TERM_ID - Term ID (serial number in dictionary) .

fieldType enum

Type of field. Possible values are: SINGLELINE, MULTILINE, NUMBER, PICKLIST, MULTISELECT, DATE, CHECKBOX, USER.

model FieldModel

Settings of field. Object of type Field Model.

sortIndex number

Order number for displaying in user specified order

id number

Field id.

oid string

Field oid. This is object id from old objects.

deleted number

true when object has been marked as deleted in database.

created Object

Metadata object containing information about creation

created.id number

User id created that object

created.name string

User login created that object

created.fullName string

User full name created that object

created.time number

Created date and time in milliseconds since Unix Epoch

created.oid string

User oid created that object (provided for backward compatibility)

changed Object

Metadata object containing information about last modification

changed.id number

User id changed that object

changed.name string

User login changed that object

changed.fullName string

User full name changed that object

changed.time number

Last change date and time in milliseconds since Unix Epoch

changed.oid string

User oid changed that object (provided for backward compatibility)

Field Model DTO
Object attribute Description

required boolean

true when field value can’t be empty.

minLen number

The minimum length for the field value. 0 for no limit.

maxLen number

The maximum length for the field value. 0 for no limit.

regExp string

A regular expression describing the allowed values in the field.

number boolean

true when field value can have only numbers.

unicode boolean

true when field value can contain any string, otherwise only latin character set.

picklistItems PickListItem[]

Picklist items when field type is Picklist or Multiselect. Object of type Picklist item.

id number

Field model id.

oid string

Field model oid. This is object id from old objects.

Picklist Item DTO
Object attribute Description

name string

An item display name specified by user

tbxName string

A standard TBX name for picklist item. Must be used unless user specified custom in name attribute.

sortIndex number

Order number for displaying in user specified order

fieldOid string[]

Field oid to which this item is related.

id number

Picklist item id.

oid string

Picklist item oid. This is object id from old objects.

TBX DataCategory
Object attribute Description

key string

localizable name key of the data category. Internal use only.

name string

localizable name key of the data category.

id string

ISO id for the category, e.g. 08 for ISO12620A-08

fieldType enum

Type of field. Possible values are: SINGLELINE, MULTILINE, NUMBER, PICKLIST, MULTISELECT, DATE, CHECKBOX.

picklistItems string[]

List of possible values for picklists fields.

levels string[]

An array of field levels where this category can be used. Possible values are: 'CONCEPT', 'TERM'.

Data categories

GET /api/v4/dictionaries/data-categories

Description

Returns list of supported TBX data categories by this TermWeb installation

Request documentation
Headers

X-Auth-Token

Unexpired authentication token

Response documentation
Headers

Content-Type

application/json;charset=UTF-8

Payload

body DataCategory[]

Array of available TBX data categories of type DataCategory.

Language replace

POST /api/v4/dictionaries/language-replace/

Description

This operation moves terms of dictionary from one language to another one.
This operation may run asynchronous when transfer takes more than 15 seconds. In that case server will return http status code 202 Accepted.

Request documentation

Query parameters

dictionary-id number

Dictionary id where to apply language replace operation.

from-id string

Language variant code in custom format: <lang_var>[;[region_code];[script_code]]

to-id string

Language variant code in custom format: <lang_var>[;[region_code][;script_code]]

Response documentation
Headers

Content-Type

application/json;charset=UTF-8

Status

code number

200 OK in case of successful transfer or 204 Accepted when operation is still transferring.

Payload attributes InvocationResult

result number

Number of moved terms.

jobTaskId number

When operation went to asynchronous transfer, this value will have id of running job task. See JobTask.

Find

GET /api/v4/dictionaries/

Description

Finds dictionaries with specified query parameters available to current user.

Request documentation

Query parameters

client_id number

<optional>, default is equal to current client id related to authentication token.
[TIP] Reserved for future releases and can be omitted for now.

name string

<optional>, default is null
Filters dictionaries with name starting with provided value. Search will be case insensitive.

name-eq string

<optional>, default is null
Filters dictionaries with name equal to provided value ignoring case.

format enum

<optional>, default is 'FULL'
Response format for dictionary objects, possible values are ID, SHORT, FULL, EDIT. See Formats.

include-deleted boolean

<optional>, default is false
When value is true TermWeb will include softly deleted objects to search results.
This function is available only to System or client administrators.

size number

<optional>, default is 20
Page size, represents how many of objects can be returned

page number

<optional>, default is 0
Page number, represents from which position to start loading data, in other words offset equal to size * page.

sort string

<optional>, default is null
Order direction of returned data by some attribute, can accept most of object attributes for specific endpoint. For example: 'name', 'name,ASC', 'name,DESC'.

Response documentation
Headers

Content-Type

application/json;charset=UTF-8

Payload

content Dictionary[]

Found dictionaries of type Dictionary.

last boolean

indicates if this page is last with current search params

totalElements number

total amount of objects accessible from this endpoint

totalPages number

total number of pages available with current page size and total elements

sort string

current sort params, like 'name,ASC'

numberOfElements number

amount of objects returned with this page

first boolean

indicates if this page is first with current search params

size number

current page size

number number

current page number

Row number

GET /api/v4/dictionaries/rownum/{id}

Description

Finds rownumber of dictionary with specified filter and sort parameters. Useful when you need to determine page where object is located after creation or update.

Request documentation

Path parameters

id number

Dictionary id to look for

sort string

<optional>, default is null
Order direction of returned data by some attribute, can accept most of object attributes for specific endpoint. For example: 'name', 'name,ASC', 'name,DESC'.

Query parameters

client_id number

<optional>, default is equal to current client id related to authentication token.
[TIP] Reserved for future releases and can be omitted for now.

name string

<optional>, default is null
Filters dictionaries with name starting with provided value. Search will be case insensitive.

name-eq string

<optional>, default is null
Filters dictionaries with name equal to provided value ignoring case.

format enum

<optional>, default is 'FULL'
Response format for dictionary objects, possible values are ID, SHORT, FULL, EDIT. See Formats.

include-deleted boolean

<optional>, default is false
When value is true TermWeb will include softly deleted objects to search results.
This function is available only to System or client administrators.

Response documentation
Headers

Content-Type

application/json;charset=UTF-8

Payload

body number

Found row number for specified parameters, in case when nothing found return 0.

Get

GET /api/v4/dictionaries/{id}

Description

Looks for dictionary with specified id.

Request documentation

Path parameters

id number

Dictionary id to look for

format enum

<optional>, default is 'FULL'
Response format for dictionary objects, possible values are ID, SHORT, FULL, EDIT. See Formats.

include-deleted boolean

<optional>, default is false
When value is true TermWeb will include softly deleted objects to search results.
This function is available only to System or client administrators.

Response documentation

Headers

Content-Type

application/json;charset=UTF-8

Payload

body Dictionary

JSON object of Dictionary.

13.5.2. Sections endpoint

Description

Sections allows to split up dictionary content by named section. Each section can have different set of permissions and displayed attributes. When Dictionary is created it will have one section with same name as dictionary, this name can be changed to anything else. When section is last, it cannot be deleted from dictionary.

Assign clients

POST /api/v4/sections/clear/

Description

Clears Dictionary sections, by removing every concept from there.
Changes will be stored in dictionary history.

Request documentation

Query parameters

section-id number[]

An array of sections ids to clear.

Response documentation
Headers

Content-Type

application/json;charset=UTF-8

Status

code number

200 OK in case of successful clearance or 204 Accepted when operation is still clearing.

Payload attributes InvocationResult

result Map<number,boolean>

When operation has completed successfully, this result will contain map with entries where key is section id and value is boolean flag indicating result of clearance.

jobTaskId number

When operation went to asynchronous clearing, this value will have id of running job task. See JobTask.

Find

GET /api/v4/sections/

Description

Finds sections with specified query parameters available to current user.

Request documentation

Query parameters

dictionary_id number

<optional>, default is null.
Provide an id when you need to filter section objects related to specific dictionary.

client_id number

<optional>, default is equal to current client id related to authentication token.
[TIP] Reserved for future releases and can be omitted for now.

name string

<optional>, default is null
Filters sections with name starting with provided value. Search will be case insensitive.

name-eq string

<optional>, default is null
Filters sections with name equal to provided value ignoring case.

format enum

<optional>, default is 'FULL'
Response format for section objects, possible values are ID, SHORT, FULL, EDIT. See Formats.

include-deleted boolean

<optional>, default is false
When value is true TermWeb will include softly deleted objects to search results.
This function is available only to System or client administrators.

size number

<optional>, default is 20
Page size, represents how many of objects can be returned

page number

<optional>, default is 0
Page number, represents from which position to start loading data, in other words offset equal to size * page.

sort string

<optional>, default is null
Order direction of returned data by some attribute, can accept most of object attributes for specific endpoint. For example: 'name', 'name,ASC', 'name,DESC'.

Response documentation
Headers

Content-Type

application/json;charset=UTF-8

Payload

content Section[]

Found sections of type Section.

last boolean

indicates if this page is last with current search params

totalElements number

total amount of objects accessible from this endpoint

totalPages number

total number of pages available with current page size and total elements

sort string

current sort params, like 'name,ASC'

numberOfElements number

amount of objects returned with this page

first boolean

indicates if this page is first with current search params

size number

current page size

number number

current page number

Row number

GET /api/v4/sections/rownum/{id}

Description

Finds rownumber of section with specified filter and sort parameters. Useful when you need to determine page where object is located after creation or update.

Request documentation

Path parameters

id number

Section id to look for

sort string

<optional>, default is null
Order direction of returned data by some attribute, can accept most of object attributes for specific endpoint. For example: 'name', 'name,ASC', 'name,DESC'.

Query parameters

dictionary_id number

<optional>, default is null.
Provide an id when you need to filter section objects related to specific dictionary.

client_id number

<optional>, default is equal to current client id related to authentication token.
[TIP] Reserved for future releases and can be omitted for now.

name string

<optional>, default is null
Filters sections with name starting with provided value. Search will be case insensitive.

name-eq string

<optional>, default is null
Filters sections with name equal to provided value ignoring case.

format enum

<optional>, default is 'FULL'
Response format for section objects, possible values are ID, SHORT, FULL, EDIT. See Formats.

include-deleted boolean

<optional>, default is false
When value is true TermWeb will include softly deleted objects to search results.
This function is available only to System or client administrators.

Response documentation
Headers

Content-Type

application/json;charset=UTF-8

Payload

body number

Found row number for specified parameters, in case when nothing found return 0.

Get

GET /api/v4/sections/{id}

Description

Looks for section with specified id.

Request documentation

Path parameters

id number

Section id to look for

format enum

<optional>, default is 'FULL'
Response format for section objects, possible values are ID, SHORT, FULL, EDIT. See Formats.

include-deleted boolean

<optional>, default is false
When value is true TermWeb will include softly deleted objects to search results.
This function is available only to System or client administrators.

Response documentation

Headers

Content-Type

application/json;charset=UTF-8

Payload

body Section

JSON object of Section.

Create

POST /api/v4/sections/

Description

Creates new section from JSON data sent in payload.

Request documentation

Payload

body Section

JSON object of type Section.

format enum

<optional>, default is 'FULL'
Response format for section objects, possible values are ID, SHORT, FULL, EDIT. See Formats.

Response documentation
Headers

Content-Type

application/json;charset=UTF-8

Payload

body Section

Created object of section.

Update

PUT /api/v4/sections/{id}

Description

Updates existing section from JSON data sent in payload.

Request documentation

Headers

Content-Type

application/json

Path parameters

id number

Id of Section which need to be updated

Payload

body Section

JSON object of type Section. Value of id and oid attribute specified in payload will be ignored by server.
Don’t forget to include "version" attribute value.
Missing attributes in JSON object or null values will erase that value on server side.

format enum

<optional>, default is 'FULL'
Response format for section objects, possible values are ID, SHORT, FULL, EDIT. See Formats.

Response documentation
Headers

Content-Type

application/json;charset=UTF-8

Payload

body Section

Updated section object.

Partial update

PUT /api/v4/sections/partial/{id}

Description

It updates only specified parts of section from JSON data sent in payload. Unlike method Update, patch will only update values of object which are present in JSON without modifying other fields which are not present in JSON.

Request documentation

Path parameters

id number

Id of Section which need to be updated

Payload

body Section

JSON object of type Section. Value of id and oid attribute specified in payload will be ignored by server.
Missing attributes in JSON object will be omitted. Fields in JSON object with null will be cleared.
Don’t forget to include "version" attribute value.

format enum

<optional>, default is 'FULL'
Response format for section objects, possible values are ID, SHORT, FULL, EDIT. See Formats.

Response documentation
Headers

Content-Type

application/json;charset=UTF-8

Payload

body Section

Patched section object.

Delete

DELETE /api/v4/sections/{id}

Description

Deletes section with specified id.

Request documentation

Path parameters

id number

Section id to delete

Response documentation
Headers

Content-Type

text/plain;charset=UTF-8

Status

code number

204 No Content in case of successful deletion

Delete async

DELETE /api/v4/sections/async/{id[]}

Description

Deletes sections with specified ids.
This operation may run asynchronous when deletion takes more than 15 seconds. In that case server will return http status code 202 Accepted.

Request documentation

Path parameters

id number[]

Section ids of sections to delete

Response documentation
Headers

Content-Type

application/json;charset=UTF-8

Status

code number

200 OK in case of successful deletion or 204 Accepted when operation is still deleting.

Payload attributes InvocationResult

result Map<number,boolean>

When operation has completed successfully, this result will contain map with entries where key is section id and value is boolean flag indicating result of deletion.

jobTaskId number

When operation went to asynchronous deletion, this value will have id of running job task. See JobTask.

13.5.3. Fields endpoint

Description

Fields for Dictionary. Fields describes what kind of attributes terms can have. Fields can be of two types: custom and TBX compatible.

Incremental next value

GET /api/v4/fields/incremental-next/{field-oid}

Description

Returns next available value for fields of type "incremental"

Request documentation
Path parameters

field-oid string

Field old object oid of field of type "incremental"

Response documentation
Headers

Content-Type

application/json;charset=UTF-8

Payload

body number

Value with next available number

Incremental validate value

GET /api/v4/fields/incremental/validate/{field-oid}

Description

Check uniqueness of value for specified field of type "incremental".

Request documentation
Query parameters

field-oid string

Field old object oid of field of type "incremental"

value number

value to check

type enum

One of the field levels: CONCEPT or TERM

entry-id number

<optional>, Concept or Term id to exclude from validation results.

Response documentation
Headers

Content-Type

application/json;charset=UTF-8

Payload

body boolean

true when provided value is unique

13.5.4. Domains endpoint

Description

Domains for Dictionary. Domains linked together in hierarchical structure.

Domain DTO
Object attribute Description

name string

Domain name.

description string

Domain description.

dictionaryId number

Dictionary id in which that language has been created.

parentDomainId number

Domain id which is parent of this domain.

numberOfConcepts number

Number of concepts created in this section

children number[]

List of children Domain ids.

clientId number

Client DTO id to which object belongs

id number

Domain id.

oid string

Domain oid. This is object id from old objects.

deleted number

true when object has been marked as deleted in database.

created Object

Metadata object containing information about creation

created.id number

User id created that object

created.name string

User login created that object

created.fullName string

User full name created that object

created.time number

Created date and time in milliseconds since Unix Epoch

created.oid string

User oid created that object (provided for backward compatibility)

changed Object

Metadata object containing information about last modification

changed.id number

User id changed that object

changed.name string

User login changed that object

changed.fullName string

User full name changed that object

changed.time number

Last change date and time in milliseconds since Unix Epoch

changed.oid string

User oid changed that object (provided for backward compatibility)

Find

GET /api/v4/domains/

Description

Finds domain with specified query parameters available to current user.

Request documentation

Query parameters

dictionary_id number

required, provide a dictionary id to get list of domains for it.

name string

<optional>, default is null
Filters domain with name starting with provided value. Search will be case insensitive.

name-eq string

<optional>, default is null
Filters domain with name equal to provided value ignoring case.

format enum

<optional>, default is 'FULL'
Response format for domain objects, possible values are ID, SHORT, FULL, EDIT. See Formats.

include-deleted boolean

<optional>, default is false
When value is true TermWeb will include softly deleted objects to search results.
This function is available only to System or client administrators.

size number

<optional>, default is 20
Page size, represents how many of objects can be returned

page number

<optional>, default is 0
Page number, represents from which position to start loading data, in other words offset equal to size * page.

sort string

<optional>, default is null
Order direction of returned data by some attribute, can accept most of object attributes for specific endpoint. For example: 'name', 'name,ASC', 'name,DESC'.

Response documentation
Headers

Content-Type

application/json;charset=UTF-8

Payload

content Domain[]

Found domain of type Domain.

last boolean

indicates if this page is last with current search params

totalElements number

total amount of objects accessible from this endpoint

totalPages number

total number of pages available with current page size and total elements

sort string

current sort params, like 'name,ASC'

numberOfElements number

amount of objects returned with this page

first boolean

indicates if this page is first with current search params

size number

current page size

number number

current page number

Row number

GET /api/v4/domains/rownum/{id}

Description

Finds rownumber of domain with specified filter and sort parameters. Useful when you need to determine page where object is located after creation or update.

Request documentation

Path parameters

id number

Domain id to look for

sort string

<optional>, default is null
Order direction of returned data by some attribute, can accept most of object attributes for specific endpoint. For example: 'name', 'name,ASC', 'name,DESC'.

Query parameters

dictionary_id number

required, provide a dictionary id to get list of domains for it.

name string

<optional>, default is null
Filters domain with name starting with provided value. Search will be case insensitive.

name-eq string

<optional>, default is null
Filters domain with name equal to provided value ignoring case.

format enum

<optional>, default is 'FULL'
Response format for domain objects, possible values are ID, SHORT, FULL, EDIT. See Formats.

include-deleted boolean

<optional>, default is false
When value is true TermWeb will include softly deleted objects to search results.
This function is available only to System or client administrators.

Response documentation
Headers

Content-Type

application/json;charset=UTF-8

Payload

body number

Found row number for specified parameters, in case when nothing found return 0.

Get

GET /api/v4/domains/{id}

Description

Looks for domain with specified id.

Request documentation

Path parameters

id number

Domain id to look for

format enum

<optional>, default is 'FULL'
Response format for domain objects, possible values are ID, SHORT, FULL, EDIT. See Formats.

include-deleted boolean

<optional>, default is false
When value is true TermWeb will include softly deleted objects to search results.
This function is available only to System or client administrators.

Response documentation

Headers

Content-Type

application/json;charset=UTF-8

Payload

body Domain

JSON object of Domain.

Create

POST /api/v4/domains/

Description

Creates new domain from JSON data sent in payload.

Request documentation

Payload

body Domain

JSON object of type Domain.

format enum

<optional>, default is 'FULL'
Response format for domain objects, possible values are ID, SHORT, FULL, EDIT. See Formats.

Response documentation
Headers

Content-Type

application/json;charset=UTF-8

Payload

body Domain

Created object of domain.

Update

PUT /api/v4/domains/{id}

Description

Updates existing domain from JSON data sent in payload.

Request documentation

Headers

Content-Type

application/json

Path parameters

id number

Id of Domain which need to be updated

Payload

body Domain

JSON object of type Domain. Value of id and oid attribute specified in payload will be ignored by server.
Don’t forget to include "version" attribute value.
Missing attributes in JSON object or null values will erase that value on server side.

format enum

<optional>, default is 'FULL'
Response format for domain objects, possible values are ID, SHORT, FULL, EDIT. See Formats.

Response documentation
Headers

Content-Type

application/json;charset=UTF-8

Payload

body Domain

Updated domain object.

Partial update

PUT /api/v4/domains/partial/{id}

Description

It updates only specified parts of domain from JSON data sent in payload. Unlike method Update, patch will only update values of object which are present in JSON without modifying other fields which are not present in JSON.

Request documentation

Path parameters

id number

Id of Domain which need to be updated

Payload

body Domain

JSON object of type Domain. Value of id and oid attribute specified in payload will be ignored by server.
Missing attributes in JSON object will be omitted. Fields in JSON object with null will be cleared.
Don’t forget to include "version" attribute value.

format enum

<optional>, default is 'FULL'
Response format for domain objects, possible values are ID, SHORT, FULL, EDIT. See Formats.

Response documentation
Headers

Content-Type

application/json;charset=UTF-8

Payload

body Domain

Patched domain object.

Delete

DELETE /api/v4/domains/{id}

Description

Deletes domain with specified id.

Request documentation

Path parameters

id number

Domain id to delete

Response documentation
Headers

Content-Type

text/plain;charset=UTF-8

Status

code number

204 No Content in case of successful deletion

Delete async

DELETE /api/v4/domains/async/{id[]}

Description

Deletes domain with specified ids.
This operation may run asynchronous when deletion takes more than 15 seconds. In that case server will return http status code 202 Accepted.

Request documentation

Path parameters

id number[]

Domain ids of domain to delete

Response documentation
Headers

Content-Type

application/json;charset=UTF-8

Status

code number

200 OK in case of successful deletion or 204 Accepted when operation is still deleting.

Payload attributes InvocationResult

result Map<number,boolean>

When operation has completed successfully, this result will contain map with entries where key is domain id and value is boolean flag indicating result of deletion.

jobTaskId number

When operation went to asynchronous deletion, this value will have id of running job task. See JobTask.

13.5.5. Filters endpoint

Description
Filter DTO
Object attribute Description

name string

Filter name.

groupId number

Group id to which this Filter available to use. Used for "Visibility" field in UI.
When value is null this means filter visible only to author and Client administrator.

filteringTerms boolean

true when search results will return only matching terms. Otherwise it will return all terms from Concept containing matching term. ()

criterias FilterCriteria[]

Original developer of this functionality didn’t know that criteria is the plural form of criterion and indices, and not indexes, is correct plural form of index.
Later these field names will be updated to have the correct grammatical form.
List of filter criteria of type Filter criterion.

indexed boolean

true when TermWeb processed filter and indexed all terms.

type enum

Filter type. Possible values are: STANDARD, TEMPORARY, SEARCH_FIELD, PROJECT, DUAL, SYNC_SETTING.

canEdit boolean

true when filter can be edited by current user.

cantDelete boolean

true when filter can’t be deleted by current user.

cantDeleteReason string

Message containing information why this filter can’t be deleted.

dictionaryId number

Dictionary id to which filter related.

clientId number

Client DTO id to which object belongs

id number

Filter id.

oid string

Filter oid. This is object id from old objects.

created Object

Metadata object containing information about creation

created.id number

User id created that object

created.name string

User login created that object

created.fullName string

User full name created that object

created.time number

Created date and time in milliseconds since Unix Epoch

created.oid string

User oid created that object (provided for backward compatibility)

changed Object

Metadata object containing information about last modification

changed.id number

User id changed that object

changed.name string

User login changed that object

changed.fullName string

User full name changed that object

changed.time number

Last change date and time in milliseconds since Unix Epoch

changed.oid string

User oid changed that object (provided for backward compatibility)

Filter criterion DTO
Object attribute Description

filterId number

Filter id to which this criterion belongs.

fieldOid string

Field old object oid from dictionary to which this Filter belongs to.
Can have here system field oid instead of regular dictionary field: DOM - concepts domain,
DICT - dictionary,
SECT - dictionary sections,
SUBC - subclass, not in use,
CONID - Concept ID (serial number in dictionary),
CREBY - concept created by,
CREDATE - concept creation date,
CHGBY - last author of concept changes,
CHGDATE - concept last modification date,

TERM - term name,
LANG - term language,
GVAR - geographical variant,
OVAR - orthographical variant,
TERM_CONFIG - internal use only,
TCREBY - term created by,
TCREDATE - term creation date,
TCHGBY - term last author of term changes,
TCHGDATE - term last modification date,
TERM_ID - Term ID (serial number in dictionary) .

To split up concept level fields criteria and term level fields criteria used special fieldOid value equal to 'TERM_CRI_START'.
Filter can have multiple groups of term level fields criteria. Terms criteria can’t be nested into each other.
There is NO special fieldOid 'TERM_CRI_END' as you may think.

conceptField boolean

true when this condition is for concept level field.

operation enum

Comparison operation for this field, can have this values: EQUALS, NOT_EQUALS, CONTAINS, NOT_CONTAINS, EXISTS, NOT_EXISTS, LESS_THAN, GREATER_THAN, STARTS_WITH, EMPTY, NOT_EMPTY .

value string

String value to use with operation. When search is done on non text field types, value must another value than text. In case of field type:

  • User: User old object oid.

  • Domain: Domain old object oid.

  • Concept Id: Concept cid (serial number in Dictionary).

  • Date: Date string in one of the formats: yyyy-MM-dd HH:mm:ss, yyyy-MM-dd HH:mm, yyyy-MM-dd, yyyyMMdd. Please note that these dates will be converted to the server’s time zone which is UTC by default. .

  • Section: Section old object oid.

  • Term: Term name attribute.

  • Language: should be ISO639-2 three-letter lower case code.

  • Region: Language Variant old object oid for geographical variant.

  • Script: Language Variant old object oid for orthographical variant.

  • Picklist: Picklist item name attribute when it has value, otherwise - tbxName value.

boolOperator enum

Number enum which indicates how current criterion linked with next criterion in array.
Values are: 'No operator' - 0, 'AND operator' - 1, 'OR operator' - 2.

type enum

Filter type. Possible values are: STANDARD, TEMPORARY, SEARCH_FIELD, PROJECT, DUAL, SYNC_SETTING.

sortIndex number

Order number where this criterion must be in an array of filter criteria.

relDate boolean

true when date condition is used as relative date (TermWeb will update date condition relatively to date of creation).

included boolean|null

Used in combination with fieldOid equal to 'TERM_CRI_START' otherwise will be null. true means that matched values will be included into search results, otherwise - excluded.

id number

Filter criterion id.

oid string

Filter criterion oid. This is object id from old objects.

Index filter

POST /api/v4/filters/index/{id}

Description

Launches indexing of Filter. Operation is synchronous.

Request documentation

Path parameters

id number

Filter id.

Response documentation
Headers

Content-Type

application/json;charset=UTF-8

Status

code number

200 OK in case of successful index.

Find

GET /api/v4/filters/

Description

Finds filters with specified query parameters available to current user.

Request documentation

Query parameters

dictionary_id number

<optional>, default is null.
Provide an id when you need to filter filter criterion objects related to specific dictionary.

client_id number

<optional>, default is equal to current client id related to authentication token.
[TIP] Reserved for future releases and can be omitted for now.

name string

<optional>, default is null
Filters filters with name starting with provided value. Search will be case insensitive.

name-eq string

<optional>, default is null
Filters filters with name equal to provided value ignoring case.

format enum

<optional>, default is 'FULL'
Response format for filter criterion objects, possible values are ID, SHORT, FULL, EDIT. See Formats.

include-deleted boolean

<optional>, default is false
When value is true TermWeb will include softly deleted objects to search results.
This function is available only to System or client administrators.

size number

<optional>, default is 20
Page size, represents how many of objects can be returned

page number

<optional>, default is 0
Page number, represents from which position to start loading data, in other words offset equal to size * page.

sort string

<optional>, default is null
Order direction of returned data by some attribute, can accept most of object attributes for specific endpoint. For example: 'name', 'name,ASC', 'name,DESC'.

Response documentation
Headers

Content-Type

application/json;charset=UTF-8

Payload

content Filter[]

Found filters of type Filter.

last boolean

indicates if this page is last with current search params

totalElements number

total amount of objects accessible from this endpoint

totalPages number

total number of pages available with current page size and total elements

sort string

current sort params, like 'name,ASC'

numberOfElements number

amount of objects returned with this page

first boolean

indicates if this page is first with current search params

size number

current page size

number number

current page number

Row number

GET /api/v4/filters/rownum/{id}

Description

Finds rownumber of filter criterion with specified filter and sort parameters. Useful when you need to determine page where object is located after creation or update.

Request documentation

Path parameters

id number

Filter criterion id to look for

sort string

<optional>, default is null
Order direction of returned data by some attribute, can accept most of object attributes for specific endpoint. For example: 'name', 'name,ASC', 'name,DESC'.

Query parameters

dictionary_id number

<optional>, default is null.
Provide an id when you need to filter filter criterion objects related to specific dictionary.

client_id number

<optional>, default is equal to current client id related to authentication token.
[TIP] Reserved for future releases and can be omitted for now.

name string

<optional>, default is null
Filters filters with name starting with provided value. Search will be case insensitive.

name-eq string

<optional>, default is null
Filters filters with name equal to provided value ignoring case.

format enum

<optional>, default is 'FULL'
Response format for filter criterion objects, possible values are ID, SHORT, FULL, EDIT. See Formats.

include-deleted boolean

<optional>, default is false
When value is true TermWeb will include softly deleted objects to search results.
This function is available only to System or client administrators.

Response documentation
Headers

Content-Type

application/json;charset=UTF-8

Payload

body number

Found row number for specified parameters, in case when nothing found return 0.

Get

GET /api/v4/filters/{id}

Description

Looks for filter criterion with specified id.

Request documentation

Path parameters

id number

Filter criterion id to look for

format enum

<optional>, default is 'FULL'
Response format for filter criterion objects, possible values are ID, SHORT, FULL, EDIT. See Formats.

include-deleted boolean

<optional>, default is false
When value is true TermWeb will include softly deleted objects to search results.
This function is available only to System or client administrators.

Response documentation

Headers

Content-Type

application/json;charset=UTF-8

Payload

body Filter

JSON object of Filter criterion.

Create

POST /api/v4/filters/

Description

Creates new filter criterion from JSON data sent in payload.

Request documentation

Payload

body Filter

JSON object of type Filter.

format enum

<optional>, default is 'FULL'
Response format for filter criterion objects, possible values are ID, SHORT, FULL, EDIT. See Formats.

Response documentation
Headers

Content-Type

application/json;charset=UTF-8

Payload

body Filter

Created object of filter criterion.

Update

PUT /api/v4/filters/{id}

Description

Updates existing filter criterion from JSON data sent in payload.

Request documentation

Headers

Content-Type

application/json

Path parameters

id number

Id of Filter criterion which need to be updated

Payload

body Filter

JSON object of type Filter. Value of id and oid attribute specified in payload will be ignored by server.
Don’t forget to include "version" attribute value.
Missing attributes in JSON object or null values will erase that value on server side.

format enum

<optional>, default is 'FULL'
Response format for filter criterion objects, possible values are ID, SHORT, FULL, EDIT. See Formats.

Response documentation
Headers

Content-Type

application/json;charset=UTF-8

Payload

body Filter

Updated filter criterion object.

Partial update

PUT /api/v4/filters/partial/{id}

Description

It updates only specified parts of filter criterion from JSON data sent in payload. Unlike method Update, patch will only update values of object which are present in JSON without modifying other fields which are not present in JSON.

Request documentation

Path parameters

id number

Id of Filter criterion which need to be updated

Payload

body Filter

JSON object of type Filter. Value of id and oid attribute specified in payload will be ignored by server.
Missing attributes in JSON object will be omitted. Fields in JSON object with null will be cleared.
Don’t forget to include "version" attribute value.

format enum

<optional>, default is 'FULL'
Response format for filter criterion objects, possible values are ID, SHORT, FULL, EDIT. See Formats.

Response documentation
Headers

Content-Type

application/json;charset=UTF-8

Payload

body Filter

Patched filter criterion object.

Delete

DELETE /api/v4/filters/{id}

Description

Deletes filter criterion with specified id.

Request documentation

Path parameters

id number

Filter criterion id to delete

Response documentation
Headers

Content-Type

text/plain;charset=UTF-8

Status

code number

204 No Content in case of successful deletion

Delete async

DELETE /api/v4/filters/async/{id[]}

Description

Deletes filters with specified ids.
This operation may run asynchronous when deletion takes more than 15 seconds. In that case server will return http status code 202 Accepted.

Request documentation

Path parameters

id number[]

Filter criterion ids of filters to delete

Response documentation
Headers

Content-Type

application/json;charset=UTF-8

Status

code number

200 OK in case of successful deletion or 204 Accepted when operation is still deleting.

Payload attributes InvocationResult

result Map<number,boolean>

When operation has completed successfully, this result will contain map with entries where key is filter criterion id and value is boolean flag indicating result of deletion.

jobTaskId number

When operation went to asynchronous deletion, this value will have id of running job task. See JobTask.

13.5.6. Views endpoint

Description

Client administrator or dictionary administrator should be able to create/edit view for Dictionary, and also be able to delete Views which are not in use. When view is in use (by Group, Section) UI should provide information why it can’t be deleted.

Dictionary can be changed for View during edit (only when View is not in use by any Group or Section).

'Term' and 'Language' fields are always visible and can’t be hidden.

View DTO
Object attribute Description

name string

View name.

fields string[]

Field oids included in this view.

inUse boolean

true when view is in use by any Section or by Group.

inUseMessage boolean

Message with a description of which views or groups are using that view.

dictionaryId number

Dictionary id to which view related.

clientId number

Client DTO id to which object belongs

id number

View id.

oid string

View oid. This is object id from old objects.

deleted number

true when object has been marked as deleted in database.

created Object

Metadata object containing information about creation

created.id number

User id created that object

created.name string

User login created that object

created.fullName string

User full name created that object

created.time number

Created date and time in milliseconds since Unix Epoch

created.oid string

User oid created that object (provided for backward compatibility)

changed Object

Metadata object containing information about last modification

changed.id number

User id changed that object

changed.name string

User login changed that object

changed.fullName string

User full name changed that object

changed.time number

Last change date and time in milliseconds since Unix Epoch

changed.oid string

User oid changed that object (provided for backward compatibility)

Find

GET /api/v4/views/

Description

Finds views with specified query parameters available to current user.

Request documentation

Query parameters

dictionary_id number

<optional>, default is null.
Provide an id when you need to filter view objects related to specific dictionary.

client_id number

<optional>, default is equal to current client id related to authentication token.
[TIP] Reserved for future releases and can be omitted for now.

name string

<optional>, default is null
Filters views with name starting with provided value. Search will be case insensitive.

name-eq string

<optional>, default is null
Filters views with name equal to provided value ignoring case.

format enum

<optional>, default is 'FULL'
Response format for view objects, possible values are ID, SHORT, FULL, EDIT. See Formats.

include-deleted boolean

<optional>, default is false
When value is true TermWeb will include softly deleted objects to search results.
This function is available only to System or client administrators.

size number

<optional>, default is 20
Page size, represents how many of objects can be returned

page number

<optional>, default is 0
Page number, represents from which position to start loading data, in other words offset equal to size * page.

sort string

<optional>, default is null
Order direction of returned data by some attribute, can accept most of object attributes for specific endpoint. For example: 'name', 'name,ASC', 'name,DESC'.

Response documentation
Headers

Content-Type

application/json;charset=UTF-8

Payload

content View[]

Found views of type View.

last boolean

indicates if this page is last with current search params

totalElements number

total amount of objects accessible from this endpoint

totalPages number

total number of pages available with current page size and total elements

sort string

current sort params, like 'name,ASC'

numberOfElements number

amount of objects returned with this page

first boolean

indicates if this page is first with current search params

size number

current page size

number number

current page number

Row number

GET /api/v4/views/rownum/{id}

Description

Finds rownumber of view with specified filter and sort parameters. Useful when you need to determine page where object is located after creation or update.

Request documentation

Path parameters

id number

View id to look for

sort string

<optional>, default is null
Order direction of returned data by some attribute, can accept most of object attributes for specific endpoint. For example: 'name', 'name,ASC', 'name,DESC'.

Query parameters

dictionary_id number

<optional>, default is null.
Provide an id when you need to filter view objects related to specific dictionary.

client_id number

<optional>, default is equal to current client id related to authentication token.
[TIP] Reserved for future releases and can be omitted for now.

name string

<optional>, default is null
Filters views with name starting with provided value. Search will be case insensitive.

name-eq string

<optional>, default is null
Filters views with name equal to provided value ignoring case.

format enum

<optional>, default is 'FULL'
Response format for view objects, possible values are ID, SHORT, FULL, EDIT. See Formats.

include-deleted boolean

<optional>, default is false
When value is true TermWeb will include softly deleted objects to search results.
This function is available only to System or client administrators.

Response documentation
Headers

Content-Type

application/json;charset=UTF-8

Payload

body number

Found row number for specified parameters, in case when nothing found return 0.

Get

GET /api/v4/views/{id}

Description

Looks for view with specified id.

Request documentation

Path parameters

id number

View id to look for

format enum

<optional>, default is 'FULL'
Response format for view objects, possible values are ID, SHORT, FULL, EDIT. See Formats.

include-deleted boolean

<optional>, default is false
When value is true TermWeb will include softly deleted objects to search results.
This function is available only to System or client administrators.

Response documentation

Headers

Content-Type

application/json;charset=UTF-8

Payload

body View

JSON object of View.

Create

POST /api/v4/views/

Description

Creates new view from JSON data sent in payload.

Request documentation

Payload

body View

JSON object of type View.

format enum

<optional>, default is 'FULL'
Response format for view objects, possible values are ID, SHORT, FULL, EDIT. See Formats.

Response documentation
Headers

Content-Type

application/json;charset=UTF-8

Payload

body View

Created object of view.

Update

PUT /api/v4/views/{id}

Description

Updates existing view from JSON data sent in payload.

Request documentation

Headers

Content-Type

application/json

Path parameters

id number

Id of View which need to be updated

Payload

body View

JSON object of type View. Value of id and oid attribute specified in payload will be ignored by server.
Don’t forget to include "version" attribute value.
Missing attributes in JSON object or null values will erase that value on server side.

format enum

<optional>, default is 'FULL'
Response format for view objects, possible values are ID, SHORT, FULL, EDIT. See Formats.

Response documentation
Headers

Content-Type

application/json;charset=UTF-8

Payload

body View

Updated view object.

Partial update

PUT /api/v4/views/partial/{id}

Description

It updates only specified parts of view from JSON data sent in payload. Unlike method Update, patch will only update values of object which are present in JSON without modifying other fields which are not present in JSON.

Request documentation

Path parameters

id number

Id of View which need to be updated

Payload

body View

JSON object of type View. Value of id and oid attribute specified in payload will be ignored by server.
Missing attributes in JSON object will be omitted. Fields in JSON object with null will be cleared.
Don’t forget to include "version" attribute value.

format enum

<optional>, default is 'FULL'
Response format for view objects, possible values are ID, SHORT, FULL, EDIT. See Formats.

Response documentation
Headers

Content-Type

application/json;charset=UTF-8

Payload

body View

Patched view object.

Delete

DELETE /api/v4/views/{id}

Description

Deletes view with specified id.

Request documentation

Path parameters

id number

View id to delete

Response documentation
Headers

Content-Type

text/plain;charset=UTF-8

Status

code number

204 No Content in case of successful deletion

Delete async

DELETE /api/v4/views/async/{id[]}

Description

Deletes views with specified ids.
This operation may run asynchronous when deletion takes more than 15 seconds. In that case server will return http status code 202 Accepted.

Request documentation

Path parameters

id number[]

View ids of views to delete

Response documentation
Headers

Content-Type

application/json;charset=UTF-8

Status

code number

200 OK in case of successful deletion or 204 Accepted when operation is still deleting.

Payload attributes InvocationResult

result Map<number,boolean>

When operation has completed successfully, this result will contain map with entries where key is view id and value is boolean flag indicating result of deletion.

jobTaskId number

When operation went to asynchronous deletion, this value will have id of running job task. See JobTask.

13.6. Terminology

13.6.1. Concepts endpoint

Description

Concepts are a key part of the TermWeb object structure. They join together related terms from different languages. To avoid data duplication users can define concept level fields which will have common attributes, like; definition, source reference, figure, picture, domain, usage note, etc.

Concept DTO
Object attribute Description

cid string

Concept ID. Serial number of this concept in Dictionary. Don’t confuse with object id which is unique for whole TermWeb installation and cid unique only for one Dictionary.

sectionOid string

Section old object oid to which this Concept belongs to.

domainList string[]

Domain old object oids to which this Concept related.

terms Term[]

An array of terms related to this Concept.

conceptRelations ConceptRelation[]

An array of Concept relation link objects.

languageCodesEditable string[]

A list of language codes which can be edited by current user. Language code is ISO639-2 three-letter lowercase code.

permissions Map<ConceptPermission,boolean>

A map of Concept permissions for current user. When user has permission to perform some operation, map will have value true.

fieldMap Map<string,string[]

The map of Field oids and values. Only fields with non-empty values should be included in the map. Line breaks in the value should be encoded as CR LF (\r\n) to correspond with reflink positions.
Only fields with type MULTISELECT can have multiple values.

comments Comment[]

List of last comments created for this concept.

dictionaryId number

Dictionary id to which concept related.

clientId number

Client DTO id to which object belongs

id number

Concept id.

oid string

Concept oid. This is object id from old objects.

deleted number

true when object has been marked as deleted in database.

created Object

Metadata object containing information about creation

created.id number

User id created that object

created.name string

User login created that object

created.fullName string

User full name created that object

created.time number

Created date and time in milliseconds since Unix Epoch

created.oid string

User oid created that object (provided for backward compatibility)

changed Object

Metadata object containing information about last modification

changed.id number

User id changed that object

changed.name string

User login changed that object

changed.fullName string

User full name changed that object

changed.time number

Last change date and time in milliseconds since Unix Epoch

changed.oid string

User oid changed that object (provided for backward compatibility)

Concept permissions enum
Value Description

CONCEPT_EDIT_FIELDS string

The user can edit concept level fields.

CONCEPT_UPDATE string

The user can edit a concept or restore changes in history.

CONCEPT_DELETE string

The user can delete a concept.

CONCEPT_PRINT string

The user may print a concept.

CONCEPT_VIEW_HISTORY string

The user can see change history for concepts.

RESTORE_STATE string

The user can restore to state in concept history.

TERM_CREATE string

The user is allowed to create new terms and restore deleted terms from history.

Concept Relation DTO
Object attribute Description

dictionaryId number

Dictionary id in which that relation has been created.

sourceConceptId number

Source Concept id of this relation.

targetConceptId number

Target Concept id of this relation.

type enum

Concept relation type, value is numeric. Possible values are: 'GENERIC' - 0, 'PARTITIVE' - 1, 'TEMPORAL' - 2, 'SPATIAL' - 3, 'ASSOCIATIVE' - 4

attribute enum

Concept relation attribute, depends on value of type attribute. Possible values are: 'GENERIC_SUPERORDINATE' - 0, 'GENERIC_SUBORDINATE' - 1,
'PARTITIVE_SUPERORDINATE' - 2, 'PARTITIVE_SUBORDINATE' - 3,
'TEMPORAL_BEFORE' - 4, 'TEMPORAL_CONCURRENT' - 5, 'TEMPORAL_AFTER' - 6,
'SPATIAL_UP' - 7, 'SPATIAL_DOWN' - 8, 'SPATIAL_RIGHT' - 9, 'SPATIAL_LEFT' - 10,
'ASSOCIATIVE_DEFAULT' - 11

text string

Relation specification text.

relationId number

Serial number for this relation. Unique per Dictionary. Assigned by the server on creation.

id number

Concept relation id.

oid string

Concept relation oid. This is object id from old objects.

Get by id

GET /api/v4/concepts/{id}

Description

Looks for concept with specified id.

Request documentation

Path parameters

id number

Concept id to look for

Query parameters

format enum

<optional>, default is 'FULL'
Response format for concept objects, possible values are ID, SHORT, FULL, EDIT. See Formats.

Response documentation

Headers

Content-Type

application/json;charset=UTF-8

Payload

body Concept

JSON object of Concept.

Get by oid

GET /api/v4/concepts/oid/{oid}

Description

Looks for concept with specified oid.

Request documentation

Path parameters

oid number

Concept oid to look for

Query parameters

format enum

<optional>, default is 'FULL'
Response format for concept objects, possible values are ID, SHORT, FULL, EDIT. See Formats.

Response documentation

Headers

Content-Type

application/json;charset=UTF-8

Payload

body Concept

JSON object of Concept.

Get by term id

GET /api/v4/concepts/find-by-term-id

Description

Looks for concept by Term id.

Request documentation
Query parameters

term-id number

Term id to look for

with-comments boolean

<optional>, true when Concept must include comments.

Response documentation

Headers

Content-Type

application/json;charset=UTF-8

Payload

body Concept

JSON object of Concept.

Get by term oid

GET /api/v4/concepts/find-by-term-oid

Description

Looks for concept by Term old object oid.

Request documentation
Query parameters

term-oid number

Term oid to look for

Response documentation

Headers

Content-Type

application/json;charset=UTF-8

Payload

body Concept

JSON object of Concept.

Get by terms ids

GET /api/v4/concepts/find-by-term-ids

Description

Looks for Concepts by terms ids.

Request documentation
Query parameters

term-ids number[]

An array of Term id to look for

with-comments boolean

<optional>, true when Concept must include comments.

Response documentation

Headers

Content-Type

application/json;charset=UTF-8

Payload

body Concept[]

An array of found JSON objects of type Concept.

Create

POST /api/v4/concepts/

Description

Creates new concept from JSON data sent in payload.

Request documentation

Payload

body Concept

JSON object of type Concept.

format enum

<optional>, default is 'FULL'
Response format for concept objects, possible values are ID, SHORT, FULL, EDIT. See Formats.

Response documentation
Headers

Content-Type

application/json;charset=UTF-8

Payload

body Concept

Created object of concept.

Update

PUT /api/v4/concepts/{id}

Description

Updates existing concept from JSON data sent in payload.

Request documentation

Headers

Content-Type

application/json

Path parameters

id number

Id of Concept which need to be updated

Payload

body Concept

JSON object of type Concept. Value of id and oid attribute specified in payload will be ignored by server.
Don’t forget to include "version" attribute value.
Missing attributes in JSON object or null values will erase that value on server side.

format enum

<optional>, default is 'FULL'
Response format for concept objects, possible values are ID, SHORT, FULL, EDIT. See Formats.

Response documentation
Headers

Content-Type

application/json;charset=UTF-8

Payload

body Concept

Updated concept object.

Delete

DELETE /api/v4/concepts/{id}

Description

Deletes concept with specified id.

Request documentation

Path parameters

id number

Concept id to delete

Response documentation
Headers

Content-Type

text/plain;charset=UTF-8

Status

code number

204 No Content in case of successful deletion

Acquire lock

PUT /api/v4/concepts/acquire-lock

Description

Locks concept from future edits by other users.

Request documentation

Headers

Content-Type

application/json

Query parameters

concept-id number

Id of Concept which need to be locked

Payload

body string

Must be empty.

Response documentation
Headers

Content-Type

application/json;charset=UTF-8

Payload

body boolean

true when concept lock has been set.

Release lock

PUT /api/v4/concepts/release-lock

Description

Unlocks Concept and allow future edits by other users.

Request documentation

Headers

Content-Type

application/json

Query parameters

concept-id number

Id of Concept which need to be unlocked

Payload

body string

Must be empty.

Response documentation
Headers

Content-Type

application/json;charset=UTF-8

Payload

body boolean

true when concept lock has been unset.

Print as HTML

GET /api/v4/concepts/print-as-html/{id}

Description

Generates html preview of concept for specified id.

Request documentation

Path parameters

id number

Concept id to look for

Response documentation
Headers

Content-Type

application/json;charset=UTF-8

Payload

body

Body containing HTML text.

Permissions

GET /api/v4/concepts/permissions/{id}

Description

Looks for current user concept permissions with specified id.

Request documentation

Path parameters

id number

Concept id to look for

Query parameters

section-oid string

Section old object oid.

Response documentation

Headers

Content-Type

application/json;charset=UTF-8

Payload

body Concept

JSON object of Concept with filled permission values for concept and its terms. See Concept permissions.

13.6.2. Terms endpoint

Description
Term DTO
Object attribute Description

name string

Term itself.

tid string

Term ID. Serial number of this term in Dictionary. Don’t confuse with object id which is unique for whole TermWeb installation and tid unique only for one Dictionary.
tid consists of two parts: Concept cid + '-' <unique serial number of that term inside of concept>, like 100-5.

conceptId number

Concept id to which this term belongs.

conceptOid string

Concept old object oid to which this term belongs.

languageCode string

Language code. Should be ISO639-2 3-char lower case code.

regionCode string

Geographical Language Variant variantCode for this term if set.

scriptCode string

Orthographical Language Variant variantCode for this term if set.

permissions Map<TermPermission,boolean>

A map of Term permissions for current user. When user has permission to perform some operation, map will have value true.

fieldMap Map<string,string[]

The map of Field oids and values. Only fields with non-empty values should be included in the map. Line breaks in the value should be encoded as CR LF (\r\n) to correspond with reflink positions.
Only fields with type MULTISELECT can have multiple values.

comments Comment[]

List of last comments created for this term.

dictionaryId number

Dictionary id to which term related.

clientId number

Client DTO id to which object belongs

id number

Term id.

oid string

Term oid. This is object id from old objects.

deleted number

true when object has been marked as deleted in database.

created Object

Metadata object containing information about creation

created.id number

User id created that object

created.name string

User login created that object

created.fullName string

User full name created that object

created.time number

Created date and time in milliseconds since Unix Epoch

created.oid string

User oid created that object (provided for backward compatibility)

changed Object

Metadata object containing information about last modification

changed.id number

User id changed that object

changed.name string

User login changed that object

changed.fullName string

User full name changed that object

changed.time number

Last change date and time in milliseconds since Unix Epoch

changed.oid string

User oid changed that object (provided for backward compatibility)

Term permissions enum
Value Description

TERM_UPDATE string

The user can edit a term or restore changes in history.

TERM_DELETE string

The user can delete a term.

Description

Searches for terms form specified dictionaries.

Request documentation

Payload fields TermSearchRequest

dictionaryIds number[]

required, An array of Dictionary ids. Typically used to search from one dictionary, but more than one can be specified.

langCode string

required, Should be ISO639-2 three-letter lower case code.

regionCode string

<optional>, Geographical Language Variant variantCode for this term if set.

scriptCode string

<optional>, Orthographical Language Variant variantCode for this term if set.

filterId number

<optional>, Filter id to use with search.

sectionOids string[]

required, List of Section old object oids to include in search.

domainOids string[]

<optional>, To filter by domains provide a list of Domain old object oids.

quickFilter Filter

<optional>, temporary filter to quickly apply it to search results without creating normal filter. Object of type Filter.

name string

<optional>, Term name to search, or text to search in case of multi field search.

pageSize number

<optional>, Amount of entries to return.

termOid number

<optional>, Term oid. When provided search will look for that Term with terms around it.

searchAfter Object[]

<optional>, internal value with index from which continue next search call to load next page of search results. Can be obtained from TermSearchResponse.

reverse boolean

true when search results are loading backwards.

bidirectional boolean

Can be used only with combination of termOid attribute. true when to load search results surrounding requested term before and after. Otherwise requested Term will be first in search results.

searchOptions.normalized boolean

true to enable normalized search for symbols with length more than 2-byte.

searchOptions.fuzzy boolean

true enable approximate string matching, also known as fuzzy string searching, in search results.

searchOptions.multiEnabled boolean

true when search must include field to values into search. false look as usual only term name.

searchOptions.multiAllFields boolean

true when search must be done in all fields.

searchOptions.fields Map<FieldLevel,Set<string>

A collection of selected Field oids for multi-field search. FieldLevel is enum with values: CONCEPT and TERM.

Response documentation
Headers

Content-Type

application/json;charset=UTF-8

Payload

body TermSearchResponse

Search results object of type TermSearchResponse.

TermSearchResponse
Object attribute Description

total number

Total number of terms available with current search params. Can be unknown in case of complicated search params, result then will be -1.

pageSize number

Page size of search results.

searchAfter Object[]

Internal value with index from which continue next forward search call.

searchBefore Object[]

Internal value with index from which continue next backward search call.

results TermListEntry[]

Found entries for current search results of type TermListEntry.

message string

Server message containing warning or error description.

TermListEntry
Object attribute Description

id number

Term id.

name number

Term name.

dictionaryId number

Dictionary id to which Term related.

termId string

Term tid value.

conceptId number

Concept id.

conceptOid string

Concept oid.

langCode string

ISO639-2 three-letter lower case language code

filterId number

Filter id matched this term. Deprecated.

style string

Value for HTML attribute style. May contain results of conditional formatting from Workflow.

disabled boolean

Term is read-only when value is true.

hidden boolean

Get by terms ids

GET /api/v4/terms/duplicates

Description

Looks for Terms duplicates.

Request documentation
Query parameters

term string

Term name to check for duplicates

dictionary-id string

Dictionary where to look for duplicate terms.

lang-code string

ISO639-2 three-letter lower case language code.

concept-id number

<optional>, Concept id which must be excluded from search results.

region-code string

<optional>, geographical Language Variant variantCode to look for.

script-code string

<optional>, orthographical Language Variant variantCode to look for.

Response documentation

Headers

Content-Type

application/json;charset=UTF-8

Payload

body TermListEntry[]

An array of found JSON objects of type TermListEntry.

13.6.3. Display concepts endpoint

Description

This endpoint is used for getting prepared Concept for display. It contains applied Workflow functions, conditional formatting and views.

It can, for example, set default values to fields on creation or edit.

Please note this endpoint is subject to change in future. It will be merged with Concepts endpoint.

Display Concept DTO
Object attribute Description

sectionId number

Section id to which concept belongs.

requestedByUserId number

User id which requested this concept.

classificationFields DisplayField[]

List of concept classification fields of type Display field. This list can have fewer fields than original entry.

languageCodes string[]

Language codes of terms which are present in concept. Codes are ordered according to Language sortIndex.

termsPerLanguage List<List<DisplayTerm>>

Terms of type Display term grouped by language code assigned on same position in languageCodes attributes.

termSelected boolean

true when display concept has been created with selected term.

concept Concept

Original object of type Concept.

id number

Display concept id.

dictionary_id number

Dictionary id to which display concept related.

metadataFields DisplayField[]

List of display concept metadata fields of type Display field. This list can have fewer fields than original entry.

fields DisplayField[]

List of display concept fields of type Display field. This list can have fewer fields than original entry.

Display Term DTO
Object attribute Description

languageCode string

Language code for a term.

elementId string

Element id for a term consisting of prefix 'T' + term.oid

termField DisplayField

Display field for term name.

id number

Display concept id.

dictionary_id number

Dictionary id to which display concept related.

metadataFields DisplayField[]

List of display concept metadata fields of type Display field. This list can have fewer fields than original entry.

fields DisplayField[]

List of display concept fields of type Display field. This list can have fewer fields than original entry.

Display Field DTO
Object attribute Description

id string

Field old object oid.

label string

English name of Field.

value string[]

Processed and prepared for display value of field from entry.

valueOid string[]

In case when value is related to another object like Dictionary, Section or it has picklist type, this array will contain that objects oids.

cssClass string

CSS class name for an element displaying that field.

cssStyle string

CSS style for an element displaying that field.

readOnly boolean

true when value must read only.

hidden boolean

true when field must not be displayed to user.

Get

GET /api/v4/display-concepts/{id}

Description

Looks for display concept with specified id.

Request documentation

Path parameters

id number

Display concept id to look for

Query parameters

term-id number

Display concept id to look for

load-concept boolean

<optional>, default value true, returns original concept together with response.

Response documentation

Headers

Content-Type

application/json;charset=UTF-8

Payload

body DisplayConcept

JSON object of Display concept.

Create

POST /api/v4/display-concepts/create/{dictionary-id}

Description

Creates new display concept for specified dictionary. Concept is not persisted to database. It creates only stub for a concept with applied workflow functions.

Request documentation

Path parameters

dictionary-id number

Dictionary id where to create new concept.

Response documentation
Headers

Content-Type

application/json;charset=UTF-8

Payload

body DisplayConcept

Created object of display concept.

Edit

PUT /api/v4/display-concepts/edit/{concept-id}

Description

Creates edit version display concept for specified concept. Concept is not persisted to database. It applies workflow functions to a concept on edit start.

Request documentation

Path parameters

concept-id number

Concept id which need to process.

Query parameters

term-id number

Term id - selected term.

Response documentation
Headers

Content-Type

application/json;charset=UTF-8

Payload

body DisplayConcept

Created object of display concept.

Copy

POST /api/v4/display-concepts/copy/{concept-id}

Description

Creates new display concept by copying specified concept. New concept is not persisted to database. It creates only stub for a concept with applied workflow functions.

Request documentation

Path parameters

concept-id number

id of Concept to copy.

Response documentation
Headers

Content-Type

application/json;charset=UTF-8

Payload

body DisplayConcept

Created object of display concept.

Add term

POST /api/v4/display-concepts/add-term/{concept-id}

Description

Creates new Display term for specified concept. New term is not persisted to database. It creates only stub for a term with applied workflow functions.

Request documentation

Path parameters

concept-id number

id of Concept where to create new term.

Response documentation
Headers

Content-Type

application/json;charset=UTF-8

Payload

body DisplayTerm

Created term of DisplayTerm.

Copy term

POST /api/v4/display-concepts/copy-term/{term-id}

Description

Creates new Display term by copying specified term. New term is not persisted to database. It creates only stub for a term with applied workflow functions.

Request documentation

Path parameters

term-id number

id of Concept where to create new term.

Response documentation
Headers

Content-Type

application/json;charset=UTF-8

Payload

body DisplayTerm

Created copy of term.

13.6.4. Comments endpoint

Description

Simplified version of comments.

Comment DTO
Object attribute Description

text string

Comment text.

authorName string

Full name of comment author.

userId number

User id of comment author.

dictionary_id number

Dictionary id to which comment related.

fieldLevel enum

Field level enum which helps to determine type of entry. Possible values are: CONCEPT or TERM.

entryId number

Concept id or Term id for which this comment created.

date number

Creation date and time of comment in milliseconds since Unix Epoch until license is valid.

Find

GET /api/v4/comments/

Description

Finds comments with specified entry id.

Request documentation

Query parameters

entry-id number

Concept id or Term id to look for.

Response documentation
Headers

Content-Type

application/json;charset=UTF-8

Payload

body Comment[]

An array of comments of type Comment.

Create

POST /api/v4/comments/

Description

Creates new comment from JSON data sent in payload.

Request documentation

Query parameters

entry-id number

Concept id or Term id where to create new comment.

Payload

body Comment

JSON object of type Comment containing only filled "text" attribute.

Response documentation
Headers

Content-Type

application/json;charset=UTF-8

Payload

body Comment

Created object of comment.

Delete

DELETE /api/v4/comments/{id}

Description

Deletes comment with specified id.

Request documentation

Path parameters

id number

Comment id to delete

Response documentation
Headers

Content-Type

text/plain;charset=UTF-8

Status

code number

204 No Content in case of successful deletion

13.6.5. History items endpoint

Description
History Item DTO
Object attribute Description

id number

history item id.

oid string

history item oid. This is object id from old objects.

Find dictionary history

GET /api/v4/history/concept/{concept-id}

Description

Returns a page of history items for requested concept.

Request documentation
Path parameters

concept-id number

Concept id where to look for history items.

Response documentation
Headers

Content-Type

application/json;charset=UTF-8

Payload

content HistoryItem[]

Found history items of type History item.

last boolean

indicates if this page is last with current search params

totalElements number

total amount of objects accessible from this endpoint

totalPages number

total number of pages available with current page size and total elements

sort string

current sort params, like 'name,ASC'

numberOfElements number

amount of objects returned with this page

first boolean

indicates if this page is first with current search params

size number

current page size

number number

current page number

Find dictionary history

GET /api/v4/history/dictionary/{dictionary-id}

Description

Returns a page of history items for requested dictionary. Because of current limitations, history items can only be retrieved since last Dictionary structure change.

Request documentation
Path parameters

dictionary-id number

Dictionary id where to look for history items.

Response documentation
Headers

Content-Type

application/json;charset=UTF-8

Payload

content HistoryItem[]

Found history items of type History item.

last boolean

indicates if this page is last with current search params

totalElements number

total amount of objects accessible from this endpoint

totalPages number

total number of pages available with current page size and total elements

sort string

current sort params, like 'name,ASC'

numberOfElements number

amount of objects returned with this page

first boolean

indicates if this page is first with current search params

size number

current page size

number number

current page number

Undo concept

POST /api/v4/history/concept-undo/

Description

Undoing concept changes to specified concepts state in history item.

Request documentation

Query parameters

history-item-id number

History item id to which we need to restore concept state.

Response documentation

Headers

Content-Type

application/json;charset=UTF-8

Payload

body Concept

JSON object of restored Concept object.

Undo dictionary

POST /api/v4/history/dictionary-undo/

Description

Undoing any changes in Dictionary to specified state in history item.

Request documentation

Query parameters

history-item-id number

History item id to which we need to restore dictionary state.

Response documentation

Headers

Content-Type

application/json;charset=UTF-8

Status

code number

200 OK in case of successful transfer or 204 Accepted when operation is still restoring.

Payload attributes InvocationResult

result boolean

true when dictionary successfully restored to requested state.

jobTaskId number

When operation went to asynchronous transfer, this value will have id of running job task. See JobTask.

13.7. UI settings

13.7.1. User data endpoint

The endpoint provides initial data for authentication token required to setup UI client

Session data DTO
Object attribute Description

user User

Current user object of type User.

• Get initial data

GET /api/v4/data

Request documentation
Headers

X-Auth-Token

Unexpired authentication token

Response documentation
Headers

Content-Type

application/json;charset=UTF-8

Payload

body SessionData

JSON object of Session data.

13.7.2. Menu endpoint

Because TermWeb is a hybrid app with combination of server rendering and single page application. We need to share state of menu items between that two parts.

Menu item DTO
Object attribute Description

href string

• Get Top menu

GET /api/v4/ui/menu/top

Returns top menu items for Administration View.

Request documentation
Headers

X-Auth-Token

Unexpired authentication token

Response documentation
Headers

Content-Type

application/json;charset=UTF-8

Payload

body MenuItem[]

An array of menu items available to user of type Menu item.

• Get Side menu

GET /api/v4/ui/menu/side/{idx}

Returns side menu items related to specified top menu idx.

Request documentation
Path parameters

idx string

Top menu item serial number from returned an array of items.

Response documentation
Headers

Content-Type

application/json;charset=UTF-8

Payload

body MenuItem

JSON object of Menu item.

13.7.3. Profile endpoint

Methods to work with personal and account data for users.

Profile DTO
Object attribute Description

user User

• Get profile

GET /api/v4/profile/

Returns profile data for current user.

Request documentation
Headers

X-Auth-Token

Unexpired authentication token

Response documentation
Headers

Content-Type

application/json;charset=UTF-8

Payload

body Profile

JSON object of Profile.

• Update profile

PUT /api/v4/profile/

Request documentation
Headers

Content-Type

application/json;charset=UTF-8

Payload

body Profile

User data of type Profile to update.

Response documentation
Headers

Content-Type

application/json;charset=UTF-8

Payload

body Profile

Updated data of type Profile.

• Change password

PUT /api/v4/profile/password

Updates user password. Password must fulfill validation password rules, otherwise server will reject new value, see Password settings.

Request documentation
Headers

Content-Type

application/json;charset=UTF-8

Payload

body Profile

User data of type Profile containing new password.

Response documentation
Headers

Content-Type

application/json;charset=UTF-8

Payload

body Profile

Updated data of type Profile.

13.7.4. Search settings endpoint

Methods to work with personal search settings. This allows to store user settings between logins.

Search settings DTO
Object attribute Description

userOid string

TBD

• Get user settings

GET /api/v4/user-search-settings/

Returns user search settings for requested user

Request documentation
Query parameters

user-id number

User id

Response documentation
Headers

Content-Type

application/json;charset=UTF-8

Payload

body SearchSettings

JSON object of Search settings.

• Update user settings

PUT /api/v4/user-search-settings/

Request documentation
Headers

Content-Type

application/json;charset=UTF-8

Payload

body SearchSettings

Data of type Search settings to save.

Response documentation
Headers

Content-Type

application/json;charset=UTF-8

Payload

body Profile

Updated data of type Profile.

• Update single search setting

PUT /api/v4/profile/password

Updates only one setting.

Request documentation
Query parameters

user-id number

User id of which setting to update

setting enum

One of the names of attribute of type Search settings.

Payload

body string[]

An array of string values

Response documentation
Headers

Content-Type

application/json;charset=UTF-8

Payload

body SearchSettings

Updated data of type Search settings.

13.8. Grid View

13.8.1. Staging areas endpoint

Description

Staging areas places where users can prepare coming changes to concepts in drafts. Areas can be shared between users.

Staging area DTO
Object attribute Description

name string

Area name.

dictionaryId number

Dictionary id to which staging area related.

clientId number

Client DTO id to which object belongs

id number

Staging area id.

version number

Staging area version number. Represents latest modification counter.

deleted number

true when object has been marked as deleted in database.

created Object

Metadata object containing information about creation

created.id number

User id created that object

created.name string

User login created that object

created.fullName string

User full name created that object

created.time number

Created date and time in milliseconds since Unix Epoch

created.oid string

User oid created that object (provided for backward compatibility)

changed Object

Metadata object containing information about last modification

changed.id number

User id changed that object

changed.name string

User login changed that object

changed.fullName string

User full name changed that object

changed.time number

Last change date and time in milliseconds since Unix Epoch

changed.oid string

User oid changed that object (provided for backward compatibility)

Find

GET /api/v4/staging/

Description

Finds staging areas with specified query parameters available to current user.

Request documentation

Query parameters

dictionary_id number

<optional>, default is null.
Provide an id when you need to filter staging area objects related to specific dictionary.

client_id number

<optional>, default is equal to current client id related to authentication token.
[TIP] Reserved for future releases and can be omitted for now.

name string

<optional>, default is null
Filters staging areas with name starting with provided value. Search will be case insensitive.

name-eq string

<optional>, default is null
Filters staging areas with name equal to provided value ignoring case.

format enum

<optional>, default is 'FULL'
Response format for staging area objects, possible values are ID, SHORT, FULL, EDIT. See Formats.

include-deleted boolean

<optional>, default is false
When value is true TermWeb will include softly deleted objects to search results.
This function is available only to System or client administrators.

size number

<optional>, default is 20
Page size, represents how many of objects can be returned

page number

<optional>, default is 0
Page number, represents from which position to start loading data, in other words offset equal to size * page.

sort string

<optional>, default is null
Order direction of returned data by some attribute, can accept most of object attributes for specific endpoint. For example: 'name', 'name,ASC', 'name,DESC'.

Response documentation
Headers

Content-Type

application/json;charset=UTF-8

Payload

content StagingArea[]

Found staging areas of type Staging area.

last boolean

indicates if this page is last with current search params

totalElements number

total amount of objects accessible from this endpoint

totalPages number

total number of pages available with current page size and total elements

sort string

current sort params, like 'name,ASC'

numberOfElements number

amount of objects returned with this page

first boolean

indicates if this page is first with current search params

size number

current page size

number number

current page number

Row number

GET /api/v4/staging/rownum/{id}

Description

Finds rownumber of staging area with specified filter and sort parameters. Useful when you need to determine page where object is located after creation or update.

Request documentation

Path parameters

id number

Staging area id to look for

sort string

<optional>, default is null
Order direction of returned data by some attribute, can accept most of object attributes for specific endpoint. For example: 'name', 'name,ASC', 'name,DESC'.

Query parameters

dictionary_id number

<optional>, default is null.
Provide an id when you need to filter staging area objects related to specific dictionary.

client_id number

<optional>, default is equal to current client id related to authentication token.
[TIP] Reserved for future releases and can be omitted for now.

name string

<optional>, default is null
Filters staging areas with name starting with provided value. Search will be case insensitive.

name-eq string

<optional>, default is null
Filters staging areas with name equal to provided value ignoring case.

format enum

<optional>, default is 'FULL'
Response format for staging area objects, possible values are ID, SHORT, FULL, EDIT. See Formats.

include-deleted boolean

<optional>, default is false
When value is true TermWeb will include softly deleted objects to search results.
This function is available only to System or client administrators.

Response documentation
Headers

Content-Type

application/json;charset=UTF-8

Payload

body number

Found row number for specified parameters, in case when nothing found return 0.

Get

GET /api/v4/staging/{id}

Description

Looks for staging area with specified id.

Request documentation

Path parameters

id number

Staging area id to look for

format enum

<optional>, default is 'FULL'
Response format for staging area objects, possible values are ID, SHORT, FULL, EDIT. See Formats.

include-deleted boolean

<optional>, default is false
When value is true TermWeb will include softly deleted objects to search results.
This function is available only to System or client administrators.

Response documentation

Headers

Content-Type

application/json;charset=UTF-8

Payload

body StagingArea

JSON object of Staging area.

Create

POST /api/v4/staging/

Description

Creates new staging area from JSON data sent in payload.

Request documentation

Payload

body StagingArea

JSON object of type Staging area.

format enum

<optional>, default is 'FULL'
Response format for staging area objects, possible values are ID, SHORT, FULL, EDIT. See Formats.

Response documentation
Headers

Content-Type

application/json;charset=UTF-8

Payload

body StagingArea

Created object of staging area.

Update

PUT /api/v4/staging/{id}

Description

Updates existing staging area from JSON data sent in payload.

Request documentation

Headers

Content-Type

application/json

Path parameters

id number

Id of Staging area which need to be updated

Payload

body StagingArea

JSON object of type Staging area. Value of id and oid attribute specified in payload will be ignored by server.
Don’t forget to include "version" attribute value.
Missing attributes in JSON object or null values will erase that value on server side.

format enum

<optional>, default is 'FULL'
Response format for staging area objects, possible values are ID, SHORT, FULL, EDIT. See Formats.

Response documentation
Headers

Content-Type

application/json;charset=UTF-8

Payload

body StagingArea

Updated staging area object.

Partial update

PUT /api/v4/staging/partial/{id}

Description

It updates only specified parts of staging area from JSON data sent in payload. Unlike method Update, patch will only update values of object which are present in JSON without modifying other fields which are not present in JSON.

Request documentation

Path parameters

id number

Id of Staging area which need to be updated

Payload

body StagingArea

JSON object of type Staging area. Value of id and oid attribute specified in payload will be ignored by server.
Missing attributes in JSON object will be omitted. Fields in JSON object with null will be cleared.
Don’t forget to include "version" attribute value.

format enum

<optional>, default is 'FULL'
Response format for staging area objects, possible values are ID, SHORT, FULL, EDIT. See Formats.

Response documentation
Headers

Content-Type

application/json;charset=UTF-8

Payload

body StagingArea

Patched staging area object.

Delete

DELETE /api/v4/staging/{id}

Description

Deletes staging area with specified id.

Request documentation

Path parameters

id number

Staging area id to delete

Response documentation
Headers

Content-Type

text/plain;charset=UTF-8

Status

code number

204 No Content in case of successful deletion

Delete async

DELETE /api/v4/staging/async/{id[]}

Description

Deletes staging areas with specified ids.
This operation may run asynchronous when deletion takes more than 15 seconds. In that case server will return http status code 202 Accepted.

Request documentation

Path parameters

id number[]

Staging area ids of staging areas to delete

Response documentation
Headers

Content-Type

application/json;charset=UTF-8

Status

code number

200 OK in case of successful deletion or 204 Accepted when operation is still deleting.

Payload attributes InvocationResult

result Map<number,boolean>

When operation has completed successfully, this result will contain map with entries where key is staging area id and value is boolean flag indicating result of deletion.

jobTaskId number

When operation went to asynchronous deletion, this value will have id of running job task. See JobTask.

13.8.2. Concept drafts endpoint

Description

Concept drafts contains new data. To make this data available draft must be published. When draft is deleted Concept remains untouched. But user can mark draft for deletion and publish that change and then concept will be deleted.

Concept draft DTO
Object attribute Description

areaId number

Staging area id to which this draft belongs.

clientId number

Client DTO id to which object belongs

id number

Concept draft id.

version number

Concept draft version number. Represents latest modification counter.

deleted number

true when object has been marked as deleted in database.

created Object

Metadata object containing information about creation

created.id number

User id created that object

created.name string

User login created that object

created.fullName string

User full name created that object

created.time number

Created date and time in milliseconds since Unix Epoch

created.oid string

User oid created that object (provided for backward compatibility)

changed Object

Metadata object containing information about last modification

changed.id number

User id changed that object

changed.name string

User login changed that object

changed.fullName string

User full name changed that object

changed.time number

Last change date and time in milliseconds since Unix Epoch

changed.oid string

User oid changed that object (provided for backward compatibility)

Get

GET /api/v4/concept-drafts/{id}

Find

POST /api/v4/concept-drafts/area/{area-id}/

Changed concepts

GET /api/v4/concept-drafts/area/{area-id}/concepts-changed

Create

POST /api/v4/concept-drafts/area/{area-id}/concept/

Create from concepts

POST /api/v4/concept-drafts/area/{area-id}/concept/

Add term

POST /api/v4/concept-drafts/area/{area-id}/new-term/

Update

PUT /api/v4/concept-drafts/{id}/

Update bulk

POST /api/v4/concept-drafts/area/{area-id}/bulk-update/

Merge

PUT /api/v4/concept-drafts/merge/{id}

Delete

DELETE /api/v4/concept-drafts/{id}

Publish

PUT /api/v4/concept-drafts/publish/

13.8.3. Workflows endpoint

Description

Client administrator or dictionary administrator should be able to create/edit workflow for Dictionary.
Workflows allows to setup conditional formatting and triggers on some events.

Workflow DTO
Object attribute Description

name string

Workflow name.

dictionaryId number

Dictionary id to which workflow related.

clientId number

Client DTO id to which object belongs

id number

Workflow id.

oid string

Workflow oid. This is object id from old objects.

created Object

Metadata object containing information about creation

created.id number

User id created that object

created.name string

User login created that object

created.fullName string

User full name created that object

created.time number

Created date and time in milliseconds since Unix Epoch

created.oid string

User oid created that object (provided for backward compatibility)

changed Object

Metadata object containing information about last modification

changed.id number

User id changed that object

changed.name string

User login changed that object

changed.fullName string

User full name changed that object

changed.time number

Last change date and time in milliseconds since Unix Epoch

changed.oid string

User oid changed that object (provided for backward compatibility)

Find

GET /api/v4/workflows/

Description

Finds workflows with specified query parameters available to current user.

Request documentation

Query parameters

dictionary_id number

<optional>, default is null.
Provide an id when you need to filter workflow objects related to specific dictionary.

client_id number

<optional>, default is equal to current client id related to authentication token.
[TIP] Reserved for future releases and can be omitted for now.

name string

<optional>, default is null
Filters workflows with name starting with provided value. Search will be case insensitive.

name-eq string

<optional>, default is null
Filters workflows with name equal to provided value ignoring case.

format enum

<optional>, default is 'FULL'
Response format for workflow objects, possible values are ID, SHORT, FULL, EDIT. See Formats.

include-deleted boolean

<optional>, default is false
When value is true TermWeb will include softly deleted objects to search results.
This function is available only to System or client administrators.

size number

<optional>, default is 20
Page size, represents how many of objects can be returned

page number

<optional>, default is 0
Page number, represents from which position to start loading data, in other words offset equal to size * page.

sort string

<optional>, default is null
Order direction of returned data by some attribute, can accept most of object attributes for specific endpoint. For example: 'name', 'name,ASC', 'name,DESC'.

Response documentation
Headers

Content-Type

application/json;charset=UTF-8

Payload

content Workflow[]

Found workflows of type Workflow.

last boolean

indicates if this page is last with current search params

totalElements number

total amount of objects accessible from this endpoint

totalPages number

total number of pages available with current page size and total elements

sort string

current sort params, like 'name,ASC'

numberOfElements number

amount of objects returned with this page

first boolean

indicates if this page is first with current search params

size number

current page size

number number

current page number

Row number

GET /api/v4/workflows/rownum/{id}

Description

Finds rownumber of workflow with specified filter and sort parameters. Useful when you need to determine page where object is located after creation or update.

Request documentation

Path parameters

id number

Workflow id to look for

sort string

<optional>, default is null
Order direction of returned data by some attribute, can accept most of object attributes for specific endpoint. For example: 'name', 'name,ASC', 'name,DESC'.

Query parameters

dictionary_id number

<optional>, default is null.
Provide an id when you need to filter workflow objects related to specific dictionary.

client_id number

<optional>, default is equal to current client id related to authentication token.
[TIP] Reserved for future releases and can be omitted for now.

name string

<optional>, default is null
Filters workflows with name starting with provided value. Search will be case insensitive.

name-eq string

<optional>, default is null
Filters workflows with name equal to provided value ignoring case.

format enum

<optional>, default is 'FULL'
Response format for workflow objects, possible values are ID, SHORT, FULL, EDIT. See Formats.

include-deleted boolean

<optional>, default is false
When value is true TermWeb will include softly deleted objects to search results.
This function is available only to System or client administrators.

Response documentation
Headers

Content-Type

application/json;charset=UTF-8

Payload

body number

Found row number for specified parameters, in case when nothing found return 0.

Get

GET /api/v4/workflows/{id}

Description

Looks for workflow with specified id.

Request documentation

Path parameters

id number

Workflow id to look for

format enum

<optional>, default is 'FULL'
Response format for workflow objects, possible values are ID, SHORT, FULL, EDIT. See Formats.

include-deleted boolean

<optional>, default is false
When value is true TermWeb will include softly deleted objects to search results.
This function is available only to System or client administrators.

Response documentation

Headers

Content-Type

application/json;charset=UTF-8

Payload

body Workflow

JSON object of Workflow.

Create

POST /api/v4/workflows/

Description

Creates new workflow from JSON data sent in payload.

Request documentation

Payload

body Workflow

JSON object of type Workflow.

format enum

<optional>, default is 'FULL'
Response format for workflow objects, possible values are ID, SHORT, FULL, EDIT. See Formats.

Response documentation
Headers

Content-Type

application/json;charset=UTF-8

Payload

body Workflow

Created object of workflow.

Update

PUT /api/v4/workflows/{id}

Description

Updates existing workflow from JSON data sent in payload.

Request documentation

Headers

Content-Type

application/json

Path parameters

id number

Id of Workflow which need to be updated

Payload

body Workflow

JSON object of type Workflow. Value of id and oid attribute specified in payload will be ignored by server.
Don’t forget to include "version" attribute value.
Missing attributes in JSON object or null values will erase that value on server side.

format enum

<optional>, default is 'FULL'
Response format for workflow objects, possible values are ID, SHORT, FULL, EDIT. See Formats.

Response documentation
Headers

Content-Type

application/json;charset=UTF-8

Payload

body Workflow

Updated workflow object.

Partial update

PUT /api/v4/workflows/partial/{id}

Description

It updates only specified parts of workflow from JSON data sent in payload. Unlike method Update, patch will only update values of object which are present in JSON without modifying other fields which are not present in JSON.

Request documentation

Path parameters

id number

Id of Workflow which need to be updated

Payload

body Workflow

JSON object of type Workflow. Value of id and oid attribute specified in payload will be ignored by server.
Missing attributes in JSON object will be omitted. Fields in JSON object with null will be cleared.
Don’t forget to include "version" attribute value.

format enum

<optional>, default is 'FULL'
Response format for workflow objects, possible values are ID, SHORT, FULL, EDIT. See Formats.

Response documentation
Headers

Content-Type

application/json;charset=UTF-8

Payload

body Workflow

Patched workflow object.

Delete

DELETE /api/v4/workflows/{id}

Description

Deletes workflow with specified id.

Request documentation

Path parameters

id number

Workflow id to delete

Response documentation
Headers

Content-Type

text/plain;charset=UTF-8

Status

code number

204 No Content in case of successful deletion

Delete async

DELETE /api/v4/workflows/async/{id[]}

Description

Deletes workflows with specified ids.
This operation may run asynchronous when deletion takes more than 15 seconds. In that case server will return http status code 202 Accepted.

Request documentation

Path parameters

id number[]

Workflow ids of workflows to delete

Response documentation
Headers

Content-Type

application/json;charset=UTF-8

Status

code number

200 OK in case of successful deletion or 204 Accepted when operation is still deleting.

Payload attributes InvocationResult

result Map<number,boolean>

When operation has completed successfully, this result will contain map with entries where key is workflow id and value is boolean flag indicating result of deletion.

jobTaskId number

When operation went to asynchronous deletion, this value will have id of running job task. See JobTask.

13.8.4. Projects endpoint

Description
Project DTO
Object attribute Description

name string

Project name.

dictionaryId number

Dictionary id to which project related.

clientId number

Client DTO id to which object belongs

id number

Project id.

oid string

Project oid. This is object id from old objects.

created Object

Metadata object containing information about creation

created.id number

User id created that object

created.name string

User login created that object

created.fullName string

User full name created that object

created.time number

Created date and time in milliseconds since Unix Epoch

created.oid string

User oid created that object (provided for backward compatibility)

changed Object

Metadata object containing information about last modification

changed.id number

User id changed that object

changed.name string

User login changed that object

changed.fullName string

User full name changed that object

changed.time number

Last change date and time in milliseconds since Unix Epoch

changed.oid string

User oid changed that object (provided for backward compatibility)

Find

GET /api/v4/projects/

Description

Finds projects with specified query parameters available to current user.

Request documentation

Query parameters

dictionary_id number

<optional>, default is null.
Provide an id when you need to filter project objects related to specific dictionary.

client_id number

<optional>, default is equal to current client id related to authentication token.
[TIP] Reserved for future releases and can be omitted for now.

name string

<optional>, default is null
Filters projects with name starting with provided value. Search will be case insensitive.

name-eq string

<optional>, default is null
Filters projects with name equal to provided value ignoring case.

format enum

<optional>, default is 'FULL'
Response format for project objects, possible values are ID, SHORT, FULL, EDIT. See Formats.

include-deleted boolean

<optional>, default is false
When value is true TermWeb will include softly deleted objects to search results.
This function is available only to System or client administrators.

size number

<optional>, default is 20
Page size, represents how many of objects can be returned

page number

<optional>, default is 0
Page number, represents from which position to start loading data, in other words offset equal to size * page.

sort string

<optional>, default is null
Order direction of returned data by some attribute, can accept most of object attributes for specific endpoint. For example: 'name', 'name,ASC', 'name,DESC'.

Response documentation
Headers

Content-Type

application/json;charset=UTF-8

Payload

content Project[]

Found projects of type Project.

last boolean

indicates if this page is last with current search params

totalElements number

total amount of objects accessible from this endpoint

totalPages number

total number of pages available with current page size and total elements

sort string

current sort params, like 'name,ASC'

numberOfElements number

amount of objects returned with this page

first boolean

indicates if this page is first with current search params

size number

current page size

number number

current page number

Row number

GET /api/v4/projects/rownum/{id}

Description

Finds rownumber of project with specified filter and sort parameters. Useful when you need to determine page where object is located after creation or update.

Request documentation

Path parameters

id number

Project id to look for

sort string

<optional>, default is null
Order direction of returned data by some attribute, can accept most of object attributes for specific endpoint. For example: 'name', 'name,ASC', 'name,DESC'.

Query parameters

dictionary_id number

<optional>, default is null.
Provide an id when you need to filter project objects related to specific dictionary.

client_id number

<optional>, default is equal to current client id related to authentication token.
[TIP] Reserved for future releases and can be omitted for now.

name string

<optional>, default is null
Filters projects with name starting with provided value. Search will be case insensitive.

name-eq string

<optional>, default is null
Filters projects with name equal to provided value ignoring case.

format enum

<optional>, default is 'FULL'
Response format for project objects, possible values are ID, SHORT, FULL, EDIT. See Formats.

include-deleted boolean

<optional>, default is false
When value is true TermWeb will include softly deleted objects to search results.
This function is available only to System or client administrators.

Response documentation
Headers

Content-Type

application/json;charset=UTF-8

Payload

body number

Found row number for specified parameters, in case when nothing found return 0.

Get

GET /api/v4/projects/{id}

Description

Looks for project with specified id.

Request documentation

Path parameters

id number

Project id to look for

format enum

<optional>, default is 'FULL'
Response format for project objects, possible values are ID, SHORT, FULL, EDIT. See Formats.

include-deleted boolean

<optional>, default is false
When value is true TermWeb will include softly deleted objects to search results.
This function is available only to System or client administrators.

Response documentation

Headers

Content-Type

application/json;charset=UTF-8

Payload

body Project

JSON object of Project.

Create

POST /api/v4/projects/

Description

Creates new project from JSON data sent in payload.

Request documentation

Payload

body Project

JSON object of type Project.

format enum

<optional>, default is 'FULL'
Response format for project objects, possible values are ID, SHORT, FULL, EDIT. See Formats.

Response documentation
Headers

Content-Type

application/json;charset=UTF-8

Payload

body Project

Created object of project.

Update

PUT /api/v4/projects/{id}

Description

Updates existing project from JSON data sent in payload.

Request documentation

Headers

Content-Type

application/json

Path parameters

id number

Id of Project which need to be updated

Payload

body Project

JSON object of type Project. Value of id and oid attribute specified in payload will be ignored by server.
Don’t forget to include "version" attribute value.
Missing attributes in JSON object or null values will erase that value on server side.

format enum

<optional>, default is 'FULL'
Response format for project objects, possible values are ID, SHORT, FULL, EDIT. See Formats.

Response documentation
Headers

Content-Type

application/json;charset=UTF-8

Payload

body Project

Updated project object.

Partial update

PUT /api/v4/projects/partial/{id}

Description

It updates only specified parts of project from JSON data sent in payload. Unlike method Update, patch will only update values of object which are present in JSON without modifying other fields which are not present in JSON.

Request documentation

Path parameters

id number

Id of Project which need to be updated

Payload

body Project

JSON object of type Project. Value of id and oid attribute specified in payload will be ignored by server.
Missing attributes in JSON object will be omitted. Fields in JSON object with null will be cleared.
Don’t forget to include "version" attribute value.

format enum

<optional>, default is 'FULL'
Response format for project objects, possible values are ID, SHORT, FULL, EDIT. See Formats.

Response documentation
Headers

Content-Type

application/json;charset=UTF-8

Payload

body Project

Patched project object.

Delete

DELETE /api/v4/projects/{id}

Description

Deletes project with specified id.

Request documentation

Path parameters

id number

Project id to delete

Response documentation
Headers

Content-Type

text/plain;charset=UTF-8

Status

code number

204 No Content in case of successful deletion

Delete async

DELETE /api/v4/projects/async/{id[]}

Description

Deletes projects with specified ids.
This operation may run asynchronous when deletion takes more than 15 seconds. In that case server will return http status code 202 Accepted.

Request documentation

Path parameters

id number[]

Project ids of projects to delete

Response documentation
Headers

Content-Type

application/json;charset=UTF-8

Status

code number

200 OK in case of successful deletion or 204 Accepted when operation is still deleting.

Payload attributes InvocationResult

result Map<number,boolean>

When operation has completed successfully, this result will contain map with entries where key is project id and value is boolean flag indicating result of deletion.

jobTaskId number

When operation went to asynchronous deletion, this value will have id of running job task. See JobTask.

14. API methods Index

Authentication

Clients

API synchronization settings

Job tasks

License

Features

Users

Groups

Permissions

Dictionaries

Sections

Fields

Domains

Filters

Views

Concepts

Terms

Display concepts

Comments

History

User Session data

User Profile

UI Menu

User search settings

Workflows

Projects

15. DTO Index