1. Introduction
This is the REST API documentation for TermWeb 4.0.7-0. 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 openapi.yaml.
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
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
{
"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 |
<optional>, default is 20 |
page |
<optional>, default is 0 |
sort |
<optional>, default is null |
List response
{
"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 |
requested resources from endpoint |
last |
indicates if this page is last with current search params |
totalElements |
total amount of objects accessible from this endpoint |
totalPages |
total number of pages available with current page size and total elements |
sort |
current sort params, like |
numberOfElements |
amount of objects returned with this page |
first |
indicates if this page is first with current search params |
size |
current page size |
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 |
id |
User id created that object |
name |
User login created that object |
|
fullName |
User full name created that object |
|
time |
Created date and time in milliseconds since Unix Epoch |
|
oid |
User oid created that object (provided for backward compatibility) |
|
changed |
id |
User id changed that object |
name |
User login changed that object |
|
fullName |
User full name changed that object |
|
time |
Last change date and time in milliseconds since Unix Epoch |
|
oid |
User oid changed that object (provided for backward compatibility) |
|
client_id |
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. |
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 |
FULL |
Search results will have all attributes, including id, name and metadata. |
EDIT |
Includes everything from |
• NamedObject interface
Server may return for some requests simplified form of object containing only object id and name.
Object attribute | Description |
---|---|
name |
Name of object |
oid |
Old object oid |
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 | |
---|---|
|
application/x-www-form-urlencoded |
Path parameters |
|
Query parameters |
|
Payload fields |
|
|
<optional>, default is 'admin', or any other client login name in case of multitenant installation |
|
user login |
|
user password |
|
<optional>, default is 'eng' |
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 | |||||
---|---|---|---|---|---|
|
application/json;charset=UTF-8 |
||||
Payload fields |
|||||
token |
|
||||
errorMessage |
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 | |
---|---|
|
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 | |
---|---|
|
Unexpired authentication token |
Response documentation
Headers | |
---|---|
|
application/application/json;charset=UTF-8 |
Payload fields |
|
tokenValid |
|
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 | |
---|---|
|
Unexpired authentication token |
Response documentation
Headers | |
---|---|
|
application/json;charset=UTF-8 |
Payload fields |
|
expires |
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 | |
---|---|
|
Unexpired authentication token |
|
application/json;charset=UTF-8 |
Payload |
|
|
Body must contain only one value – |
Response documentation
Headers | |
---|---|
|
application/json;charset=UTF-8 |
Payload |
|
User data |
User data object specific to current user search settings for requested client |
{
"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 |
Unique name of client. |
active |
Current status of client. |
loginName |
Unique login name for client. May contain only Latin letters and numbers. |
apiKey |
API key for current client. Used in integrations via webservices. |
maxUsers |
Maximum number of users which can be created in that client. |
maxGuests |
Maximum number of current guests which can login and work to that client. |
maxConcurrentUsers |
Maximum number of users in total (names users + guests) which can login and work concurrently with that client. |
currentUsersNumber |
Current number of named users for that client. |
adminUser |
Can be used only with create method. Administrator login for new client. Simplified version of User. |
id |
Client id. |
oid |
Client oid. This is object id from old objects. |
created |
Metadata object containing information about creation |
created.id |
User id created that object |
created.name |
User login created that object |
created.fullName |
User full name created that object |
created.time |
Created date and time in milliseconds since Unix Epoch |
created.oid |
User oid created that object (provided for backward compatibility) |
changed |
Metadata object containing information about last modification |
changed.id |
User id changed that object |
changed.name |
User login changed that object |
changed.fullName |
User full name changed that object |
changed.time |
Last change date and time in milliseconds since Unix Epoch |
changed.oid |
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 | |
---|---|
|
Unexpired authentication token |
Response documentation
Headers | |
---|---|
|
application/json;charset=UTF-8 |
Payload |
|
body |
Array of available clients of type Client. |
• 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 |
client id value |
Response documentation
Headers |
|
---|---|
|
application/json;charset=UTF-8 |
Payload |
|
body |
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 |
<optional>, default is |
login-name-eq |
<optional>, default is |
max-concurrent-users |
<optional>, default is |
max-user-accounts |
<optional>, default is |
name |
<optional>, default is |
name-eq |
<optional>, default is |
format |
<optional>, default is |
include-deleted |
<optional>, default is |
size |
<optional>, default is 20 |
page |
<optional>, default is 0 |
sort |
<optional>, default is null |
Response documentation
Headers | |
---|---|
|
application/json;charset=UTF-8 |
Payload |
|
content |
Found clients of type Client. |
last |
indicates if this page is last with current search params |
totalElements |
total amount of objects accessible from this endpoint |
totalPages |
total number of pages available with current page size and total elements |
sort |
current sort params, like |
numberOfElements |
amount of objects returned with this page |
first |
indicates if this page is first with current search params |
size |
current page size |
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 |
Client id to look for |
sort |
<optional>, default is null |
Query parameters |
|
login-name |
<optional>, default is |
login-name-eq |
<optional>, default is |
max-concurrent-users |
<optional>, default is |
max-user-accounts |
<optional>, default is |
name |
<optional>, default is |
name-eq |
<optional>, default is |
format |
<optional>, default is |
include-deleted |
<optional>, default is |
Response documentation
Headers | |
---|---|
|
application/json;charset=UTF-8 |
Payload |
|
body |
Found row number for specified parameters, in case when nothing found return |
• Get
GET /api/v4/clients/{id}
Description
Looks for client with specified id.
Request documentation
Path parameters |
|
---|---|
id |
Client id to look for |
format |
<optional>, default is |
include-deleted |
<optional>, default is |
Response documentation
Headers |
|
---|---|
|
application/json;charset=UTF-8 |
Payload |
|
body |
JSON object of Client. |
• Create
POST /api/v4/clients/
Description
Creates new client from JSON data sent in payload.
Request documentation
Payload |
|
---|---|
body |
JSON object of type Client. |
format |
<optional>, default is |
Response documentation
Headers | |
---|---|
|
application/json;charset=UTF-8 |
Payload |
|
body |
Created object of client. |
• Update
PUT /api/v4/clients/{id}
Description
Updates existing client from JSON data sent in payload.
Request documentation
Headers |
|
---|---|
|
application/json |
Path parameters |
|
id |
Id of Client which need to be updated |
Payload |
|
body |
JSON object of type Client. Value of |
format |
<optional>, default is |
Response documentation
Headers | |
---|---|
|
application/json;charset=UTF-8 |
Payload |
|
body |
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 PUT /api/v4/clients/{id}
, 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 |
Id of Client which need to be updated |
Payload |
|
body |
JSON object of type Client. Value of |
format |
<optional>, default is |
Response documentation
Headers | |
---|---|
|
application/json;charset=UTF-8 |
Payload |
|
body |
Patched client object. |
• Delete
DELETE /api/v4/clients/{id}
Description
Deletes client with specified id.
Request documentation
Path parameters |
|
---|---|
id |
Client id to delete |
Response documentation
Headers | |
---|---|
|
text/plain;charset=UTF-8 |
Status |
|
code |
|
• 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 |
Client ids of clients to delete |
Response documentation
Headers | |
---|---|
|
application/json;charset=UTF-8 |
Status |
|
code |
|
Payload attributes |
|
result |
When operation has completed successfully, this result will contain map with entries where key is |
jobTaskId |
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 |
Unique name of API sync settings object. |
description |
Description for API sync settings object. |
active |
Current status of API sync settings object. |
dictionaryId |
Dictionary id of the corresponding dictionary. |
languages |
List of languages to which this API sync settings applied. See LangMapping. |
groups |
List of groups to which this API sync settings applied. See GroupMapping. |
filter |
<optional>, Set of conditions applied to this API sync settings. See Filter. |
clientId |
Client id to which object belongs |
id |
API synchronization settings id. |
version |
API synchronization settings version number. Represents latest modification counter. |
created |
Metadata object containing information about creation |
created.id |
User id created that object |
created.name |
User login created that object |
created.fullName |
User full name created that object |
created.time |
Created date and time in milliseconds since Unix Epoch |
created.oid |
User oid created that object (provided for backward compatibility) |
changed |
Metadata object containing information about last modification |
changed.id |
User id changed that object |
changed.name |
User login changed that object |
changed.fullName |
User full name changed that object |
changed.time |
Last change date and time in milliseconds since Unix Epoch |
changed.oid |
User oid changed that object (provided for backward compatibility) |
• LangMapping
Object attribute | Description |
---|---|
langCode |
Code of one of the languages from dictionary related to API sync settings. |
regionCode |
Code of one of the region from language of dictionary related to API sync settings. |
scriptCode |
Code of one of the script from language of dictionary related to API sync settings. |
• GroupMapping
Object attribute | Description |
---|---|
groupId |
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 |
<optional>, default is |
client_id |
<optional>, default is equal to current client id related to authentication token. |
name |
<optional>, default is |
name-eq |
<optional>, default is |
format |
<optional>, default is |
include-deleted |
<optional>, default is |
size |
<optional>, default is 20 |
page |
<optional>, default is 0 |
sort |
<optional>, default is null |
Response documentation
Headers | |
---|---|
|
application/json;charset=UTF-8 |
Payload |
|
content |
Found API sync settings of type APISyncSettings. |
last |
indicates if this page is last with current search params |
totalElements |
total amount of objects accessible from this endpoint |
totalPages |
total number of pages available with current page size and total elements |
sort |
current sort params, like |
numberOfElements |
amount of objects returned with this page |
first |
indicates if this page is first with current search params |
size |
current page size |
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 |
API synchronization settings id to look for |
sort |
<optional>, default is null |
Query parameters |
|
dictionary_id |
<optional>, default is |
client_id |
<optional>, default is equal to current client id related to authentication token. |
name |
<optional>, default is |
name-eq |
<optional>, default is |
format |
<optional>, default is |
include-deleted |
<optional>, default is |
Response documentation
Headers | |
---|---|
|
application/json;charset=UTF-8 |
Payload |
|
body |
Found row number for specified parameters, in case when nothing found return |
• Get
GET /api/v4/sync-settings/{id}
Description
Looks for API sync settings with specified id.
Request documentation
Path parameters |
|
---|---|
id |
API synchronization settings id to look for |
format |
<optional>, default is |
include-deleted |
<optional>, default is |
Response documentation
Headers |
|
---|---|
|
application/json;charset=UTF-8 |
Payload |
|
body |
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 |
JSON object of type APISyncSettings. |
format |
<optional>, default is |
Response documentation
Headers | |
---|---|
|
application/json;charset=UTF-8 |
Payload |
|
body |
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 |
|
---|---|
|
application/json |
Path parameters |
|
id |
Id of API synchronization settings which need to be updated |
Payload |
|
body |
JSON object of type APISyncSettings. Value of |
format |
<optional>, default is |
Response documentation
Headers | |
---|---|
|
application/json;charset=UTF-8 |
Payload |
|
body |
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 PUT /api/v4/sync-settings/{id}
, 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 |
Id of API synchronization settings which need to be updated |
Payload |
|
body |
JSON object of type APISyncSettings. Value of |
format |
<optional>, default is |
Response documentation
Headers | |
---|---|
|
application/json;charset=UTF-8 |
Payload |
|
body |
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 |
API synchronization settings id to delete |
Response documentation
Headers | |
---|---|
|
text/plain;charset=UTF-8 |
Status |
|
code |
|
• 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 |
API synchronization settings ids of API sync settings to delete |
Response documentation
Headers | |
---|---|
|
application/json;charset=UTF-8 |
Status |
|
code |
|
Payload attributes |
|
result |
When operation has completed successfully, this result will contain map with entries where key is |
jobTaskId |
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 |
Job object id to which this task is related. Internal use only. |
ordinal |
Serial number of this task in job. Internal use only. Internal use only. |
parentTaskId |
Job task parent id. Tasks can launch subtasks. Internal use only. |
launchedAt |
Launch date and time in milliseconds since Unix Epoch. |
launchedBy |
User id launched this job. |
launchedByLocale |
Locale used by user during launch of job. |
finishedAt |
Finish date and time in milliseconds since Unix Epoch |
stoppedBy |
User id which stopped this job. Filled only when job has been interrupted. |
processed |
Number of processed objects by this task. |
processedSuccessfully |
Number of successfully processed objects without failures by this task. |
total |
Total amount of objects to process by this task. |
status |
Job task status. Possible values are |
id |
Job task id. |
version |
Job task version number. Represents latest modification counter. |
JobTaskStatus
Status | Description |
---|---|
CREATED |
JobTask has been created for execution. Params are stored in DB. |
RUNNING |
JobTask is executed by one of the ExecutorService. In case of crash job can stuck in that status. |
PAUSED |
JobTask has been paused by user call. |
HALTED |
JobTask has been halted by system call (e.g. shutdown). TermWeb will restore halted tasks on next run. |
FAILURE |
During execution of code in JobTask something went wrong. Execution has been stopped. |
STOPPED |
JobTask has been stopped by user call. |
FINISHED |
JobTask has been successfully completed. |
TERMINATED |
JobTask execution has been interrupted by another JobTask (e.g. sequential update of Dictionary ES index). |
JobTaskResult DTO
Object attribute | Description |
---|---|
jobId |
Job object id to which this task is related to. Internal use only. |
jobTaskId |
Job task id to which this results related to. |
parentJobTaskId |
Job task parent id. Tasks can launch subtasks. Internal use only. |
createdAt |
Launch date and time in milliseconds since Unix Epoch. |
results |
User id launched this job. |
id |
Job task id. |
version |
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 | |
---|---|
|
Unexpired authentication token |
Response documentation
Headers |
|
---|---|
|
application/json;charset=UTF-8 |
Payload |
|
body |
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 |
Job task id to look for |
Response documentation
Headers |
|
---|---|
|
application/json;charset=UTF-8 |
Payload |
|
body |
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 |
Job task id to look for |
Response documentation
Headers |
|
---|---|
|
application/json;charset=UTF-8 |
Payload |
|
body |
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 |
|
owner |
Name of owner for that license, like Big Company Name |
expireDate |
Expiration date and time in milliseconds since Unix Epoch until license is valid. |
clients |
Number of clients which can be created in this installation by using this license. 0 means "Unlimited" |
guestAccount |
|
maxAccounts |
Maximum number of named users. 0 means "Unlimited" |
maxConcurrentUsers |
Maximum number of users which can use system concurrently (including guest users). |
maxConcurrentGuests |
Maximum number of guest users which can use system concurrently. |
xmlRpcApi |
|
soapApi |
|
ldapSupport |
|
samlSupport |
|
availableUserSlots |
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 | |
---|---|
|
Unexpired authentication token |
Response documentation
Headers | |
---|---|
|
application/json;charset=UTF-8 |
Payload |
|
body |
JSON object of License. |
• Update license
POST /api/v4/system/license
Request documentation
Payload | |
---|---|
body |
license text |
Response documentation
Headers | |
---|---|
|
application/json;charset=UTF-8 |
Payload |
|
body |
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 methods 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
or
GET /api/v4/system/features/client/{clientLogin}
Response documentation
Headers | |
---|---|
|
application/json;charset=UTF-8 |
Payload attributes |
|
DEVELOPMENT |
|
SESSION_TIMEOUT |
Server setting for how long authentication token will be valid. Value in seconds. |
MULTIPLE_CLIENT |
|
GUEST_AUTO_DISABLED |
|
MULTIVALUED_SEPARATOR |
Separator for multivalued picklists. |
ALWAYS_WILDCARD |
Default search mode for input string. When |
MAX_FILE_SIZE |
Maximum file size accepted by TermWeb. Size in bytes. |
VERSION |
Version of running TermWeb. |
BUILD_DATETIME |
Date when build has been made of running TermWeb. |
GUEST_TOKEN |
In case when guest login activated for current client (default client or client specified in path parameter |
13.2.6. Features script endpoint
This method wraps response object of GET /api/v4/system/features
into script file. This script file creates in Window object property with name termwebFeatures
which contains all system features including GUEST_TOKEN.
To determine client login server is using http header Referer
when it equals to termweb.properties base.url property, like ${base.url}/client/{clientLogin}
it will look for automatic guest login settings.
Response documentation
Headers | |
---|---|
|
application/javascript; charset=UTF-8 |
Payload |
|
Body |
|
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
password
change password at next logon System administrator:
full name
username
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
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
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 |
Unique username per client of user used as login. May contain only Latin letters and numbers. |
fullName |
Full name of user. |
email |
User email. |
title |
User’s title. |
expDate |
Expiration date and time in milliseconds since Unix Epoch when user be deactivated. |
type |
User type. Usually you cannot specify it on creation or update. |
active |
Status of user. When |
password |
|
confirmPassword |
|
roles |
|
clientIds |
|
groups |
|
sendNotificationEmail |
|
forcePasswordChange |
|
clientId |
Client id to which object belongs |
id |
User id. |
oid |
User oid. This is object id from old objects. |
deleted |
|
created |
Metadata object containing information about creation |
created.id |
User id created that object |
created.name |
User login created that object |
created.fullName |
User full name created that object |
created.time |
Created date and time in milliseconds since Unix Epoch |
created.oid |
User oid created that object (provided for backward compatibility) |
changed |
Metadata object containing information about last modification |
changed.id |
User id changed that object |
changed.name |
User login changed that object |
changed.fullName |
User full name changed that object |
changed.time |
Last change date and time in milliseconds since Unix Epoch |
changed.oid |
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 |
|
---|---|
|
multipart/form-data |
Payload fields |
|
file |
Multipart data containing file contents. |
fileName |
Name of uploaded file |
overwrite-user |
<optional>, default is |
overwrite-group |
<optional>, default is |
Response documentation
Headers |
|
---|---|
|
application/json;charset=UTF-8 |
Payload |
|
userCount |
Number of user created with import. |
groupCount |
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 | |
---|---|
|
Unexpired authentication token |
Response documentation
Headers | |
---|---|
|
application/xml |
|
attachment; filename="some_file_name" |
|
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 |
|
---|---|
|
application/json |
|
Unexpired authentication token |
Payload fields |
|
users |
An array of users ids to update their client mappings. |
clients |
An array of clients ids to which users must me mapped. |
Response documentation
Headers |
|
---|---|
|
application/json;charset=UTF-8 |
Payload |
|
body |
number of successfully updated users |
• Password settings
GET /api/v4/users/password-settings
Description
Returns password settings for this TermWeb installation.
These settings are configured by system administrator in Admin view → System → Administrator tools → Password strength.
Request documentation
Headers | |
---|---|
|
Unexpired authentication token |
Response documentation
Headers | |
---|---|
|
application/json;charset=UTF-8 |
Payload fields |
|
regExp |
String containing regular expression for password validation. |
msg |
String message for user when password is not matching to regular expression. |
• GuestSettings DTO
Object attribute | Description |
---|---|
enabled |
|
username |
Login name for guest user. |
password |
Password for guest user. |
loginMethod |
Setting which configures how guests will login into TermWeb. Possible values are: |
autoAlwaysDisabled |
|
enableFilters |
|
enableSearchModes |
|
enableGridView |
|
enableCommenting |
|
• 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 | |
---|---|
|
Unexpired authentication token |
Response documentation
Headers | |
---|---|
|
application/json;charset=UTF-8 |
Payload |
|
body |
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 | |
---|---|
|
Unexpired authentication token |
Payload |
|
body |
Updates for Guest settings in JSON object of GuestSettings. |
Response documentation
Status |
|
---|---|
code |
|
• Find
GET /api/v4/users/
Description
Finds users with specified query parameters available to current user.
Request documentation
Query parameters |
|
---|---|
login |
<optional>, default is |
full-name |
<optional>, default is |
client_id |
<optional>, default is equal to current client id related to authentication token. |
name |
<optional>, default is |
name-eq |
<optional>, default is |
format |
<optional>, default is |
include-deleted |
<optional>, default is |
size |
<optional>, default is 20 |
page |
<optional>, default is 0 |
sort |
<optional>, default is null |
Response documentation
Headers | |
---|---|
|
application/json;charset=UTF-8 |
Payload |
|
content |
Found users of type User. |
last |
indicates if this page is last with current search params |
totalElements |
total amount of objects accessible from this endpoint |
totalPages |
total number of pages available with current page size and total elements |
sort |
current sort params, like |
numberOfElements |
amount of objects returned with this page |
first |
indicates if this page is first with current search params |
size |
current page size |
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 |
User id to look for |
sort |
<optional>, default is null |
Query parameters |
|
login |
<optional>, default is |
full-name |
<optional>, default is |
client_id |
<optional>, default is equal to current client id related to authentication token. |
name |
<optional>, default is |
name-eq |
<optional>, default is |
format |
<optional>, default is |
include-deleted |
<optional>, default is |
Response documentation
Headers | |
---|---|
|
application/json;charset=UTF-8 |
Payload |
|
body |
Found row number for specified parameters, in case when nothing found return |
• Get
GET /api/v4/users/{id}
Description
Looks for user with specified id.
Request documentation
Path parameters |
|
---|---|
id |
User id to look for |
format |
<optional>, default is |
include-deleted |
<optional>, default is |
Response documentation
Headers |
|
---|---|
|
application/json;charset=UTF-8 |
Payload |
|
body |
JSON object of User. |
• Create
POST /api/v4/users/
Description
Creates new user from JSON data sent in payload.
Request documentation
Payload |
|
---|---|
body |
JSON object of type User. |
format |
<optional>, default is |
Response documentation
Headers | |
---|---|
|
application/json;charset=UTF-8 |
Payload |
|
body |
Created object of user. |
• Update
PUT /api/v4/users/{id}
Description
Updates existing user from JSON data sent in payload.
Request documentation
Headers |
|
---|---|
|
application/json |
Path parameters |
|
id |
Id of User which need to be updated |
Payload |
|
body |
JSON object of type User. Value of |
format |
<optional>, default is |
Response documentation
Headers | |
---|---|
|
application/json;charset=UTF-8 |
Payload |
|
body |
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 PUT /api/v4/users/{id}
, 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 |
Id of User which need to be updated |
Payload |
|
body |
JSON object of type User. Value of |
format |
<optional>, default is |
Response documentation
Headers | |
---|---|
|
application/json;charset=UTF-8 |
Payload |
|
body |
Patched user object. |
• Delete
DELETE /api/v4/users/{id}
Description
Deletes user with specified id.
Request documentation
Path parameters |
|
---|---|
id |
User id to delete |
Response documentation
Headers | |
---|---|
|
text/plain;charset=UTF-8 |
Status |
|
code |
|
• 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 |
User ids of users to delete |
Response documentation
Headers | |
---|---|
|
application/json;charset=UTF-8 |
Status |
|
code |
|
Payload attributes |
|
result |
When operation has completed successfully, this result will contain map with entries where key is |
jobTaskId |
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 |
Unique name per client of group. |
description |
Text describing that group. |
timeout |
Session timeout setting for users of this Group. |
pwdChange |
Number of days till the next password change for users of this Group. |
viewsMap |
A map containing assigned Views to Dictionary. One dictionary can have multiple assigned views. Map structure is: |
filterMap |
A map containing Filter applied to search results from <<doc-dto-dictionary,Dictionary> for users of that Group}. |
type |
A group type. System attribute. Can’t be changed via API. Possible values are: Groups of type |
langCode3 |
When group is Language Group, this value will have three-letter code from ISO 639. |
hasApiAccess |
|
currentUsersNumber |
|
groupMembers |
|
clientId |
Client id to which object belongs |
id |
Group id. |
oid |
Group oid. This is object id from old objects. |
deleted |
|
created |
Metadata object containing information about creation |
created.id |
User id created that object |
created.name |
User login created that object |
created.fullName |
User full name created that object |
created.time |
Created date and time in milliseconds since Unix Epoch |
created.oid |
User oid created that object (provided for backward compatibility) |
changed |
Metadata object containing information about last modification |
changed.id |
User id changed that object |
changed.name |
User login changed that object |
changed.fullName |
User full name changed that object |
changed.time |
Last change date and time in milliseconds since Unix Epoch |
changed.oid |
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 |
<optional>, default is |
include-guest |
<optional>, default is |
include-private |
<optional>, default is |
client_id |
<optional>, default is equal to current client id related to authentication token. |
name |
<optional>, default is |
name-eq |
<optional>, default is |
format |
<optional>, default is |
include-deleted |
<optional>, default is |
size |
<optional>, default is 20 |
page |
<optional>, default is 0 |
sort |
<optional>, default is null |
Response documentation
Headers | |
---|---|
|
application/json;charset=UTF-8 |
Payload |
|
content |
Found groups of type Group. |
last |
indicates if this page is last with current search params |
totalElements |
total amount of objects accessible from this endpoint |
totalPages |
total number of pages available with current page size and total elements |
sort |
current sort params, like |
numberOfElements |
amount of objects returned with this page |
first |
indicates if this page is first with current search params |
size |
current page size |
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 |
Group id to look for |
sort |
<optional>, default is null |
Query parameters |
|
include-all |
<optional>, default is |
include-guest |
<optional>, default is |
include-private |
<optional>, default is |
client_id |
<optional>, default is equal to current client id related to authentication token. |
name |
<optional>, default is |
name-eq |
<optional>, default is |
format |
<optional>, default is |
include-deleted |
<optional>, default is |
Response documentation
Headers | |
---|---|
|
application/json;charset=UTF-8 |
Payload |
|
body |
Found row number for specified parameters, in case when nothing found return |
• Get
GET /api/v4/groups/{id}
Description
Looks for group with specified id.
Request documentation
Path parameters |
|
---|---|
id |
Group id to look for |
format |
<optional>, default is |
include-deleted |
<optional>, default is |
Response documentation
Headers |
|
---|---|
|
application/json;charset=UTF-8 |
Payload |
|
body |
JSON object of Group. |
• Create
POST /api/v4/groups/
Description
Creates new group from JSON data sent in payload.
Request documentation
Payload |
|
---|---|
body |
JSON object of type Group. |
format |
<optional>, default is |
Response documentation
Headers | |
---|---|
|
application/json;charset=UTF-8 |
Payload |
|
body |
Created object of group. |
• Update
PUT /api/v4/groups/{id}
Description
Updates existing group from JSON data sent in payload.
Request documentation
Headers |
|
---|---|
|
application/json |
Path parameters |
|
id |
Id of Group which need to be updated |
Payload |
|
body |
JSON object of type Group. Value of |
format |
<optional>, default is |
Response documentation
Headers | |
---|---|
|
application/json;charset=UTF-8 |
Payload |
|
body |
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 PUT /api/v4/groups/{id}
, 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 |
Id of Group which need to be updated |
Payload |
|
body |
JSON object of type Group. Value of |
format |
<optional>, default is |
Response documentation
Headers | |
---|---|
|
application/json;charset=UTF-8 |
Payload |
|
body |
Patched group object. |
• Delete
DELETE /api/v4/groups/{id}
Description
Deletes group with specified id.
Request documentation
Path parameters |
|
---|---|
id |
Group id to delete |
Response documentation
Headers | |
---|---|
|
text/plain;charset=UTF-8 |
Status |
|
code |
|
• 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 |
Group ids of groups to delete |
Response documentation
Headers | |
---|---|
|
application/json;charset=UTF-8 |
Status |
|
code |
|
Payload attributes |
|
result |
When operation has completed successfully, this result will contain map with entries where key is |
jobTaskId |
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 |
{txt-object-c} an array of dictionary ids for which we’re retrieving permissions information. |
Response documentation
Headers | |
---|---|
|
application/json;charset=UTF-8 |
Payload attributes |
|
dictionaryId |
Dictionary id to which this set of permissions related. |
permissions |
Map of top-level permissions for dictionary. When users have permission to work with any dictionary section, this value will be |
sectionPermissions |
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 |
Same as sectionPermissions except the key in parent map will be Section oid. |
• Dictionary permissions enum
Value | Description |
---|---|
DICT_READ |
User can read dictionary metadata and concepts with terms from it. |
DICT_UPDATE |
User can update dictionary metadata. |
DICT_DELETE |
User able to delete dictionary. |
CONCEPT_CREATE |
User can create a new concept, and restore deleted concepts from history |
CONCEPT_PRINT |
User can print concepts. |
CONCEPT_IMPORT |
User can import concepts. |
CONCEPT_EXPORT |
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 |
Domain name. |
description |
Domain description. |
TBD |
TBD |
clientId |
Client id to which object belongs |
id |
Permission scheme id. |
oid |
Permission scheme oid. This is object id from old objects. |
created |
Metadata object containing information about creation |
created.id |
User id created that object |
created.name |
User login created that object |
created.fullName |
User full name created that object |
created.time |
Created date and time in milliseconds since Unix Epoch |
created.oid |
User oid created that object (provided for backward compatibility) |
changed |
Metadata object containing information about last modification |
changed.id |
User id changed that object |
changed.name |
User login changed that object |
changed.fullName |
User full name changed that object |
changed.time |
Last change date and time in milliseconds since Unix Epoch |
changed.oid |
User oid changed that object (provided for backward compatibility) |
Description
Finds permission schemes for specified client.
Request documentation
Query parameters |
|
---|---|
client_id |
Client id to look for |
Response documentation
Headers | |
---|---|
|
application/json;charset=UTF-8 |
Payload |
|
body |
An array of found permission schemes of type Permission scheme. |
13.5. Dictionaries administration
13.5.1. Dictionaries endpoint
Description
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:
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. |
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 |
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 |
• Dictionary DTO
Object attribute | Description |
---|---|
name |
Dictionary name. |
description |
Description of dictionary. |
sections |
List of Dictionary sections of type Section available for reading by current user. |
allSections |
List of all Dictionary sections of type Section created in Dictionary. |
languages |
List of Dictionary languages of type Language. |
conceptFields |
List of Dictionary concept fields of type Field. |
termFields |
List of Dictionary term fields of type Field. |
emailRecipientId |
User id of email recipient. |
sortIndex |
Order number for displaying in user specified order. |
concepts |
Number of non-deleted concepts in a dictionary. |
clientId |
Client id to which object belongs |
id |
Dictionary id. |
oid |
Dictionary oid. This is object id from old objects. |
created |
Metadata object containing information about creation |
created.id |
User id created that object |
created.name |
User login created that object |
created.fullName |
User full name created that object |
created.time |
Created date and time in milliseconds since Unix Epoch |
created.oid |
User oid created that object (provided for backward compatibility) |
changed |
Metadata object containing information about last modification |
changed.id |
User id changed that object |
changed.name |
User login changed that object |
changed.fullName |
User full name changed that object |
changed.time |
Last change date and time in milliseconds since Unix Epoch |
changed.oid |
User oid changed that object (provided for backward compatibility) |
• Section DTO
Object attribute | Description |
---|---|
name |
Section name. |
viewId |
View id which assigned to section. |
numberOfConcepts |
Number of concepts created in this section |
deletable |
|
sortIndex |
Order number for displaying in user specified order |
dictionaryId |
Dictionary id to which section related. |
clientId |
Client id to which object belongs |
id |
Section id. |
oid |
Section oid. This is object id from old objects. |
deleted |
|
created |
Metadata object containing information about creation |
created.id |
User id created that object |
created.name |
User login created that object |
created.fullName |
User full name created that object |
created.time |
Created date and time in milliseconds since Unix Epoch |
created.oid |
User oid created that object (provided for backward compatibility) |
changed |
Metadata object containing information about last modification |
changed.id |
User id changed that object |
changed.name |
User login changed that object |
changed.fullName |
User full name changed that object |
changed.time |
Last change date and time in milliseconds since Unix Epoch |
changed.oid |
User oid changed that object (provided for backward compatibility) |
• Language DTO
Object attribute | Description |
---|---|
name |
Language name. |
dictionaryId |
Dictionary id in which that language has been created. |
clientId |
Client id in which that language has been created. |
code |
The ISO639-2 code (3 chars) in case of standard code. In case of custom language can contain anything. |
code2 |
The ISO639-1 code (2 chars) to be used for Locale creation, e.g sv, en, pt, de. Can be empty string. |
code3 |
The ISO639-2 code (3 chars) in case of standard code e.g. swe, eng, por, deu, haw. In case of custom language can contain anything. |
isIso |
Flag which indicates if this language is defined in ISO639-2. |
sortIndex |
Order number for displaying in user specified order |
variants |
List of geographical and orthographical variants of type Language Variant. |
rtl |
|
id |
Language id. |
oid |
Language oid. This is object id from old objects. |
deleted |
|
• Language Variant DTO
Object attribute | Description |
---|---|
type |
0 for Geographical, 1 for Orthographical |
code |
Variant code string |
predefined |
|
languageId |
Language id to which this variant belongs to. |
name |
Language variant name. |
sortIndex |
Order number for displaying in user specified order |
id |
Language variant id. |
oid |
Language variant oid. This is object id from old objects. |
deleted |
|
• Field DTO
Object attribute | Description |
---|---|
name |
Field name. |
specifiedName |
The user specified name of the field if any. |
dictionaryId |
Dictionary id to which this field belongs. |
dataCategory |
|
fieldType |
Type of field. Possible values are: |
level |
Level of field. Possible values are: |
model |
Settings of field. Object of type Field Model. |
sortIndex |
Order number for displaying in user specified order |
id |
Field id. |
oid |
Field oid. This is object id from old objects. |
deleted |
|
created |
Metadata object containing information about creation |
created.id |
User id created that object |
created.name |
User login created that object |
created.fullName |
User full name created that object |
created.time |
Created date and time in milliseconds since Unix Epoch |
created.oid |
User oid created that object (provided for backward compatibility) |
changed |
Metadata object containing information about last modification |
changed.id |
User id changed that object |
changed.name |
User login changed that object |
changed.fullName |
User full name changed that object |
changed.time |
Last change date and time in milliseconds since Unix Epoch |
changed.oid |
User oid changed that object (provided for backward compatibility) |
• Field Model DTO
Object attribute | Description |
---|---|
required |
|
minLen |
The minimum length for the field value. 0 for no limit. |
maxLen |
The maximum length for the field value. 0 for no limit. |
regExp |
A regular expression describing the allowed values in the field. |
number |
|
unicode |
|
picklistItems |
Picklist items when field type is Picklist or Multiselect. Object of type Picklist item. |
id |
Field model id. |
oid |
Field model oid. This is object id from old objects. |
• Picklist Item DTO
Object attribute | Description |
---|---|
name |
An item display name specified by user |
tbxName |
A standard TBX name for picklist item. Must be used unless user specified custom in |
sortIndex |
Order number for displaying in user specified order |
fieldOid |
Field oid to which this item is related. |
id |
Picklist item id. |
oid |
Picklist item oid. This is object id from old objects. |
• TBX DataCategory
Object attribute | Description |
---|---|
key |
localizable name key of the data category. Internal use only. |
name |
localizable name key of the data category. |
id |
ISO id for the category, e.g. 08 for ISO12620A-08 |
fieldType |
Type of field. Possible values are: |
picklistItems |
List of possible values for picklists fields. |
levels |
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 | |
---|---|
|
Unexpired authentication token |
Response documentation
Headers | |
---|---|
|
application/json;charset=UTF-8 |
Payload |
|
body |
Array of available TBX data categories of type DataCategory. |
• Copy
POST /api/v4/dictionaries/copy/{id}
Description
This operation creates a new copy of existing dictionary. It may create only structure copy or full copy including data.
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
Path parameters |
|
---|---|
id |
Dictionary id to copy |
Query parameters |
|
---|---|
name |
Dictionary name of copy, can be omitted then server will generate a name automatically. |
copy-data |
Default value is |
Response documentation
Headers | |
---|---|
|
application/json;charset=UTF-8 |
Status |
|
code |
|
Payload attributes |
|
result |
|
jobTaskId |
When operation went to asynchronous execution, this value will have id of running job task. See JobTask. |
• Empty
POST /api/v4/dictionaries/empty/{id}
Description
This operation erases all data (Concepts and Terms) in a dictionary.
This operation may run asynchronous when emptying takes more than 15 seconds. In that case server will return http status code 202 Accepted
.
Request documentation
Path parameters |
|
---|---|
id |
Dictionary id to empty |
Response documentation
Headers | |
---|---|
|
application/json;charset=UTF-8 |
Status |
|
code |
|
Payload attributes |
|
result |
|
jobTaskId |
When operation went to asynchronous execution, this value will have id of running job task. See JobTask. |
• Export definition
POST /api/v4/dictionaries/export-definition/{id}
Description
This operation creates a file containing dictionary definition in specified format.
Request documentation
Path parameters |
|
---|---|
id |
Dictionary id to export |
Query parameters | |
---|---|
include-filters |
Default value is |
format |
<optional>, default is |
Response documentation
Headers | |
---|---|
|
application/xml |
|
attachment; filename="dictioanry_name_as_file_name" |
|
Generated file length |
Status |
|
code |
|
Payload |
|
body |
XML file containing dictionary definition. |
• Import Definition – start
POST /api/v4/dictionaries/import-definition/start
Description
Starts session for importing dictionary definition by uploading new file and validates its contents.
Request documentation
Headers |
|
---|---|
|
multipart/form-data |
Payload fields |
|
file |
Multipart data containing dictionary definition file. |
Response documentation
Headers |
|
---|---|
|
application/json;charset=UTF-8 |
Payload |
|
importId |
Import session id in case of successful file upload and file is valid. This values will be used in subsequent calls |
hasFilters |
Indicator that uploaded file has compatible filter definitions. |
success |
Indicator that uploaded file is valid and user may continue importing it. |
errorMessage |
Error message for displaying to user in case of unsuccessful processing of dictionary definition file. |
• Import definition – process dictionary
PUT /api/v4/dictionaries/import-definition/process-dictionary/
Description
This operation continues import of dictionary definition. It may create a new dictionary from definition or use existing. When processing is launched without including filters or execution is failed import session will be terminated. If filters included, then import session will be still active and user may launch processing of filters.
Request documentation
Query parameters |
|
---|---|
import-id |
Import session id. |
dictionary-id |
Dictionary id or |
include-filters |
|
Response documentation
Headers | |
---|---|
|
application/json;charset=UTF-8 |
Status |
|
code |
|
Payload |
|
importId |
Import session id in case of successful file upload and file is valid. This values will be used in subsequent calls |
success |
Indicator that uploaded file is valid and user may continue importing it. |
dictionaryNew |
Indicator that import job created new dictionary. |
addedFiltersCount |
Number of added new filters. |
skippedFiltersCount |
Number of skipped filters. |
errorMessage |
Error message for displaying to user in case of unsuccessful processing of dictionary definition file. |
• Import definition – process filter
PUT /api/v4/dictionaries/import-definition/process-filter/
Description
This operation continues import of dictionary definition by processing filters stored in dictionary definition file.
When all data is available on server, then method returns ImportDefinitionResult
object.
If something is missing on server (user, group, concept or term field) method returns object + ImportDefinitionValidationFilterResult
containing information about missing data.
Subsequent call of this method with provided full mapping will proceed successfully and ImportDefinitionResult
will be returned with import results and import session will be terminated as well.
In case of incomplete mapping ImportDefinitionValidationFilterResult
will be returned again,
import session remains active.
Request documentation
Query parameters |
|
---|---|
import-id |
Import session id. |
Payload |
|
Payload is |
|
userMapping |
The map of User missing oids and mapped values of existing users. |
groupMapping |
The map of Group missing oids and mapped values of existing users. |
conceptFieldsMapping |
The map of Field missing oids and mapped values of existing users. |
termFieldsMapping |
The map of Field missing oids and mapped values of existing users. |
Response documentation
Headers | |
---|---|
|
application/json;charset=UTF-8 |
Status |
|
code |
|
Payload |
|
importId |
Import session id in case of successful file upload and file is valid. This values will be used in subsequent calls |
success |
Indicator that import is successful. |
dictionaryNew |
Indicator that import job created new dictionary. |
addedFiltersCount |
Number of added new filters. |
skippedFiltersCount |
Number of skipped filters. |
errorMessage |
Error message for displaying to user in case of unsuccessful processing of dictionary definition file. |
Or payload |
|
importId |
Import session id in case of successful file upload and file is valid. This values will be used in subsequent calls |
success |
Indicator that validation is successful. |
errorMessage |
Error message for displaying to user in case of unsuccessful processing of dictionary definition file. |
missingGroups |
Array of missing groups wrapped into interface NamedObject. |
missingUsers |
Array of missing users wrapped into interface NamedObject. |
missingConceptFields |
Array of missing concept fields wrapped into interface NamedObject. |
missingTermFields |
Array of missing term fields wrapped into interface NamedObject. |
existingGroups |
Array of existing groups wrapped into interface NamedObject plus skip option object. |
existingUsers |
Array of existing users wrapped into interface NamedObject plus skip option object. |
existingConceptFields |
Array of existing concept fields wrapped into interface NamedObject plus skip option object. |
existingTermFields |
Array of existing term fields wrapped into interface NamedObject plus skip option object. |
• 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 |
Dictionary id where to apply language replace operation. |
from-id |
Language variant code in custom format: <lang_var>[;[region_code];[script_code]] |
to-id |
Language variant code in custom format: <lang_var>[;[region_code][;script_code]] |
Response documentation
Headers | |
---|---|
|
application/json;charset=UTF-8 |
Status |
|
code |
|
Payload attributes |
|
result |
Number of moved terms. |
jobTaskId |
When operation went to asynchronous transfer, this value will have id of running job task. See JobTask. |
• Reindex
POST /api/v4/dictionaries/reindex/{id}
Description
This operation executes reindexing of terms in a specified dictionary. Reindexing mostly needed to restore visibility
of terms or sort order in case of errors on import phase.
This operation may run asynchronous when emptying takes more than 15 seconds. In that case server will return http status code 202 Accepted
.
Request documentation
Path parameters |
|
---|---|
id |
Dictionary id to reindex |
Response documentation
Headers | |
---|---|
|
application/json;charset=UTF-8 |
Status |
|
code |
|
Payload attributes |
|
result |
|
jobTaskId |
When operation went to asynchronous execution, 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 |
<optional>, default is equal to current client id related to authentication token. |
name |
<optional>, default is |
name-eq |
<optional>, default is |
format |
<optional>, default is |
include-deleted |
<optional>, default is |
size |
<optional>, default is 20 |
page |
<optional>, default is 0 |
sort |
<optional>, default is null |
Response documentation
Headers | |
---|---|
|
application/json;charset=UTF-8 |
Payload |
|
content |
Found dictionaries of type Dictionary. |
last |
indicates if this page is last with current search params |
totalElements |
total amount of objects accessible from this endpoint |
totalPages |
total number of pages available with current page size and total elements |
sort |
current sort params, like |
numberOfElements |
amount of objects returned with this page |
first |
indicates if this page is first with current search params |
size |
current page size |
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 |
Dictionary id to look for |
sort |
<optional>, default is null |
Query parameters |
|
client_id |
<optional>, default is equal to current client id related to authentication token. |
name |
<optional>, default is |
name-eq |
<optional>, default is |
format |
<optional>, default is |
include-deleted |
<optional>, default is |
Response documentation
Headers | |
---|---|
|
application/json;charset=UTF-8 |
Payload |
|
body |
Found row number for specified parameters, in case when nothing found return |
• Get
GET /api/v4/dictionaries/{id}
Description
Looks for dictionary with specified id.
Request documentation
Path parameters |
|
---|---|
id |
Dictionary id to look for |
format |
<optional>, default is |
include-deleted |
<optional>, default is |
Response documentation
Headers |
|
---|---|
|
application/json;charset=UTF-8 |
Payload |
|
body |
JSON object of Dictionary. |
• Create
POST /api/v4/dictionaries/
Description
Creates new dictionary from JSON data sent in payload.
Request documentation
Payload |
|
---|---|
body |
JSON object of type Dictionary. |
format |
<optional>, default is |
Response documentation
Headers | |
---|---|
|
application/json;charset=UTF-8 |
Payload |
|
body |
Created object of dictionary. |
• Update
PUT /api/v4/dictionaries/{id}
Description
Updates existing dictionary from JSON data sent in payload.
Request documentation
Headers |
|
---|---|
|
application/json |
Path parameters |
|
id |
Id of Dictionary which need to be updated |
Payload |
|
body |
JSON object of type Dictionary. Value of |
format |
<optional>, default is |
Response documentation
Headers | |
---|---|
|
application/json;charset=UTF-8 |
Payload |
|
body |
Updated dictionary object. |
• Delete
DELETE /api/v4/dictionaries/{id}
Description
Deletes dictionary with specified id.
Request documentation
Path parameters |
|
---|---|
id |
Dictionary id to delete |
Response documentation
Headers | |
---|---|
|
text/plain;charset=UTF-8 |
Status |
|
code |
|
• Delete async
DELETE /api/v4/dictionaries/async/{id[]}
Description
Deletes dictionaries 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 |
Dictionary ids of dictionaries to delete |
Response documentation
Headers | |
---|---|
|
application/json;charset=UTF-8 |
Status |
|
code |
|
Payload attributes |
|
result |
When operation has completed successfully, this result will contain map with entries where key is |
jobTaskId |
When operation went to asynchronous deletion, this value will have id of running job task. See JobTask. |
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 |
An array of sections ids to clear. |
Response documentation
Headers | |
---|---|
|
application/json;charset=UTF-8 |
Status |
|
code |
|
Payload attributes |
|
result |
When operation has completed successfully, this result will contain map with entries where key is |
jobTaskId |
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 |
<optional>, default is |
client_id |
<optional>, default is equal to current client id related to authentication token. |
name |
<optional>, default is |
name-eq |
<optional>, default is |
format |
<optional>, default is |
include-deleted |
<optional>, default is |
size |
<optional>, default is 20 |
page |
<optional>, default is 0 |
sort |
<optional>, default is null |
Response documentation
Headers | |
---|---|
|
application/json;charset=UTF-8 |
Payload |
|
content |
Found sections of type Section. |
last |
indicates if this page is last with current search params |
totalElements |
total amount of objects accessible from this endpoint |
totalPages |
total number of pages available with current page size and total elements |
sort |
current sort params, like |
numberOfElements |
amount of objects returned with this page |
first |
indicates if this page is first with current search params |
size |
current page size |
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 |
Section id to look for |
sort |
<optional>, default is null |
Query parameters |
|
dictionary_id |
<optional>, default is |
client_id |
<optional>, default is equal to current client id related to authentication token. |
name |
<optional>, default is |
name-eq |
<optional>, default is |
format |
<optional>, default is |
include-deleted |
<optional>, default is |
Response documentation
Headers | |
---|---|
|
application/json;charset=UTF-8 |
Payload |
|
body |
Found row number for specified parameters, in case when nothing found return |
• Get
GET /api/v4/sections/{id}
Description
Looks for section with specified id.
Request documentation
Path parameters |
|
---|---|
id |
Section id to look for |
format |
<optional>, default is |
include-deleted |
<optional>, default is |
Response documentation
Headers |
|
---|---|
|
application/json;charset=UTF-8 |
Payload |
|
body |
JSON object of Section. |
• Create
POST /api/v4/sections/
Description
Creates new section from JSON data sent in payload.
Request documentation
Payload |
|
---|---|
body |
JSON object of type Section. |
format |
<optional>, default is |
Response documentation
Headers | |
---|---|
|
application/json;charset=UTF-8 |
Payload |
|
body |
Created object of section. |
• Update
PUT /api/v4/sections/{id}
Description
Updates existing section from JSON data sent in payload.
Request documentation
Headers |
|
---|---|
|
application/json |
Path parameters |
|
id |
Id of Section which need to be updated |
Payload |
|
body |
JSON object of type Section. Value of |
format |
<optional>, default is |
Response documentation
Headers | |
---|---|
|
application/json;charset=UTF-8 |
Payload |
|
body |
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 PUT /api/v4/sections/{id}
, 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 |
Id of Section which need to be updated |
Payload |
|
body |
JSON object of type Section. Value of |
format |
<optional>, default is |
Response documentation
Headers | |
---|---|
|
application/json;charset=UTF-8 |
Payload |
|
body |
Patched section object. |
• Delete
DELETE /api/v4/sections/{id}
Description
Deletes section with specified id.
Request documentation
Path parameters |
|
---|---|
id |
Section id to delete |
Response documentation
Headers | |
---|---|
|
text/plain;charset=UTF-8 |
Status |
|
code |
|
• 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 |
Section ids of sections to delete |
Response documentation
Headers | |
---|---|
|
application/json;charset=UTF-8 |
Status |
|
code |
|
Payload attributes |
|
result |
When operation has completed successfully, this result will contain map with entries where key is |
jobTaskId |
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 |
Field old object oid of field of type "incremental" |
Response documentation
Headers | |
---|---|
|
application/json;charset=UTF-8 |
Payload |
|
body |
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 |
Field old object oid of field of type "incremental" |
value |
value to check |
type |
One of the field levels: |
entry-id |
<optional>, Concept or Term id to exclude from validation results. |
Response documentation
Headers | |
---|---|
|
application/json;charset=UTF-8 |
Payload |
|
body |
|
• Generate picklist from text values
GET /api/v4/fields/generate-picklist/{field-oid}
Description
Returns next available value for fields of type "incremental"
Request documentation
Path parameters | |
---|---|
field-oid |
Field old object oid of field of type "incremental" |
Query parameters | |
---|---|
multivalued |
<optional>, default is |
Response documentation
Headers | |
---|---|
|
application/json;charset=UTF-8 |
Payload |
|
body |
Picklist items generated from text values of specified field. An array of objects of type Picklist item. |
13.5.4. Domains endpoint
Description
Domains for Dictionary. Domains linked together in hierarchical structure.
• Domain DTO
Object attribute | Description |
---|---|
name |
Domain name. |
description |
Domain description. |
dictionaryId |
Dictionary id in which that language has been created. |
parentDomainId |
Domain id which is parent of this domain. |
numberOfConcepts |
Number of concepts created in this section |
children |
List of children Domain ids. |
clientId |
Client id to which object belongs |
id |
Domain id. |
oid |
Domain oid. This is object id from old objects. |
deleted |
|
created |
Metadata object containing information about creation |
created.id |
User id created that object |
created.name |
User login created that object |
created.fullName |
User full name created that object |
created.time |
Created date and time in milliseconds since Unix Epoch |
created.oid |
User oid created that object (provided for backward compatibility) |
changed |
Metadata object containing information about last modification |
changed.id |
User id changed that object |
changed.name |
User login changed that object |
changed.fullName |
User full name changed that object |
changed.time |
Last change date and time in milliseconds since Unix Epoch |
changed.oid |
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 |
required, provide a dictionary id to get list of domains for it. |
name |
<optional>, default is |
name-eq |
<optional>, default is |
format |
<optional>, default is |
include-deleted |
<optional>, default is |
size |
<optional>, default is 20 |
page |
<optional>, default is 0 |
sort |
<optional>, default is null |
Response documentation
Headers | |
---|---|
|
application/json;charset=UTF-8 |
Payload |
|
content |
Found domain of type Domain. |
last |
indicates if this page is last with current search params |
totalElements |
total amount of objects accessible from this endpoint |
totalPages |
total number of pages available with current page size and total elements |
sort |
current sort params, like |
numberOfElements |
amount of objects returned with this page |
first |
indicates if this page is first with current search params |
size |
current page size |
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 |
Domain id to look for |
sort |
<optional>, default is null |
Query parameters |
|
dictionary_id |
required, provide a dictionary id to get list of domains for it. |
name |
<optional>, default is |
name-eq |
<optional>, default is |
format |
<optional>, default is |
include-deleted |
<optional>, default is |
Response documentation
Headers | |
---|---|
|
application/json;charset=UTF-8 |
Payload |
|
body |
Found row number for specified parameters, in case when nothing found return |
• Get
GET /api/v4/domains/{id}
Description
Looks for domain with specified id.
Request documentation
Path parameters |
|
---|---|
id |
Domain id to look for |
format |
<optional>, default is |
include-deleted |
<optional>, default is |
Response documentation
Headers |
|
---|---|
|
application/json;charset=UTF-8 |
Payload |
|
body |
JSON object of Domain. |
• Create
POST /api/v4/domains/
Description
Creates new domain from JSON data sent in payload.
Request documentation
Payload |
|
---|---|
body |
JSON object of type Domain. |
format |
<optional>, default is |
Response documentation
Headers | |
---|---|
|
application/json;charset=UTF-8 |
Payload |
|
body |
Created object of domain. |
• Update
PUT /api/v4/domains/{id}
Description
Updates existing domain from JSON data sent in payload.
Request documentation
Headers |
|
---|---|
|
application/json |
Path parameters |
|
id |
Id of Domain which need to be updated |
Payload |
|
body |
JSON object of type Domain. Value of |
format |
<optional>, default is |
Response documentation
Headers | |
---|---|
|
application/json;charset=UTF-8 |
Payload |
|
body |
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 PUT /api/v4/domains/{id}
, 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 |
Id of Domain which need to be updated |
Payload |
|
body |
JSON object of type Domain. Value of |
format |
<optional>, default is |
Response documentation
Headers | |
---|---|
|
application/json;charset=UTF-8 |
Payload |
|
body |
Patched domain object. |
• Delete
DELETE /api/v4/domains/{id}
Description
Deletes domain with specified id.
Request documentation
Path parameters |
|
---|---|
id |
Domain id to delete |
Response documentation
Headers | |
---|---|
|
text/plain;charset=UTF-8 |
Status |
|
code |
|
• 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 |
Domain ids of domain to delete |
Response documentation
Headers | |
---|---|
|
application/json;charset=UTF-8 |
Status |
|
code |
|
Payload attributes |
|
result |
When operation has completed successfully, this result will contain map with entries where key is |
jobTaskId |
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 |
Filter name. |
groupId |
Group id to which this Filter available to use. Used for "Visibility" field in UI. |
filteringTerms |
|
criterias |
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. |
indexed |
|
type |
Filter type. Possible values are: |
canEdit |
|
cantDelete |
|
cantDeleteReason |
Message containing information why this filter can’t be deleted. |
dictionaryId |
Dictionary id to which filter related. |
clientId |
Client id to which object belongs |
id |
Filter id. |
oid |
Filter oid. This is object id from old objects. |
created |
Metadata object containing information about creation |
created.id |
User id created that object |
created.name |
User login created that object |
created.fullName |
User full name created that object |
created.time |
Created date and time in milliseconds since Unix Epoch |
created.oid |
User oid created that object (provided for backward compatibility) |
changed |
Metadata object containing information about last modification |
changed.id |
User id changed that object |
changed.name |
User login changed that object |
changed.fullName |
User full name changed that object |
changed.time |
Last change date and time in milliseconds since Unix Epoch |
changed.oid |
User oid changed that object (provided for backward compatibility) |
• Filter criterion DTO
Object attribute | Description |
---|---|
filterId |
Filter id to which this criterion belongs. |
fieldOid |
Field old object oid from dictionary to which this Filter belongs to. |
conceptField |
|
operation |
Comparison operation for this field, can have this values:
|
value |
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:
|
boolOperator |
Number enum which indicates how current criterion linked with next criterion in array. |
type |
Filter type. Possible values are: |
sortIndex |
Order number where this criterion must be in an array of filter criteria. |
relDate |
|
included |
Used in combination with fieldOid equal to 'TERM_CRI_START' otherwise will be |
id |
Filter criterion id. |
oid |
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 |
Filter id. |
Response documentation
Headers | |
---|---|
|
application/json;charset=UTF-8 |
Status |
|
code |
|
• Find
GET /api/v4/filters/
Description
Finds filters with specified query parameters available to current user.
Request documentation
Query parameters |
|
---|---|
dictionary_id |
<optional>, default is |
client_id |
<optional>, default is equal to current client id related to authentication token. |
name |
<optional>, default is |
name-eq |
<optional>, default is |
format |
<optional>, default is |
include-deleted |
<optional>, default is |
size |
<optional>, default is 20 |
page |
<optional>, default is 0 |
sort |
<optional>, default is null |
Response documentation
Headers | |
---|---|
|
application/json;charset=UTF-8 |
Payload |
|
content |
Found filters of type Filter. |
last |
indicates if this page is last with current search params |
totalElements |
total amount of objects accessible from this endpoint |
totalPages |
total number of pages available with current page size and total elements |
sort |
current sort params, like |
numberOfElements |
amount of objects returned with this page |
first |
indicates if this page is first with current search params |
size |
current page size |
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 |
Filter criterion id to look for |
sort |
<optional>, default is null |
Query parameters |
|
dictionary_id |
<optional>, default is |
client_id |
<optional>, default is equal to current client id related to authentication token. |
name |
<optional>, default is |
name-eq |
<optional>, default is |
format |
<optional>, default is |
include-deleted |
<optional>, default is |
Response documentation
Headers | |
---|---|
|
application/json;charset=UTF-8 |
Payload |
|
body |
Found row number for specified parameters, in case when nothing found return |
• Get
GET /api/v4/filters/{id}
Description
Looks for filter criterion with specified id.
Request documentation
Path parameters |
|
---|---|
id |
Filter criterion id to look for |
format |
<optional>, default is |
include-deleted |
<optional>, default is |
Response documentation
Headers |
|
---|---|
|
application/json;charset=UTF-8 |
Payload |
|
body |
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 |
JSON object of type Filter. |
format |
<optional>, default is |
Response documentation
Headers | |
---|---|
|
application/json;charset=UTF-8 |
Payload |
|
body |
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 |
|
---|---|
|
application/json |
Path parameters |
|
id |
Id of Filter criterion which need to be updated |
Payload |
|
body |
JSON object of type Filter. Value of |
format |
<optional>, default is |
Response documentation
Headers | |
---|---|
|
application/json;charset=UTF-8 |
Payload |
|
body |
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 PUT /api/v4/filters/{id}
, 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 |
Id of Filter criterion which need to be updated |
Payload |
|
body |
JSON object of type Filter. Value of |
format |
<optional>, default is |
Response documentation
Headers | |
---|---|
|
application/json;charset=UTF-8 |
Payload |
|
body |
Patched filter criterion object. |
• Delete
DELETE /api/v4/filters/{id}
Description
Deletes filter criterion with specified id.
Request documentation
Path parameters |
|
---|---|
id |
Filter criterion id to delete |
Response documentation
Headers | |
---|---|
|
text/plain;charset=UTF-8 |
Status |
|
code |
|
• 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 |
Filter criterion ids of filters to delete |
Response documentation
Headers | |
---|---|
|
application/json;charset=UTF-8 |
Status |
|
code |
|
Payload attributes |
|
result |
When operation has completed successfully, this result will contain map with entries where key is |
jobTaskId |
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 |
View name. |
fields |
Field oids included in this view. |
inUse |
|
inUseMessage |
Message with a description of which views or groups are using that view. |
dictionaryId |
Dictionary id to which view related. |
clientId |
Client id to which object belongs |
id |
View id. |
oid |
View oid. This is object id from old objects. |
deleted |
|
created |
Metadata object containing information about creation |
created.id |
User id created that object |
created.name |
User login created that object |
created.fullName |
User full name created that object |
created.time |
Created date and time in milliseconds since Unix Epoch |
created.oid |
User oid created that object (provided for backward compatibility) |
changed |
Metadata object containing information about last modification |
changed.id |
User id changed that object |
changed.name |
User login changed that object |
changed.fullName |
User full name changed that object |
changed.time |
Last change date and time in milliseconds since Unix Epoch |
changed.oid |
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 |
<optional>, default is |
client_id |
<optional>, default is equal to current client id related to authentication token. |
name |
<optional>, default is |
name-eq |
<optional>, default is |
format |
<optional>, default is |
include-deleted |
<optional>, default is |
size |
<optional>, default is 20 |
page |
<optional>, default is 0 |
sort |
<optional>, default is null |
Response documentation
Headers | |
---|---|
|
application/json;charset=UTF-8 |
Payload |
|
content |
Found views of type View. |
last |
indicates if this page is last with current search params |
totalElements |
total amount of objects accessible from this endpoint |
totalPages |
total number of pages available with current page size and total elements |
sort |
current sort params, like |
numberOfElements |
amount of objects returned with this page |
first |
indicates if this page is first with current search params |
size |
current page size |
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 |
View id to look for |
sort |
<optional>, default is null |
Query parameters |
|
dictionary_id |
<optional>, default is |
client_id |
<optional>, default is equal to current client id related to authentication token. |
name |
<optional>, default is |
name-eq |
<optional>, default is |
format |
<optional>, default is |
include-deleted |
<optional>, default is |
Response documentation
Headers | |
---|---|
|
application/json;charset=UTF-8 |
Payload |
|
body |
Found row number for specified parameters, in case when nothing found return |
• Get
GET /api/v4/views/{id}
Description
Looks for view with specified id.
Request documentation
Path parameters |
|
---|---|
id |
View id to look for |
format |
<optional>, default is |
include-deleted |
<optional>, default is |
Response documentation
Headers |
|
---|---|
|
application/json;charset=UTF-8 |
Payload |
|
body |
JSON object of View. |
• Create
POST /api/v4/views/
Description
Creates new view from JSON data sent in payload.
Request documentation
Payload |
|
---|---|
body |
JSON object of type View. |
format |
<optional>, default is |
Response documentation
Headers | |
---|---|
|
application/json;charset=UTF-8 |
Payload |
|
body |
Created object of view. |
• Update
PUT /api/v4/views/{id}
Description
Updates existing view from JSON data sent in payload.
Request documentation
Headers |
|
---|---|
|
application/json |
Path parameters |
|
id |
Id of View which need to be updated |
Payload |
|
body |
JSON object of type View. Value of |
format |
<optional>, default is |
Response documentation
Headers | |
---|---|
|
application/json;charset=UTF-8 |
Payload |
|
body |
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 PUT /api/v4/views/{id}
, 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 |
Id of View which need to be updated |
Payload |
|
body |
JSON object of type View. Value of |
format |
<optional>, default is |
Response documentation
Headers | |
---|---|
|
application/json;charset=UTF-8 |
Payload |
|
body |
Patched view object. |
• Delete
DELETE /api/v4/views/{id}
Description
Deletes view with specified id.
Request documentation
Path parameters |
|
---|---|
id |
View id to delete |
Response documentation
Headers | |
---|---|
|
text/plain;charset=UTF-8 |
Status |
|
code |
|
• 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 |
View ids of views to delete |
Response documentation
Headers | |
---|---|
|
application/json;charset=UTF-8 |
Status |
|
code |
|
Payload attributes |
|
result |
When operation has completed successfully, this result will contain map with entries where key is |
jobTaskId |
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 |
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 |
Section old object oid to which this Concept belongs to. |
domainList |
Domain old object oids to which this Concept related. |
terms |
An array of terms related to this Concept. |
conceptRelations |
An array of Concept relation link objects. |
languageCodesEditable |
A list of language codes which can be edited by current user. Language code is ISO639-2 three-letter lowercase code. |
permissions |
A map of Concept permissions for current user. When user has permission to perform some operation, map will have value |
fieldMap |
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. |
refLinks |
List of RefLinks created for current concept. |
comments |
List of last comments created for this concept. |
dictionaryId |
Dictionary id to which concept related. |
clientId |
Client id to which object belongs |
id |
Concept id. |
oid |
Concept oid. This is object id from old objects. |
deleted |
|
created |
Metadata object containing information about creation |
created.id |
User id created that object |
created.name |
User login created that object |
created.fullName |
User full name created that object |
created.time |
Created date and time in milliseconds since Unix Epoch |
created.oid |
User oid created that object (provided for backward compatibility) |
changed |
Metadata object containing information about last modification |
changed.id |
User id changed that object |
changed.name |
User login changed that object |
changed.fullName |
User full name changed that object |
changed.time |
Last change date and time in milliseconds since Unix Epoch |
changed.oid |
User oid changed that object (provided for backward compatibility) |
• Concept permissions enum
Value | Description |
---|---|
CONCEPT_EDIT_FIELDS |
The user can edit concept level fields. |
CONCEPT_UPDATE |
The user can edit a concept or restore changes in history. |
CONCEPT_DELETE |
The user can delete a concept. |
CONCEPT_PRINT |
The user may print a concept. |
CONCEPT_VIEW_HISTORY |
The user can see change history for concepts. |
RESTORE_STATE |
The user can restore to state in concept history. |
TERM_CREATE |
The user is allowed to create new terms and restore deleted terms from history. |
• Concept Relation DTO
Object attribute | Description |
---|---|
dictionaryId |
Dictionary id in which that relation has been created. |
sourceConceptId |
Source Concept id of this relation. |
targetConceptId |
Target Concept id of this relation. |
type |
Concept relation type, value is numeric. Possible values are:
'GENERIC' - |
attribute |
Concept relation attribute, depends on value of type attribute. Possible values are:
'GENERIC_SUPERORDINATE' - |
text |
Relation specification text. |
relationId |
Serial number for this relation. Unique per Dictionary. Assigned by the server on creation. |
id |
Concept relation id. |
oid |
Concept relation oid. This is object id from old objects. |
• RefLink DTO
Object attribute | Description |
---|---|
sourceConceptId |
Concept id to which this cross-reference belongs. |
sourceTermId |
Term id to which this cross-reference belongs, will be |
sourceFieldOid |
Field oid where this cross-reference must be rendered. |
type |
Cross-reference type defines what it contains. Possible values are: |
text |
Original reference text. |
dynamicText |
In case of |
position |
At which position in the text the link starts. If the text contains line breaks these are considered to be encoded as CR LF (\r\n), so every line break adds two characters to the position of links in following text rows. |
url |
|
In case of |
conceptId |
Concept id to which {txt-object} points in case of internal cross-reference. |
termId |
Term id to which {txt-object} points in case of |
languageCode |
Language code3 to {txt-object} points in case of |
dictionaryId |
Dictionary id to which {txt-object} related. |
invalid |
|
id |
{txt-object-c} id. |
oid |
• Get by id
GET /api/v4/concepts/{id}
Description
Looks for concept with specified id.
Request documentation
Path parameters |
|
---|---|
id |
Concept id to look for |
Query parameters |
|
format |
<optional>, default is |
Response documentation
Headers |
|
---|---|
|
application/json;charset=UTF-8 |
Payload |
|
body |
JSON object of Concept. |
• Get by [oid, term-oid, term-id]
GET /api/v4/concepts/
Description
Looks for concept with by one of the specified parameters. At lease of one the parameters must be present. Server will process only one parameter at a time.
Request documentation
Path parameters |
|
---|---|
oid |
<optional> Concept oid to look for |
term-oid |
<optional> Term oid to look for |
term-id |
<optional> An array of Term id to look for |
Query parameters |
|
format |
<optional>, default is |
Response documentation
Headers |
|
---|---|
|
application/json;charset=UTF-8 |
Payload |
|
body |
JSON object of Concept. Or an array of Concept in case of multiple values in term-id parameter. |
• Create
POST /api/v4/concepts/
Description
Creates new concept from JSON data sent in payload.
Request documentation
Payload |
|
---|---|
body |
JSON object of type Concept. |
format |
<optional>, default is |
Response documentation
Headers | |
---|---|
|
application/json;charset=UTF-8 |
Payload |
|
body |
Created object of concept. |
• Update
PUT /api/v4/concepts/{id}
Description
Updates existing concept from JSON data sent in payload.
Request documentation
Headers |
|
---|---|
|
application/json |
Path parameters |
|
id |
Id of Concept which need to be updated |
Payload |
|
body |
JSON object of type Concept. Value of |
format |
<optional>, default is |
Response documentation
Headers | |
---|---|
|
application/json;charset=UTF-8 |
Payload |
|
body |
Updated concept object. |
• Partial update
PUT /api/v4/concepts/{id}/patch
Description
It updates only specified parts of concept from JSON data sent in payload. Unlike method PUT /api/v4/concepts/{id}
, patch will only update values of object which are present in JSON without modifying other fields which are not present in JSON. For example when Concept have terms
property with actual values in array, server will update it, when term
equal to null
none of terms will be updated.
Request documentation
Path parameters |
|
---|---|
id |
Id of Concept which need to be patched |
Payload |
|
body |
JSON object of type Concept. Value of |
format |
<optional>, default is |
Response documentation
Headers | |
---|---|
|
application/json;charset=UTF-8 |
Payload |
|
body |
Patched concept object. |
• Delete
DELETE /api/v4/concepts/{id}
Description
Deletes concept with specified id.
Request documentation
Path parameters |
|
---|---|
id |
Concept id to delete |
Response documentation
Headers | |
---|---|
|
text/plain;charset=UTF-8 |
Status |
|
code |
|
• Acquire lock
PUT /api/v4/concepts/{id}/acquire-lock
Description
Locks concept from future edits by other users.
Request documentation
Headers |
|
---|---|
|
application/json |
Path parameters |
|
id |
Id of Concept which need to be locked |
Payload |
|
body |
Must be empty. |
Response documentation
Headers | |
---|---|
|
application/json;charset=UTF-8 |
Payload |
|
body |
|
• Release lock
PUT /api/v4/concepts/{id}/release-lock
Description
Unlocks Concept and allow future edits by other users.
Request documentation
Headers |
|
---|---|
|
application/json |
Path parameters |
|
id |
Id of Concept which need to be unlocked |
Payload |
|
body |
Must be empty. |
Response documentation
Headers | |
---|---|
|
application/json;charset=UTF-8 |
Payload |
|
body |
|
• Print as HTML
GET /api/v4/concepts/{id}/print-as-html
Description
Generates html preview of concept for specified id.
Request documentation
Path parameters |
|
---|---|
id |
Id of Concept which need to be printed |
Response documentation
Headers | |
---|---|
|
application/json;charset=UTF-8 |
Payload |
|
body |
Body containing HTML text. |
• Permissions
GET /api/v4/concepts/{id}/permissions
Description
Looks for current user concept permissions with specified id for specific Dictionary section.
Request documentation
Path parameters |
|
---|---|
id |
Concept id to look for |
Query parameters |
|
section-oid |
Section old object oid. |
Response documentation
Headers |
|
---|---|
|
application/json;charset=UTF-8 |
Payload |
|
body |
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 |
Term itself. |
tid |
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. |
conceptId |
Concept id to which this term belongs. |
conceptOid |
Concept old object oid to which this term belongs. |
languageCode |
Language code. Should be ISO639-2 3-char lower case code. |
regionCode |
Geographical Language Variant code for this term if set. |
scriptCode |
Orthographical Language Variant code for this term if set. |
permissions |
A map of Term permissions for current user. When user has permission to perform some operation, map will have value |
fieldMap |
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. |
refLinks |
List of RefLinks created for current term. |
comments |
List of last comments created for this term. |
dictionaryId |
Dictionary id to which term related. |
clientId |
Client id to which object belongs |
id |
Term id. |
oid |
Term oid. This is object id from old objects. |
deleted |
|
created |
Metadata object containing information about creation |
created.id |
User id created that object |
created.name |
User login created that object |
created.fullName |
User full name created that object |
created.time |
Created date and time in milliseconds since Unix Epoch |
created.oid |
User oid created that object (provided for backward compatibility) |
changed |
Metadata object containing information about last modification |
changed.id |
User id changed that object |
changed.name |
User login changed that object |
changed.fullName |
User full name changed that object |
changed.time |
Last change date and time in milliseconds since Unix Epoch |
changed.oid |
User oid changed that object (provided for backward compatibility) |
• Term permissions enum
Value | Description |
---|---|
TERM_UPDATE |
The user can edit a term or restore changes in history. |
TERM_DELETE |
The user can delete a term. |
• Search
POST /api/v4/terms/search
Description
Searches for terms form specified dictionaries.
Request documentation
Payload fields |
|
---|---|
dictionaryIds |
required, An array of Dictionary ids. Typically used to search from one dictionary, but more than one can be specified. |
langCode |
required, Should be ISO639-2 three-letter lower case code. |
regionCode |
<optional>, Geographical Language Variant code for this term if set. |
scriptCode |
<optional>, Orthographical Language Variant code for this term if set. |
filterId |
<optional>, Filter id to use with search. |
sectionOids |
required, List of Section old object oids to include in search. |
domainOids |
<optional>, To filter by domains provide a list of Domain old object oids. |
quickFilter |
<optional>, temporary filter to quickly apply it to search results without creating normal filter. Object of type Filter. |
name |
<optional>, Term name to search, or text to search in case of multi field search. |
pageSize |
<optional>, Amount of entries to return. |
termOid |
<optional>, Term oid. When provided search will look for that Term with terms around it. |
searchAfter |
<optional>, internal value with index from which continue next search call to load next page of search results. Can be obtained from TermSearchResponse. |
reverse |
|
bidirectional |
Can be used only with combination of termOid attribute. |
searchOptions.normalized |
|
searchOptions.fuzzy |
|
searchOptions.multiEnabled |
|
searchOptions.multiAllFields |
|
searchOptions.fields |
A collection of selected Field oids for multi-field search. FieldLevel is enum with values: |
Response documentation
Headers | |
---|---|
|
application/json;charset=UTF-8 |
Payload |
|
body |
Search results object of type TermSearchResponse. |
• TermSearchResponse
Object attribute | Description |
---|---|
total |
Total number of terms available with current search params. Can be unknown in case of complicated search params, result then will be |
pageSize |
Page size of search results. |
searchAfter |
Internal value with index from which continue next forward search call. |
searchBefore |
Internal value with index from which continue next backward search call. |
results |
Found entries for current search results of type TermListEntry. |
message |
Server message containing warning or error description. |
• TermListEntry
Object attribute | Description |
---|---|
id |
Term id. |
name |
Term name. |
dictionaryId |
Dictionary id to which Term related. |
termId |
Term tid value. |
conceptId |
Concept id. |
conceptOid |
Concept oid. |
langCode |
ISO639-2 three-letter lower case language code |
filterId |
Filter id matched this term. Deprecated. |
style |
Value for HTML attribute style. May contain results of conditional formatting from Workflow. |
disabled |
Term is read-only when value is |
hidden |
• Get by terms ids
GET /api/v4/terms/duplicates
Description
Looks for Terms duplicates.
Request documentation
Query parameters | |
---|---|
term |
Term name to check for duplicates |
dictionary-id |
Dictionary where to look for duplicate terms. |
lang-code |
ISO639-2 three-letter lower case language code. |
concept-id |
<optional>, Concept id which must be excluded from search results. |
region-code |
<optional>, geographical Language Variant code to look for. |
script-code |
<optional>, orthographical Language Variant code to look for. |
Response documentation
Headers |
|
---|---|
|
application/json;charset=UTF-8 |
Payload |
|
body |
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 |
Section id to which concept belongs. |
requestedByUserId |
User id which requested this concept. |
classificationFields |
List of concept classification fields of type Display field. This list can have fewer fields than original entry. |
languageCodes |
Language codes of terms which are present in concept. Codes are ordered according to Language sortIndex. |
termsPerLanguage |
Terms of type Display term grouped by language code assigned on same position in languageCodes attributes. |
termSelected |
|
concept |
Original object of type Concept. |
id |
Display concept id. |
dictionary_id |
Dictionary id to which display concept related. |
metadataFields |
List of display concept metadata fields of type Display field. This list can have fewer fields than original entry. |
fields |
List of display concept fields of type Display field. This list can have fewer fields than original entry. |
• Display Term DTO
Object attribute | Description |
---|---|
langCode |
Language code for a term. In case of custom language will have full language tag. |
region |
In case of standard language can have code of geographical variant (usually country code.) |
script |
In case of standard language can have code of orthographical variant (usually script code. |
elementId |
Element id for a term consisting of prefix |
termField |
Display field for term name. |
id |
Display concept id. |
dictionary_id |
Dictionary id to which display concept related. |
metadataFields |
List of display concept metadata fields of type Display field. This list can have fewer fields than original entry. |
fields |
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 |
Field old object oid. |
label |
English name of Field. |
value |
Processed and prepared for display value of field from entry. |
valueOid |
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 |
CSS class name for an element displaying that field. |
cssStyle |
CSS style for an element displaying that field. |
readOnly |
|
hidden |
|
• Get
GET /api/v4/display-concepts/{id}
Description
Looks for display concept with specified id.
Request documentation
Path parameters |
|
---|---|
id |
<optional> id of Concept to look for. |
Query parameters |
|
term-id |
Term id to look for. |
load-concept |
<optional>, default value |
with-comments |
<optional>, default value |
Response documentation
Headers |
|
---|---|
|
application/json;charset=UTF-8 |
Payload |
|
body |
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 |
Dictionary id where to create new concept. |
Response documentation
Headers | |
---|---|
|
application/json;charset=UTF-8 |
Payload |
|
body |
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 |
Concept id which need to process. |
Query parameters |
|
term-id |
Term id - selected term. |
Response documentation
Headers | |
---|---|
|
application/json;charset=UTF-8 |
Payload |
|
body |
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 |
id of Concept to copy. |
Response documentation
Headers | |
---|---|
|
application/json;charset=UTF-8 |
Payload |
|
body |
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 |
id of Concept where to create new term. |
Response documentation
Headers | |
---|---|
|
application/json;charset=UTF-8 |
Payload |
|
body |
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 |
id of Concept where to create new term. |
Response documentation
Headers | |
---|---|
|
application/json;charset=UTF-8 |
Payload |
|
body |
Created copy of term. |
13.6.4. Comments endpoint
Description
Simplified version of comments.
• Comment DTO
Object attribute | Description |
---|---|
text |
Comment text. |
authorName |
Full name of comment author. |
userId |
User id of comment author. |
dictionaryId |
Dictionary id to which comment related. |
fieldLevel |
Field level enum which helps to determine type of entry. Possible values are: |
entryId |
|
date |
Creation date and time of comment in milliseconds since Unix Epoch until license is valid. |
id |
Comment id. |
oid |
Comment oid. This is object id from old objects. |
• Find
GET /api/v4/comments/
Description
Finds comments with specified entry id.
Request documentation
Query parameters |
|
---|---|
entry-id |
Response documentation
Headers | |
---|---|
|
application/json;charset=UTF-8 |
Payload |
|
body |
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 |
|
Payload |
|
body |
JSON object of type Comment containing only filled "text" attribute. |
Response documentation
Headers | |
---|---|
|
application/json;charset=UTF-8 |
Payload |
|
body |
Created object of comment. |
• Delete
DELETE /api/v4/comments/{id}
Description
Deletes comment with specified id.
Request documentation
Path parameters |
|
---|---|
id |
Comment id to delete |
Response documentation
Headers | |
---|---|
|
text/plain;charset=UTF-8 |
Status |
|
code |
|
13.6.5. History items endpoint
Description
• History Item DTO
Object attribute | Description |
---|---|
id |
history item id. |
oid |
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 |
Concept id where to look for history items. |
Response documentation
Headers | |
---|---|
|
application/json;charset=UTF-8 |
Payload |
|
content |
Found history items of type History item. |
last |
indicates if this page is last with current search params |
totalElements |
total amount of objects accessible from this endpoint |
totalPages |
total number of pages available with current page size and total elements |
sort |
current sort params, like |
numberOfElements |
amount of objects returned with this page |
first |
indicates if this page is first with current search params |
size |
current page size |
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 |
Dictionary id where to look for history items. |
Response documentation
Headers | |
---|---|
|
application/json;charset=UTF-8 |
Payload |
|
content |
Found history items of type History item. |
last |
indicates if this page is last with current search params |
totalElements |
total amount of objects accessible from this endpoint |
totalPages |
total number of pages available with current page size and total elements |
sort |
current sort params, like |
numberOfElements |
amount of objects returned with this page |
first |
indicates if this page is first with current search params |
size |
current page size |
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 |
History item id to which we need to restore concept state. |
Response documentation
Headers |
|
---|---|
|
application/json;charset=UTF-8 |
Payload |
|
body |
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 |
History item id to which we need to restore dictionary state. |
Response documentation
Headers |
|
---|---|
|
application/json;charset=UTF-8 |
Status |
|
code |
|
Payload attributes |
|
result |
|
jobTaskId |
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 |
Current user object of type User. |
• Get initial data
GET /api/v4/data
Request documentation
Headers | |
---|---|
|
Unexpired authentication token |
Response documentation
Headers | |
---|---|
|
application/json;charset=UTF-8 |
Payload |
|
body |
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 |
URL for opening current Menu item. |
parentHref |
URL of parent Menu item containing current item. |
title |
Descriptive text to put it into html title attribute. |
label |
Short text used for showing as menu item text. |
icon |
CSS classes to use as icon. Normally Fontawesome. |
v4 |
|
disabled |
|
old |
Menu item object pointing to previous implementation from TermWeb 3 in case when it exists. Otherwise, this attribute won’t be present. |
• Get Top menu
GET /api/v4/ui/menu/top
Returns top menu items for Administration View.
Request documentation
Headers | |
---|---|
|
Unexpired authentication token |
Response documentation
Headers | |
---|---|
|
application/json;charset=UTF-8 |
Payload |
|
body |
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 |
Top menu item serial number from returned an array of items. |
Response documentation
Headers | |
---|---|
|
application/json;charset=UTF-8 |
Payload |
|
body |
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 |
• Get profile
GET /api/v4/profile/
Returns profile data for current user.
Request documentation
Headers | |
---|---|
|
Unexpired authentication token |
Response documentation
Headers | |
---|---|
|
application/json;charset=UTF-8 |
Payload |
|
body |
JSON object of Profile. |
• Update profile
PUT /api/v4/profile/
Request documentation
Headers | |
---|---|
|
application/json;charset=UTF-8 |
Payload |
|
body |
User data of type Profile to update. |
Response documentation
Headers | |
---|---|
|
application/json;charset=UTF-8 |
Payload |
|
body |
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 | |
---|---|
|
application/json;charset=UTF-8 |
Payload |
|
body |
User data of type Profile containing new password. |
Response documentation
Headers | |
---|---|
|
application/json;charset=UTF-8 |
Payload |
|
body |
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 |
TBD |
• Get user settings
GET /api/v4/user-search-settings/
Returns user search settings for requested user
Request documentation
Query parameters | |
---|---|
user-id |
User id |
Response documentation
Headers | |
---|---|
|
application/json;charset=UTF-8 |
Payload |
|
body |
JSON object of Search settings. |
• Update user settings
PUT /api/v4/user-search-settings/
Request documentation
Headers | |
---|---|
|
application/json;charset=UTF-8 |
Payload |
|
body |
Data of type Search settings to save. |
Response documentation
Headers | |
---|---|
|
application/json;charset=UTF-8 |
Payload |
|
body |
Updated data of type Profile. |
• Update single search setting
PUT /api/v4/profile/password
Updates only one setting.
Request documentation
Query parameters | |
---|---|
user-id |
User id of which setting to update |
setting |
One of the names of attribute of type Search settings. |
Payload |
|
body |
An array of string values |
Response documentation
Headers | |
---|---|
|
application/json;charset=UTF-8 |
Payload |
|
body |
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 |
Area name. |
dictionaryId |
Dictionary id to which staging area related. |
clientId |
Client id to which object belongs |
id |
Staging area id. |
version |
Staging area version number. Represents latest modification counter. |
deleted |
|
created |
Metadata object containing information about creation |
created.id |
User id created that object |
created.name |
User login created that object |
created.fullName |
User full name created that object |
created.time |
Created date and time in milliseconds since Unix Epoch |
created.oid |
User oid created that object (provided for backward compatibility) |
changed |
Metadata object containing information about last modification |
changed.id |
User id changed that object |
changed.name |
User login changed that object |
changed.fullName |
User full name changed that object |
changed.time |
Last change date and time in milliseconds since Unix Epoch |
changed.oid |
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 |
<optional>, default is |
client_id |
<optional>, default is equal to current client id related to authentication token. |
name |
<optional>, default is |
name-eq |
<optional>, default is |
format |
<optional>, default is |
include-deleted |
<optional>, default is |
size |
<optional>, default is 20 |
page |
<optional>, default is 0 |
sort |
<optional>, default is null |
Response documentation
Headers | |
---|---|
|
application/json;charset=UTF-8 |
Payload |
|
content |
Found staging areas of type Staging area. |
last |
indicates if this page is last with current search params |
totalElements |
total amount of objects accessible from this endpoint |
totalPages |
total number of pages available with current page size and total elements |
sort |
current sort params, like |
numberOfElements |
amount of objects returned with this page |
first |
indicates if this page is first with current search params |
size |
current page size |
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 |
Staging area id to look for |
sort |
<optional>, default is null |
Query parameters |
|
dictionary_id |
<optional>, default is |
client_id |
<optional>, default is equal to current client id related to authentication token. |
name |
<optional>, default is |
name-eq |
<optional>, default is |
format |
<optional>, default is |
include-deleted |
<optional>, default is |
Response documentation
Headers | |
---|---|
|
application/json;charset=UTF-8 |
Payload |
|
body |
Found row number for specified parameters, in case when nothing found return |
• Get
GET /api/v4/staging/{id}
Description
Looks for staging area with specified id.
Request documentation
Path parameters |
|
---|---|
id |
Staging area id to look for |
format |
<optional>, default is |
include-deleted |
<optional>, default is |
Response documentation
Headers |
|
---|---|
|
application/json;charset=UTF-8 |
Payload |
|
body |
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 |
JSON object of type Staging area. |
format |
<optional>, default is |
Response documentation
Headers | |
---|---|
|
application/json;charset=UTF-8 |
Payload |
|
body |
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 |
|
---|---|
|
application/json |
Path parameters |
|
id |
Id of Staging area which need to be updated |
Payload |
|
body |
JSON object of type Staging area. Value of |
format |
<optional>, default is |
Response documentation
Headers | |
---|---|
|
application/json;charset=UTF-8 |
Payload |
|
body |
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 PUT /api/v4/staging/{id}
, 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 |
Id of Staging area which need to be updated |
Payload |
|
body |
JSON object of type Staging area. Value of |
format |
<optional>, default is |
Response documentation
Headers | |
---|---|
|
application/json;charset=UTF-8 |
Payload |
|
body |
Patched staging area object. |
• Delete
DELETE /api/v4/staging/{id}
Description
Deletes staging area with specified id.
Request documentation
Path parameters |
|
---|---|
id |
Staging area id to delete |
Response documentation
Headers | |
---|---|
|
text/plain;charset=UTF-8 |
Status |
|
code |
|
• 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 |
Staging area ids of staging areas to delete |
Response documentation
Headers | |
---|---|
|
application/json;charset=UTF-8 |
Status |
|
code |
|
Payload attributes |
|
result |
When operation has completed successfully, this result will contain map with entries where key is |
jobTaskId |
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 |
Staging area id to which this draft belongs. |
clientId |
Client id to which object belongs |
id |
Concept draft id. |
version |
Concept draft version number. Represents latest modification counter. |
deleted |
|
created |
Metadata object containing information about creation |
created.id |
User id created that object |
created.name |
User login created that object |
created.fullName |
User full name created that object |
created.time |
Created date and time in milliseconds since Unix Epoch |
created.oid |
User oid created that object (provided for backward compatibility) |
changed |
Metadata object containing information about last modification |
changed.id |
User id changed that object |
changed.name |
User login changed that object |
changed.fullName |
User full name changed that object |
changed.time |
Last change date and time in milliseconds since Unix Epoch |
changed.oid |
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/
• Create from search
POST /api/v4/concept-drafts/area/{area-id}/concepts
• 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}
13.8.3. Workflows endpoint
Description
Client administrator or dictionary administrator should be able to create/edit workflow for Dictionary.
Workflow allows to set up conditional formatting and triggers on some events.
• Workflow DTO
Object attribute | Description |
---|---|
name |
Workflow name. |
dictionaryId |
Dictionary id to which workflow related. |
clientId |
Client id to which object belongs |
id |
Workflow id. |
oid |
Workflow oid. This is object id from old objects. |
created |
Metadata object containing information about creation |
created.id |
User id created that object |
created.name |
User login created that object |
created.fullName |
User full name created that object |
created.time |
Created date and time in milliseconds since Unix Epoch |
created.oid |
User oid created that object (provided for backward compatibility) |
changed |
Metadata object containing information about last modification |
changed.id |
User id changed that object |
changed.name |
User login changed that object |
changed.fullName |
User full name changed that object |
changed.time |
Last change date and time in milliseconds since Unix Epoch |
changed.oid |
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 |
<optional>, default is |
client_id |
<optional>, default is equal to current client id related to authentication token. |
name |
<optional>, default is |
name-eq |
<optional>, default is |
format |
<optional>, default is |
include-deleted |
<optional>, default is |
size |
<optional>, default is 20 |
page |
<optional>, default is 0 |
sort |
<optional>, default is null |
Response documentation
Headers | |
---|---|
|
application/json;charset=UTF-8 |
Payload |
|
content |
Found workflows of type Workflow. |
last |
indicates if this page is last with current search params |
totalElements |
total amount of objects accessible from this endpoint |
totalPages |
total number of pages available with current page size and total elements |
sort |
current sort params, like |
numberOfElements |
amount of objects returned with this page |
first |
indicates if this page is first with current search params |
size |
current page size |
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 |
Workflow id to look for |
sort |
<optional>, default is null |
Query parameters |
|
dictionary_id |
<optional>, default is |
client_id |
<optional>, default is equal to current client id related to authentication token. |
name |
<optional>, default is |
name-eq |
<optional>, default is |
format |
<optional>, default is |
include-deleted |
<optional>, default is |
Response documentation
Headers | |
---|---|
|
application/json;charset=UTF-8 |
Payload |
|
body |
Found row number for specified parameters, in case when nothing found return |
• Get
GET /api/v4/workflows/{id}
Description
Looks for workflow with specified id.
Request documentation
Path parameters |
|
---|---|
id |
Workflow id to look for |
format |
<optional>, default is |
include-deleted |
<optional>, default is |
Response documentation
Headers |
|
---|---|
|
application/json;charset=UTF-8 |
Payload |
|
body |
JSON object of Workflow. |
• Create
POST /api/v4/workflows/
Description
Creates new workflow from JSON data sent in payload.
Request documentation
Payload |
|
---|---|
body |
JSON object of type Workflow. |
format |
<optional>, default is |
Response documentation
Headers | |
---|---|
|
application/json;charset=UTF-8 |
Payload |
|
body |
Created object of workflow. |
• Update
PUT /api/v4/workflows/{id}
Description
Updates existing workflow from JSON data sent in payload.
Request documentation
Headers |
|
---|---|
|
application/json |
Path parameters |
|
id |
Id of Workflow which need to be updated |
Payload |
|
body |
JSON object of type Workflow. Value of |
format |
<optional>, default is |
Response documentation
Headers | |
---|---|
|
application/json;charset=UTF-8 |
Payload |
|
body |
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 PUT /api/v4/workflows/{id}
, 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 |
Id of Workflow which need to be updated |
Payload |
|
body |
JSON object of type Workflow. Value of |
format |
<optional>, default is |
Response documentation
Headers | |
---|---|
|
application/json;charset=UTF-8 |
Payload |
|
body |
Patched workflow object. |
• Delete
DELETE /api/v4/workflows/{id}
Description
Deletes workflow with specified id.
Request documentation
Path parameters |
|
---|---|
id |
Workflow id to delete |
Response documentation
Headers | |
---|---|
|
text/plain;charset=UTF-8 |
Status |
|
code |
|
• 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 |
Workflow ids of workflows to delete |
Response documentation
Headers | |
---|---|
|
application/json;charset=UTF-8 |
Status |
|
code |
|
Payload attributes |
|
result |
When operation has completed successfully, this result will contain map with entries where key is |
jobTaskId |
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 |
Project name. |
dictionaryId |
Dictionary id to which project related. |
clientId |
Client id to which object belongs |
id |
Project id. |
oid |
Project oid. This is object id from old objects. |
created |
Metadata object containing information about creation |
created.id |
User id created that object |
created.name |
User login created that object |
created.fullName |
User full name created that object |
created.time |
Created date and time in milliseconds since Unix Epoch |
created.oid |
User oid created that object (provided for backward compatibility) |
changed |
Metadata object containing information about last modification |
changed.id |
User id changed that object |
changed.name |
User login changed that object |
changed.fullName |
User full name changed that object |
changed.time |
Last change date and time in milliseconds since Unix Epoch |
changed.oid |
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 |
<optional>, default is |
client_id |
<optional>, default is equal to current client id related to authentication token. |
name |
<optional>, default is |
name-eq |
<optional>, default is |
format |
<optional>, default is |
include-deleted |
<optional>, default is |
size |
<optional>, default is 20 |
page |
<optional>, default is 0 |
sort |
<optional>, default is null |
Response documentation
Headers | |
---|---|
|
application/json;charset=UTF-8 |
Payload |
|
content |
Found projects of type Project. |
last |
indicates if this page is last with current search params |
totalElements |
total amount of objects accessible from this endpoint |
totalPages |
total number of pages available with current page size and total elements |
sort |
current sort params, like |
numberOfElements |
amount of objects returned with this page |
first |
indicates if this page is first with current search params |
size |
current page size |
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 |
Project id to look for |
sort |
<optional>, default is null |
Query parameters |
|
dictionary_id |
<optional>, default is |
client_id |
<optional>, default is equal to current client id related to authentication token. |
name |
<optional>, default is |
name-eq |
<optional>, default is |
format |
<optional>, default is |
include-deleted |
<optional>, default is |
Response documentation
Headers | |
---|---|
|
application/json;charset=UTF-8 |
Payload |
|
body |
Found row number for specified parameters, in case when nothing found return |
• Get
GET /api/v4/projects/{id}
Description
Looks for project with specified id.
Request documentation
Path parameters |
|
---|---|
id |
Project id to look for |
format |
<optional>, default is |
include-deleted |
<optional>, default is |
Response documentation
Headers |
|
---|---|
|
application/json;charset=UTF-8 |
Payload |
|
body |
JSON object of Project. |
• Create
POST /api/v4/projects/
Description
Creates new project from JSON data sent in payload.
Request documentation
Payload |
|
---|---|
body |
JSON object of type Project. |
format |
<optional>, default is |
Response documentation
Headers | |
---|---|
|
application/json;charset=UTF-8 |
Payload |
|
body |
Created object of project. |
• Update
PUT /api/v4/projects/{id}
Description
Updates existing project from JSON data sent in payload.
Request documentation
Headers |
|
---|---|
|
application/json |
Path parameters |
|
id |
Id of Project which need to be updated |
Payload |
|
body |
JSON object of type Project. Value of |
format |
<optional>, default is |
Response documentation
Headers | |
---|---|
|
application/json;charset=UTF-8 |
Payload |
|
body |
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 PUT /api/v4/projects/{id}
, 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 |
Id of Project which need to be updated |
Payload |
|
body |
JSON object of type Project. Value of |
format |
<optional>, default is |
Response documentation
Headers | |
---|---|
|
application/json;charset=UTF-8 |
Payload |
|
body |
Patched project object. |
• Delete
DELETE /api/v4/projects/{id}
Description
Deletes project with specified id.
Request documentation
Path parameters |
|
---|---|
id |
Project id to delete |
Response documentation
Headers | |
---|---|
|
text/plain;charset=UTF-8 |
Status |
|
code |
|
• 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 |
Project ids of projects to delete |
Response documentation
Headers | |
---|---|
|
application/json;charset=UTF-8 |
Status |
|
code |
|
Payload attributes |
|
result |
When operation has completed successfully, this result will contain map with entries where key is |
jobTaskId |
When operation went to asynchronous deletion, this value will have id of running job task. See JobTask. |
13.9. File repository endpoint
Description
File repository allows users to store and share files between multiple dictionaries.
• VirtualFile DTO
Object attribute | Description |
---|---|
name |
VirtualFile name. |
description |
Description of virtual file. |
fileType |
VirtualFile extension of file used during upload. |
mimeType |
VirtualFile mime type of file determined from extension stored in fileType. |
size |
File size in bytes. |
virusCheck |
VirusCheck status enum. Possible values are: |
virusCheckMessage |
In case of failed scan or virus this will have information about it. |
virusCheckAttempt |
Serial number of virus check attempt. |
virusCheckLastAttempt |
Last time of virus check in milliseconds since Unix Epoch. |
clientId |
Client id to which object belongs |
id |
VirtualFile id. |
oid |
VirtualFile oid. This is object id from old objects. |
created |
Metadata object containing information about creation |
created.id |
User id created that object |
created.name |
User login created that object |
created.fullName |
User full name created that object |
created.time |
Created date and time in milliseconds since Unix Epoch |
created.oid |
User oid created that object (provided for backward compatibility) |
changed |
Metadata object containing information about last modification |
changed.id |
User id changed that object |
changed.name |
User login changed that object |
changed.fullName |
User full name changed that object |
changed.time |
Last change date and time in milliseconds since Unix Epoch |
changed.oid |
User oid changed that object (provided for backward compatibility) |
• Find
GET /api/v4/files/
Description
Finds virtual files with specified query parameters available to current user.
Request documentation
Query parameters |
|
---|---|
name |
<optional>, default is |
name-eq |
<optional>, default is |
format |
<optional>, default is |
include-deleted |
<optional>, default is |
size |
<optional>, default is 20 |
page |
<optional>, default is 0 |
sort |
<optional>, default is null |
Response documentation
Headers | |
---|---|
|
application/json;charset=UTF-8 |
Payload |
|
content |
Found virtual files of type VirtualFile. |
last |
indicates if this page is last with current search params |
totalElements |
total amount of objects accessible from this endpoint |
totalPages |
total number of pages available with current page size and total elements |
sort |
current sort params, like |
numberOfElements |
amount of objects returned with this page |
first |
indicates if this page is first with current search params |
size |
current page size |
number |
current page number |
• Row number
GET /api/v4/files/rownum/{id}
Description
Finds rownumber of virtual file 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 |
VirtualFile id to look for |
sort |
<optional>, default is null |
Query parameters |
|
name |
<optional>, default is |
name-eq |
<optional>, default is |
format |
<optional>, default is |
include-deleted |
<optional>, default is |
Response documentation
Headers | |
---|---|
|
application/json;charset=UTF-8 |
Payload |
|
body |
Found row number for specified parameters, in case when nothing found return |
• Get
GET /api/v4/files/{id}
Description
Looks for virtual file with specified id.
Request documentation
Path parameters |
|
---|---|
id |
VirtualFile id to look for |
format |
<optional>, default is |
include-deleted |
<optional>, default is |
Response documentation
Headers |
|
---|---|
|
application/json;charset=UTF-8 |
Payload |
|
body |
JSON object of VirtualFile. |
• File data
GET /api/v4/files/{id}/data
Description
This operation retrieves a file contents from server.
Request documentation
Path parameters |
|
---|---|
id |
VirtualFile id to look for. |
Response documentation
Headers | |
---|---|
|
|
|
attachment; filename=“ |
|
|
Status |
|
code |
|
Payload |
|
body |
File contents of file. |
• Update
PUT /api/v4/files/{id}
Description
Updates existing virtual file from JSON data sent in payload.
Request documentation
Headers |
|
---|---|
|
application/json |
Path parameters |
|
id |
Id of VirtualFile which need to be updated |
Payload |
|
body |
JSON object of type VirtualFile. Value of |
format |
<optional>, default is |
Response documentation
Headers | |
---|---|
|
application/json;charset=UTF-8 |
Payload |
|
body |
Updated virtual file object. |
• Upload
POST /api/v4/files/upload
Description
This method allows to create a new VirtualFile or update existing one by uploading its contents.
Request documentation
Headers |
|
---|---|
|
multipart/form-data |
Payload fields |
|
file |
Multipart data containing dictionary definition file. |
file-id |
(Optional) provide VirtualFile.id when you need to update existing file. |
file-name |
Name of uploaded file |
file-description |
(Optional) Description for uploaded file |
Response documentation
Headers |
|
---|---|
|
application/json;charset=UTF-8 |
Payload |
|
body |
JSON object of VirtualFile. |
• Delete
DELETE /api/v4/files/{id}
Description
Deletes virtual file with specified id.
Request documentation
Path parameters |
|
---|---|
id |
VirtualFile id to delete |
Response documentation
Headers | |
---|---|
|
text/plain;charset=UTF-8 |
Status |
|
code |
|
14. API methods Index
Authentication
POST /api/v4/login
POST /api/v4/logout
GET /api/v4/validate
POST /api/v4/extend-sesion
POST /api/v4/switch-client
Clients
GET /api/v4/clients/available
POST /api/v4/clients/generate-new-api-key/{client-id}
GET /api/v4/clients/
GET /api/v4/clients/rownum/{id}
GET /api/v4/clients/{id}
POST /api/v4/clients/
PUT /api/v4/clients/{id}
PUT /api/v4/clients/partial/{id}
DELETE /api/v4/clients/{id}
DELETE /api/v4/clients/async/{id[]}
API synchronization settings
GET /api/v4/sync-settings/
GET /api/v4/sync-settings/rownum/{id}
GET /api/v4/sync-settings/{id}
POST /api/v4/sync-settings/
PUT /api/v4/sync-settings/{id}
PUT /api/v4/sync-settings/partial/{id}
DELETE /api/v4/sync-settings/{id}
DELETE /api/v4/sync-settings/async/{id[]}
Job tasks
License
Features
Users
POST /api/v4/users/import/
GET /api/v4/users/export/
PUT /api/v4/users/assign-clients/
GET /api/v4/users/password-settings/
GET /api/v4/users/guest/
PUT /api/v4/users/guest/
GET /api/v4/users/
GET /api/v4/users/rownum/{id}
GET /api/v4/users/{id}
POST /api/v4/users/
PUT /api/v4/users/{id}
PUT /api/v4/users/partial/{id}
DELETE /api/v4/users/{id}
DELETE /api/v4/users/async/{id[]}
Groups
GET /api/v4/groups/
GET /api/v4/groups/rownum/{id}
GET /api/v4/groups/{id}
POST /api/v4/groups/
PUT /api/v4/groups/{id}
PUT /api/v4/groups/partial/{id}
DELETE /api/v4/groups/{id}
DELETE /api/v4/groups/async/{id[]}
Permissions
Dictionaries
GET /api/v4/dictionaries/data-categories
POST /api/v4/dictionaries/language-replace/
GET /api/v4/dictionaries/
GET /api/v4/dictionaries/rownum/{id}
GET /api/v4/dictionaries/{id}
POST /api/v4/dictionaries/copy/{id}
POST /api/v4/dictionaries/empty/{id}
POST /api/v4/dictionaries/reindex/{id}
POST /api/v4/dictionaries/export-definition/{id}
POST /api/v4/dictionaries/import-definition/start
PUT /api/v4/dictionaries/import-definition/process-dictionary/
PUT /api/v4/dictionaries/import-definition/process-filter/
POST /api/v4/dictionaries/
PUT /api/v4/dictionaries/{id}
DELETE /api/v4/dictionaries/{id}
DELETE /api/v4/dictionaries/async/{id[]}
Sections
POST /api/v4/sections/clear/
GET /api/v4/sections/
GET /api/v4/sections/rownum/{id}
GET /api/v4/sections/{id}
POST /api/v4/sections/
PUT /api/v4/sections/{id}
PUT /api/v4/sections/partial/{id}
DELETE /api/v4/sections/{id}
DELETE /api/v4/sections/async/{id[]}
Fields
GET /api/v4/fields/incremental-next/{field-oid}
GET /api/v4/fields/incremental/validate/{field-oid}
GET /api/v4/fields/generate-picklist/{field-oid}
Domains
GET /api/v4/domains/
GET /api/v4/domains/rownum/{id}
GET /api/v4/domains/{id}
POST /api/v4/domains/
PUT /api/v4/domains/{id}
PUT /api/v4/domains/partial/{id}
DELETE /api/v4/domains/{id}
DELETE /api/v4/domains/async/{id[]}
Filters
POST /api/v4/filters/index/{id}
GET /api/v4/filters/
GET /api/v4/filters/rownum/{id}
GET /api/v4/filters/{id}
POST /api/v4/filters/
PUT /api/v4/filters/{id}
PUT /api/v4/filters/partial/{id}
DELETE /api/v4/filters/{id}
DELETE /api/v4/filters/async/{id[]}
Views
GET /api/v4/views/
GET /api/v4/views/rownum/{id}
GET /api/v4/views/{id}
POST /api/v4/views/
PUT /api/v4/views/{id}
PUT /api/v4/views/partial/{id}
DELETE /api/v4/views/{id}
DELETE /api/v4/views/async/{id[]}
Concepts
GET /api/v4/concepts/{id}
GET /api/v4/concepts/
POST /api/v4/concepts/
PUT /api/v4/concepts/{id}
DELETE /api/v4/concepts/{id}
PUT /api/v4/concepts/{id}/acquire-lock
PUT /api/v4/concepts/{id}/release-lock
GET /api/v4/concepts/{id}/print-as-html
GET /api/v4/concepts/{id}/permissions
Terms
Display concepts
GET /api/v4/display-concepts/{id}
POST /api/v4/display-concepts/create/{dictionary-id}
PUT /api/v4/display-concepts/edit/{concept-id}
POST /api/v4/display-concepts/copy/{concept-id}
POST /api/v4/display-concepts/add-term/{concept-id}
POST /api/v4/display-concepts/copy/{concept-id}
Comments
History
GET /api/v4/history/concept/{concept-id}
GET /api/v4/history/dictionary/{dictionary-id}
POST /api/v4/history/concept-undo/
POST /api/v4/history/dictionary-undo/
User Session data
User Profile
UI Menu
User search settings
GET /api/v4/user-search-settings/
PUT /api/v4/user-search-settings/
PUT /api/v4/profile/user-search-settings/
Workflows
GET /api/v4/workflows/
GET /api/v4/workflows/rownum/{id}
GET /api/v4/workflows/{id}
POST /api/v4/workflows/
PUT /api/v4/workflows/{id}
PUT /api/v4/workflows/partial/{id}
DELETE /api/v4/workflows/{id}
DELETE /api/v4/workflows/async/{id[]}
Projects
15. DTO Index
APISyncSettings
Client
Comment
Concept
Concept draft
Concept relation
DataCategory
Dictionary
Display concept
Display field
Display term
Domain
Field
Field Model
Filter
Filter criterion
Group
GuestSettings
History item
JobTask
Language
Language Variant
License
Menu item
NamedObject
Permission scheme
Picklist item
Profile
Project
RefLink
Search settings
Section
Session data
Staging area
Term
User
View
VirtualFile
Workflow