From 625b3c761f73d27576178276045ddf60d01ce265 Mon Sep 17 00:00:00 2001 From: Robert Barbey Date: Mon, 10 Mar 2025 09:34:25 +0100 Subject: [PATCH 01/18] docs: pasted Term API docs into apib file --- apiary.apib | 700 ++++++++++++++++++++++++++++++++++++++++++++++++++++ term-api.md | 699 --------------------------------------------------- 2 files changed, 700 insertions(+), 699 deletions(-) delete mode 100644 term-api.md diff --git a/apiary.apib b/apiary.apib index 0dede0ad..823319cf 100644 --- a/apiary.apib +++ b/apiary.apib @@ -7776,3 +7776,703 @@ This will download data only with the fields `checkId`, `date`, `guidelineId` an "code": 500, "message": "Something went wrong. Try again or contact Acrolinx Support." } + +# Group Terminology API v7 + +## Deprecation Note + +**Warning:** Communication using the SDL *MultiTerm XML* format is deprecated. +While it still works today, support can be removed at any time. + +## Preliminaries + +All service operations are demonstrated by a `curl` (cf. [curl man page](http://curl.haxx.se/docs/manpage.html)) command +line that can be executed against a real Acrolinx Core Platform installation, replacing any variable references +`${variable}` by the appropriate values. + +### Authorization + +Before invoking any Terminology API, the Acrolinx Integration must authorize and acquire a session. +The authorization itself isn’t part of the Terminology API, but the [Core Platform Core API](README.md#authentication). +API Requests without a valid session ID in the `Authorization` HTTP header field fail: + +```bash +curl -i -H "Accept: application/vnd.acrolinx.mtf+xml" -X GET http://${serverHostName}:8031/iq/services/v7/rest/terminology/entries/a918fccf-4a94-4398-b260-4d792289952c +``` + +```text +HTTP/1.1 403 Forbidden +Content-Type: application/json +Date: Wed, 12 Mar 2014 16:34:51 GMT +exception_message: Invalid session (no such session) +exception_type: com.acrolinx.services.faults.InvalidSessionFault +Transfer-Encoding: chunked + +{ + "message": "Invalid session (no such session)", + "errors": { + "exception_type": "com.acrolinx.services.faults.InvalidSessionFault", + "exception_message": "Invalid session (no such session)" + } +} +``` + +### Acquiring a Session + +Using the authentication token, the integration now needs to open a session, specifying the session-type (always +`TERMINOLOGY` for usage of the terminology API) and the signature of the integration (see section Signatures below). + +Example of a session request body: + +```json +{ + "sessionType": "TERMINOLOGY", + "clientSignature": "SW50ZWdyYXRpb25EZXZlbG9wbWVudERlbW9Pbmx5", + "clientInfo": { + "buildNumber": "unknown", + "clientHostname": "localhost", + "version": "0.1", + "name": "Terminology Test Client", + "clientHostApplication": "unknown", + "clientLoginName": "unknown" + } +} +``` + +To request a session, do a `POST` on `/iq/services/v3/rest/core/requestSession`: + +```bash +curl -i -H "Content-Type: application/json; charset=UTF-8" -H "authToken: ${authToken}" -H "connection: keep-alive" -X POST http://${serverHostName}:8031/iq/services/v3/rest/core/requestSession -d "{\"sessionType\":\"TERMINOLOGY\",\"clientSignature\":\"${clientSignature}\",\"clientInfo\":{\"name\":\"terminology-example\",\"version\":\"1\",\"buildNumber\":\"1\",\"clientLoginName\":\"unknown\",\"clientHostname\":\"${clientHostName}\",\"clientHostApplication\":\"unknown\"}}" +``` + +```text + HTTP/1.1 200 OK + Content-Type: text/plain + Date: Wed, 12 Mar 2014 16:34:51 GMT + Content-Length: 16 + + 56429c06fbd5da74 +``` + +The returned session token should be used in subsequent requests to the Terminology API. It’s valid until +the session is released by the integration or by the Core Platform. +As the license limits the number of concurrently opened sessions, +an integration mustn’t forget to release a session before acquiring a new session token. + +### Releasing a Session + +A session can be released by a `DELETE` on `/iq/services/v3/rest/core/releaseSession`, providing the session as path +parameter: + +```bash +curl -i -X DELETE http://${serverHostName}:8031/iq/services/v3/rest/core/releaseSession/${session2} +``` + +```text +HTTP/1.1 204 No Content +Content-Length: 0 +Date: Wed, 12 Mar 2014 16:34:51 GMT +``` + +#### Signatures + +An integration must identify itself to the Core Platform by means of a unique signature. This signature tells the Core +Platform which integration is trying to communicate to it. Depending on the signature the communication might be allowed. +Signatures can be enabled individually in the Core Platform's license. To request a session with the Core Platform, an integration's +signature is one of the required parameters. If the signature is unknown to the Core Platform, +no session can be opened and further communication isn’t possible. + +Acrolinx issues specific signatures to integrators. + +## Terminology Service Methods + +The prefix to all v7 terminology API service paths is `http://${serverHostName}:8031/iq/services/v7/rest/terminology`. + +Required privileges: + +- for all terminology service API methods, the user must have at least the `Access API-based terminology applications` + privilege + +### Configuration + +Before invoking one of the Terminology API services for the result format SDL MultiTerm, the Core Platform must be +configured correctly. This includes that there are XSL transformations from ACTIF to SDL MultiTerm XML and SDL MultiTerm +Definition XDT. The needed XSL style sheets will be available as part of the Core Platform resources. + +The availability of those resources can be checked in the Acrolinx Dashboard on +`Terminology -> Import and Export -> Import/Export -> Custom File Format`. + +### Media/Content Types + +Except for application-specific XML data (ACTIF resp. SDL MultiTerm XML/XDT data), request, and response data is usually +either plain text or in JSON format. The encoding is usually assumed to be UTF-8. + +With some service methods, you can control the format of the return values by means of the standard HTTP `Accept` header. + +Service methods that accept application-specific body data rely on the correct setting of the standard HTTP +`Content-Type` header. + +The supported media types are listed where applicable. + +### Getting Existing Entries by UUID or ID + +Supported media types: + +- `application/vnd.acrolinx.actif+xml`: return entries as ACTIF in XML +- `application/vnd.acrolinx.mtf+xml`: return entries as SDL MultiTerm XML + +Required privilege: + +- Terminology - View Terms + +This functionality is provided by `GET` `/entries`. There are two variants of this operation: + +- asking for a single UUID or ID +- asking for many UUIDs or IDs + +For asking for only one entry simply, append its UUID to the service URI: + +```bash +curl -i -H "Accept: application/vnd.acrolinx.mtf+xml" -H "Authorization: session ee7ac269aed25b4e" -X GET http://${serverHostName}:8031/iq/services/v7/rest/terminology/entries/a918fccf-4a94-4398-b260-4d792289952c +``` + +```text +HTTP/1.1 200 OK +Content-Type: application/vnd.acrolinx.mtf+xml +Date: Wed, 12 Mar 2014 16:34:51 GMT +Content-Length: 8521 + +13a918fccf-4a94-4398-b260-4d792289952cadmin2011-06-28T11:55:28+02:00admin2014-02-03T11:00:04return airpreferredTechnical_Namesundefined domain120bdf01-4818-4a2c-bcea-4f875b6b129a13711976956060undefinedundefinedundefinedunprocessedundefinedadmin2011-06-28T11:55:28+02:00admin2014-02-03T11:00:04text nicht vorhandenproposedundefined domain680e0ea1-90f1-48ab-9ec9-5a362360692d13711976956220undefinedundefinedundefinedunprocessedundefinedadmin2011-06-28T12:11:20+02:00marco.aeschimann@ch.sauter-bc.com2011-07-05T10:54:28+02:00text nicht vorhandenproposedundefined domain01352af7-73e6-4024-9433-930846681b5613711976956300undefinedundefinedundefinedunprocessedundefinedadmin2011-06-28T12:11:19+02:00eric.schneider@ch.sauter-bc.com2011-09-13T10:47:25+02:00AbluftmengeproposedTechnical_Namesundefined domain44641d47-ddf3-4bb4-b1d4-a22a3fb42f6413711976956460undefinedundefinedundefinedunprocessedundefinedadmin2011-06-28T11:55:28+02:00admin2014-02-03T10:59:47débit d'air reprispreferredTechnical_Namesundefined domain5334a674-848b-44a3-8b42-1756d38717ef13711976956140undefinedundefinedundefinedunprocessedundefinedadmin2011-06-28T11:55:28+02:00admin2014-02-03T10:59:54débit d'évacuationdeprecatedTechnical_Namesundefined domain38e4ce12-4175-465e-a26f-4bb6d8a7ea1513711976956540undefinedundefinedundefinedunprocessedundefinedadmin2011-06-28T11:55:28+02:00admin2014-02-03T10:59:58text nicht vorhandenproposedundefined domain7958d666-8511-4c0e-aef1-d0f4748d2d4613711976956380undefinedundefinedundefinedunprocessedundefinedadmin2011-06-28T12:11:18+02:00admin2011-08-30T11:55:38+02:00 +``` + +This works the same way for entry IDs (the server determines by the format of the passed ID string whether it’s a UUID or +an ID): + +```bash +curl -i -H "Accept: application/vnd.acrolinx.mtf+xml" -H "Authorization: session ee7ac269aed25b4e" -X GET http://${serverHostName}:8031/iq/services/v7/rest/terminology/entries/13 +``` + +```text +HTTP/1.1 200 OK +Content-Type: application/vnd.acrolinx.mtf+xml +Date: Wed, 12 Mar 2014 16:34:51 GMT +Content-Length: 8521 + +13a918fccf-4a94-4398-b260-4d792289952cadmin2011-06-28T11:55:28+02:00admin2014-02-03T11:00:04return airpreferredTechnical_Namesundefined domain120bdf01-4818-4a2c-bcea-4f875b6b129a13711976956060undefinedundefinedundefinedunprocessedundefinedadmin2011-06-28T11:55:28+02:00admin2014-02-03T11:00:04text nicht vorhandenproposedundefined domain680e0ea1-90f1-48ab-9ec9-5a362360692d13711976956220undefinedundefinedundefinedunprocessedundefinedadmin2011-06-28T12:11:20+02:00marco.aeschimann@ch.sauter-bc.com2011-07-05T10:54:28+02:00text nicht vorhandenproposedundefined domain01352af7-73e6-4024-9433-930846681b5613711976956300undefinedundefinedundefinedunprocessedundefinedadmin2011-06-28T12:11:19+02:00eric.schneider@ch.sauter-bc.com2011-09-13T10:47:25+02:00AbluftmengeproposedTechnical_Namesundefined domain44641d47-ddf3-4bb4-b1d4-a22a3fb42f6413711976956460undefinedundefinedundefinedunprocessedundefinedadmin2011-06-28T11:55:28+02:00admin2014-02-03T10:59:47débit d'air reprispreferredTechnical_Namesundefined domain5334a674-848b-44a3-8b42-1756d38717ef13711976956140undefinedundefinedundefinedunprocessedundefinedadmin2011-06-28T11:55:28+02:00admin2014-02-03T10:59:54débit d'évacuationdeprecatedTechnical_Namesundefined domain38e4ce12-4175-465e-a26f-4bb6d8a7ea1513711976956540undefinedundefinedundefinedunprocessedundefinedadmin2011-06-28T11:55:28+02:00admin2014-02-03T10:59:58text nicht vorhandenproposedundefined domain7958d666-8511-4c0e-aef1-d0f4748d2d4613711976956380undefinedundefinedundefinedunprocessedundefinedadmin2011-06-28T12:11:18+02:00admin2011-08-30T11:55:38+02:00 +``` + +For the more general case, to ask for many entries at the same time specify the UUIDs (or IDs) as a comma-separated list +after the `/entries/` endpoint URL: + +```bash +curl -i -H "Accept: application/vnd.acrolinx.mtf+xml" -H "Authorization: session ee7ac269aed25b4e" -H "Content-Type: application/json" -X GET http://${serverHostName}:8031/iq/services/v7/rest/terminology/entries/a918fccf-4a94-4398-b260-4d792289952c,ee1c8221-5ac2-465a-bcb8-2f329ba0da8a +``` + +```text +HTTP/1.1 200 OK +Content-Type: application/vnd.acrolinx.mtf+xml +Date: Wed, 12 Mar 2014 16:34:51 GMT +Content-Length: 11081 + +1391421694240ee1c8221-5ac2-465a-bcb8-2f329ba0da8aadmin2014-02-03T11:01:34admin2014-02-03T11:01:36neuer TermpreferredTechnical_Names79425649-0a70-458a-8cf8-910539b9a1f313911896143950undefinedundefinedundefinedunprocessedundefinedadmin2014-02-03T11:01:34admin2014-02-03T11:01:36new termproposedTechnical_Names06208308-e8ca-4dbd-91fd-add7ca4f5e9013911896145610undefinedundefinedundefinedunprocessedundefinedadmin2014-02-03T11:01:51admin2014-02-03T11:01:5113a918fccf-4a94-4398-b260-4d792289952cadmin2011-06-28T11:55:28+02:00admin2014-02-03T11:00:04return airpreferredTechnical_Namesundefined domain120bdf01-4818-4a2c-bcea-4f875b6b129a13711976956060undefinedundefinedundefinedunprocessedundefinedadmin2011-06-28T11:55:28+02:00admin2014-02-03T11:00:04text nicht vorhandenproposedundefined domain680e0ea1-90f1-48ab-9ec9-5a362360692d13711976956220undefinedundefinedundefinedunprocessedundefinedadmin2011-06-28T12:11:20+02:00marco.aeschimann@ch.sauter-bc.com2011-07-05T10:54:28+02:00text nicht vorhandenproposedundefined domain01352af7-73e6-4024-9433-930846681b5613711976956300undefinedundefinedundefinedunprocessedundefinedadmin2011-06-28T12:11:19+02:00eric.schneider@ch.sauter-bc.com2011-09-13T10:47:25+02:00AbluftmengeproposedTechnical_Namesundefined domain44641d47-ddf3-4bb4-b1d4-a22a3fb42f6413711976956460undefinedundefinedundefinedunprocessedundefinedadmin2011-06-28T11:55:28+02:00admin2014-02-03T10:59:47débit d'air reprispreferredTechnical_Namesundefined domain5334a674-848b-44a3-8b42-1756d38717ef13711976956140undefinedundefinedundefinedunprocessedundefinedadmin2011-06-28T11:55:28+02:00admin2014-02-03T10:59:54débit d'évacuationdeprecatedTechnical_Namesundefined domain38e4ce12-4175-465e-a26f-4bb6d8a7ea1513711976956540undefinedundefinedundefinedunprocessedundefinedadmin2011-06-28T11:55:28+02:00admin2014-02-03T10:59:58text nicht vorhandenproposedundefined domain7958d666-8511-4c0e-aef1-d0f4748d2d4613711976956380undefinedundefinedundefinedunprocessedundefinedadmin2011-06-28T12:11:18+02:00admin2011-08-30T11:55:38+02:00 +``` + +**Note: The length of the request URL is limited by any HTTP server implementation. Based to our tests, we don't +recommend exceeding the value of 4000 characters.** + +### Querying the Term Base Structure + +Supported media types: + +- `application/vnd.acrolinx.actif+xml`: return schema as ACTIF in XML +- `application/vnd.acrolinx.mtf+xdt`: return entries as SDL MultiTerm XDT + +Required privilege: + +- Terminology - View Terms + +This functionality is provided by GET `/schema`. The structure of the Acrolinx term base can then be retrieved as +follows (in the example the SDL MultiTerm XDT representation is requested): + +```bash +curl -i -H "Accept: application/vnd.acrolinx.mtf+xdt" -H "Authorization: session ee7ac269aed25b4e" -X GET http://${serverHostName}:8031/iq/services/v7/rest/terminology/schema +``` + +```text +HTTP/1.1 200 OK +Content-Type: application/vnd.acrolinx.mtf+xdt +Date: Wed, 12 Mar 2014 16:34:52 GMT +Content-Length: 21990 + +Entry level0110ENTRY_UUID1001sourceOfDefinition1000definition1000Project ID1000imageURL1000Index level2110Term level3110Status1100domain1110MORPHOSYNTACTIC_RESTRICTION1001TERM_UUID1001TERM_ID1000VARIANTS_CONFIGURATIONS1001HISTORY_EVENT1001assignedTo1000project1000termType1000externalCrossReference1000processStatus1000geographicalUsage1000crossReference1000Number1000sourceOfTerm1000Usage note1000customer1000Unit1000Part of Speech1000gender1000Core1000Phrase1000note space1000context1000ARArabicfalseBGBulgarianfalseCSCzechfalseDEGermanfalseENEnglishfalseEN-GBEnglish (UK)falseEN-USEnglish (USA)falseESSpanishfalseFRFrenchfalseITItalianfalseJAJapanesefalseKOKoreanfalseNLDutchfalseNONorwegianfalsePTPortuguesefalseRURussianfalseSVSwedishfalseZHChinesefalseZH-CNChinese (PRC)falseZH-TWChinese (Taiwan)falseENTRY_UUIDTextFsourceOfDefinitionTextFdefinitionTextFProject IDTextFimageURLMultimedia FileFStatusPicklistproposedproposed_from_searchdeprecatedadmittedpreferrednon-termstopwordno-single-termFdomainPicklistundefined domaincustomerSpecial SymbolsDemoSwitchesKeitaidenwaKanaKanjiUsageADSLMFPDruckerAcrolinxStandard_TerminologyRoutersBelkinD-LinkCiscoPhoneASD-STE100Technical_NamesTN_1_Official_Parts_InformationTN_2_Locations_On_Machines_Vehicles_Or_EquipmentTN_3_Tools_Or_EquipmentTN_4_Materials_Consumables_Or_Unwanted_MatterTN_5_Facilities_And_InfrastructureTN_6_Circuits_Or_SystemsTN_7_Mathematical_Scientific_Or_Engineering_TermsTN_8_NavigationTN_9_Numbers_Units_Of_Measurement_Or_Dial_MarkingsTN_10_Quoted_TextTN_11_Persons_Groups_Or_BodiesTN_12_Body_PartsTN_13_Common_Personal_EffectsTN_14_Medical_TermsTN_15_Documents_Or_ManualsTN_16_Names_Headings_And_Topics_In_SpecificationsTN_17_Technical_Records_Standards_Specifications_Or_RegulationsTN_18_Environmental_ConditionsTN_19_ColorsTN_20_Damage_TermsTN_UnclassifiedTechnical_VerbsTV_1_Manufacturing_ProcessesTV_2_Computer_Processes_And_ApplicationsTV_3_DescriptionsTV_UnclassifiedS1000D Bike Data SetFMORPHOSYNTACTIC_RESTRICTIONPicklistallnounverbadjectiveadverbadpositionprepositiondeterminerconjunctionpronounprefixsuffixFTERM_UUIDTextFTERM_IDTextFVARIANTS_CONFIGURATIONSTextFHISTORY_EVENTTextFassignedToTextFprojectTextFtermTypePicklisttrademarkundefinedfull formacronymabbreviationshort formvariantphraseFexternalCrossReferenceTextFprocessStatusPicklistunprocessedprovisionally processedfinalizedreview requestedFgeographicalUsageTextFcrossReferenceTextFNumberTextFsourceOfTermTextFUsage noteTextFcustomerTextFUnitTextFPart of SpeechPicklistadjectiveadverbnounotherproper nounundefinedverbFgenderPicklistundefinedmasculinefeminineneuterotherFCorePicklistundefinedcoreFPhraseTextFnote spaceTextFcontextTextF10Exported from Acrolinx at 2014-03-12 17:34:52 +``` + +### Querying for Available Filters + +The only supported media type is `application/json`. + +Required privilege: + +- Terminology - View Terms + +The terminology service API offers an operation to get the ids/names of all filters for term search operations, that are +available to the user in the current session. The available filters can be retrieved by `GET` to `/filters`: + +```bash +curl -i -H "Accept: application/json" -H "Authorization: session ee7ac269aed25b4e" -X GET http://${serverHostName}:8031/iq/services/v7/rest/terminology/filters +``` + +```text +HTTP/1.1 200 OK +Content-Type: application/json +Date: Wed, 12 Mar 2014 16:34:52 GMT +Transfer-Encoding: chunked + +{ + "user": "admin", + "filters": [ + { + "id": "Preferred Technical Names" + }, + { + "id": "SEO" + }, + { + "id": "Images" + } +] +} +``` + +The filters can be referenced by their `id` in a search API operation, described in the next section. + +### Searching Terms + +Terms can be searched by: + +- term `name`, supporting '%' as wildcard; +- `language` id +- `domains` an array of one or several domain names +- `filter` id +- or any combination of the above + +The individual fields of the search criteria need to be "escaped" by their unicode positions in case they contain +characters that would otherwise break the JSON request string. For example, the apostrophe/single quote character `'` is +escaped as `\u0027`. + +The search API supports pagination to retrieve only a certain subset of the result set. The parameters are: + +- `offset`, the index of the first term to display (starting from 0, where the terms are always sorted ascending by + their name) +- `limit`, the maximal number of terms to return, starting from `offset`; if < 1, no limit is imposed + +The only supported media type for request as well as result is `application/json`. + +Required privilege: + +- Terminology - View Terms + +The search-terms service function requires a request object in the format illustrated by the following example: + +```json +{ + "criteria": { + "name": "d\\u00e9bit%", + "language": "fr", + "domains": ["Technical Names", "Demo"], + "filter": "Preferred Technical Names" + }, + "pagination": { + "offset": 0, + "limit": -1 + } +} +``` + +The `criteria` and `pagination` values are mandatory, as well as `offset` and `limit`, but you can leave out (or set to +`null`) those fields of `criteria` that aren’t required by a specific query (for `domains` you can also pass an empty +array `[]`). + +The criteria that exist in the search request are then combined by AND (if `domains` contains more than one value, they’re + combined into a domain filter by OR-ing them) in the resulting filter. + +You can then search with those settings by submitting a `POST`-request to `/searchTerms`: + +```bash +curl -i -H "Content-Type: application/json; charset=UTF-8" -H "Accept: application/json" -H "Authorization: session ee7ac269aed25b4e" -X POST http://${serverHostName}:8031/iq/services/v7/rest/terminology/searchTerms -d '{"criteria":{"name":"d%","language": "fr","domains":["undefined domain", "Technical Names"], "filter":null},"pagination":{"offset": 0,"limit": -1}}' +``` + +```text +HTTP/1.1 200 OK +Content-Type: application/json +Date: Wed, 12 Mar 2014 16:34:52 GMT +Transfer-Encoding: chunked + +{ + "terms": [ + { + "name": "débit d\u0027air repris", + "status": "preferred", + "domains": [ + "Technical_Names", + "undefined domain" + ], + "uuid": "5334a674-848b-44a3-8b42-1756d38717ef", + "entry": { + "uuid": "a918fccf-4a94-4398-b260-4d792289952c", + "id": "13" + } + }, + { + "name": "débit d\u0027évacuation", + "status": "deprecated", + "domains": [ + "Technical_Names", + "undefined domain" + ], + "uuid": "38e4ce12-4175-465e-a26f-4bb6d8a7ea15", + "entry": { + "uuid": "a918fccf-4a94-4398-b260-4d792289952c", + "id": "13" + } + } + ], + "search": { + "pagination": { + "offset": 0, + "limit": -1 + }, + "criteria": { + "name": "d%", + "language": "fr", + "filter": null, + "domains": [ + "undefined domain", + "Technical Names" + ] + } + }, + "totalResultCount": 2 +} +``` + +(Note: there exists indeed a domain name `undefined domain` in the Core Platform default setup; +that value doesn't indicate the absence of a value for the domain.) + +The response is a JSON object with the following attributes: + +- `search` contains your search criteria and pagination settings; you could reuse that object for subsequent calls with + the same criteria +- `totalResultCount` is the total number of hits for the search, before applying the pagination limit +- `terms`: an array of term objects, each containing the attributes `name`, `status`, `domains`, `uuid` (the UUID of the + term: use that UUID to identify the specific term data from the full entry that you retrieve by the entry UUID), + `entry`; `entry` again is an object with two attributes `uuid` and `id`, the UUID, and ID of the entry. Using the entry + UUID or ID you can then retrieve the entire entry via `GET` `/entries` (see above). + +If there are no matching terms (or you request an offset greater than the result count), `terms` will be an empty array. +If your search request refers to a nonexistent filter, the server will respond with a 400 (Bad Request). + +### Getting Terms with Search Criteria + +You can also search for terms using an older method called `findTerms`, which supports some search criteria that +aren’t available in the `searchTerms` method above, and which also returns the result in a specified target format, +just like `get entries` described above. + +The following search criteria are supported: + +- term `surface` (name), supporting '%' as wildcard +- `language` id +- `domain` - a single domain name +- `entry ID/UUID` - an array of entry IDs or entry UUIDs +- custom criteria - an array of `field=value` strings, where `field` is one of the following ACTIF field names: + + `term/id` + + `term/uuid` + + `entry/id` + + `enty/uuid` + + `term/creation-date-time` (prepend with `<` or `>` to find terms created before or after the given date) + + `term/last-modification-date-time` (prepend with `<` or `>` to find terms modified before or after the given date) + + `term/creator-user-name` + + `term/last-modifier` + + any custom field name (as it appears in ACTIF) + +The individual fields of the search criteria need to be "escaped" by their unicode positions in case they contain +characters that would otherwise break the JSON request string. For example, the apostrophe/single quote character `'` is +escaped as `\u0027`. + +All criteria are combined with `AND` when the term filter is constructed. All criteria are optional; if you don’t give +any criteria, the result includes all terms. + +The desired result format needs to be specified in the required `format` attribute of the request object (not in the +`Accept` HTTP header). The supported media types are the same as for the "get entries" method above: + +- `application/vnd.acrolinx.actif+xml`: return terms as ACTIF in XML +- `application/vnd.acrolinx.mtf+xml`: return terms as SDL MultiTerm XML + +Finally, you can optionally have the term base structure (schema) included in the response by setting the `withSchema` +attribute to `true`. + +Required privilege: + +- Terminology - View Terms + +The find-terms service function requires a request object in the format illustrated by the following example: + +```json +{ + "surface": "d\\u00e9bit%", + "language": "fr", + "domain": ["Demo"], + "customCriteria": [ + "term/creation-date-time=<2012-05-10T11:41:00", + "customWorkflowStatus=reviewed" + ], + "withSchema": false, + "format": "application/vnd.acrolinx.mtf+xml" +} +``` + +You can then search with those settings by `POST`ing the request to `/findTerms/`. (Note that the terminology +session is part of the URL here; the `Authorization` header is ignored.) + +```bash +curl -i -H \"Content-Type: application/json; charset=UTF-8\" -X POST http://${serverHostName}:8031/iq/services/v7/rest/terminology/findTerms/ee7ac269aed25b4e -d '{"name":"d%","language": "fr","customCriteria":["term/uuid=a918fccf-4a94-4398-b260-4d792289952c"], "format":"application/vnd.acrolinx.mtf+xml"}' +``` + +```text +HTTP/1.1 200 OK +Content-Type: application/vnd.acrolinx.mtf+xml +Date: Wed, 12 Mar 2014 16:34:51 GMT +Content-Length: 8521 + +13a918fccf-4a94-4398-b260-4d792289952cadmin2011-06-28T11:55:28+02:00admin2014-02-03T11:00:04return airpreferredTechnical_Namesundefined domain120bdf01-4818-4a2c-bcea-4f875b6b129a13711976956060undefinedundefinedundefinedunprocessedundefinedadmin2011-06-28T11:55:28+02:00admin2014-02-03T11:00:04text nicht vorhandenproposedundefined domain680e0ea1-90f1-48ab-9ec9-5a362360692d13711976956220undefinedundefinedundefinedunprocessedundefinedadmin2011-06-28T12:11:20+02:00marco.aeschimann@ch.sauter-bc.com2011-07-05T10:54:28+02:00text nicht vorhandenproposedundefined domain01352af7-73e6-4024-9433-930846681b5613711976956300undefinedundefinedundefinedunprocessedundefinedadmin2011-06-28T12:11:19+02:00eric.schneider@ch.sauter-bc.com2011-09-13T10:47:25+02:00AbluftmengeproposedTechnical_Namesundefined domain44641d47-ddf3-4bb4-b1d4-a22a3fb42f6413711976956460undefinedundefinedundefinedunprocessedundefinedadmin2011-06-28T11:55:28+02:00admin2014-02-03T10:59:47débit d'air reprispreferredTechnical_Namesundefined domain5334a674-848b-44a3-8b42-1756d38717ef13711976956140undefinedundefinedundefinedunprocessedundefinedadmin2011-06-28T11:55:28+02:00admin2014-02-03T10:59:54débit d'évacuationdeprecatedTechnical_Namesundefined domain38e4ce12-4175-465e-a26f-4bb6d8a7ea1513711976956540undefinedundefinedundefinedunprocessedundefinedadmin2011-06-28T11:55:28+02:00admin2014-02-03T10:59:58text nicht vorhandenproposedundefined domain7958d666-8511-4c0e-aef1-d0f4748d2d4613711976956380undefinedundefinedundefinedunprocessedundefinedadmin2011-06-28T12:11:18+02:00admin2011-08-30T11:55:38+02:00 +``` + +### Searching Entry UUIDs and IDs by Domain + +You can retrieve all or only the entries (represented by their UUID and ID) of specific domains by using the +`searchEntries` service endpoint. This service works similar to the "search terms" service, but you can only specify a +list of domains as search criterion, for example: + +```json +{ + "criteria": { + "domains": ["Technical_Names", "Demo"] + } +} +``` + +- Passing a nonempty array will get you all entries that contain at least one term that is assigned to at least one of + the specified domains. +- Passing an empty array for domains will get you all entries. + +Example: + +```bash +curl -i -H "Content-Type: application/json; charset=UTF-8" -H "Accept: application/json" -H "Authorization: session ee7ac269aed25b4e" -X POST http://${serverHostName}:8031/iq/services/v7/rest/terminology/searchEntries -d '{"criteria":{"domains":["undefined domain", "Technical_Names"]}}' +``` + +```text +HTTP/1.1 200 OK +Content-Type: application/json +Date: Wed, 12 Mar 2014 16:34:52 GMT +Transfer-Encoding: chunked + +{ + "entries": [ + { + "uuid": "a918fccf-4a94-4398-b260-4d792289952c", + "id": "13" + }, + { + "uuid": "ee1c8221-5ac2-465a-bcb8-2f329ba0da8a", + "id": "1391421694240" + } + ], + "search": { + "criteria": { + "domains": [ + "undefined domain", + "Technical_Names" + ] + } + }, + "totalResultCount": 2 +} +``` + +The response is a JSON object with the following attributes: + +- `search` contains your search criteria +- `totalResultCount` is the total number of entries matching the criterion +- `entries`: an array of entries, each containing the attributes `id`, and `uuid`. Using the entry UUID or ID you can then + retrieve the entire entry via `GET` `/entries` (see above). + +### Creation and Update of Entries and Terms + +Entries and their terms can be created and updated by `POST`ing the respective ACTIF or SDL MultiTerm XML representation +to `/entries`. +Whether an existing entry is updated or a new entry created crucially depends on the entry UUID specified in the sent +data. +If the entry UUID references an existing entry in the database, all terms and fields of the entry will be replaced by +the sent data. +Specifically, if the sent entry data contains fewer terms than the existing entry in the database, those terms missing +from the sent entry data will be deleted. + +Otherwise, that is, no entry of the same UUID exists, a new entry will be created. + +Supported media types are: + +- `application/vnd.acrolinx.actif+xml`: ACTIF in XML +- `application/vnd.acrolinx.mtf+xml`: SDL MultiTerm XML + +Required privileges: + +- Terminology - Import terms (implies "Edit terms") +- Terminology - Change the status of a term + +Return codes: + +- For both creation and update, the return code is 201 (created) and the "Location" header gets the + URL of the inserted/updated entry. +- If the input data doesn't contain an entry that needs to be created or updated, you'll see a 204 (no content). +- If the input data contains more than one entry (which is allowed), all entries in the input data will be created or updated respectively. However, + the "Location" header will only contain the URL of one of them. + +Example (sending [example-entry.actif.xml](doc/example-entry.actif.xml)): + +```bash +curl -i -H "Accept: application/json" -H "Content-Type: application/vnd.acrolinx.actif+xml" -H "Authorization: session ee7ac269aed25b4e" -X POST http://${serverHostName}:8031/iq/services/v7/rest/terminology/entries -d "`cat doc/example-entry.actif.xml`" +``` + +```text +HTTP/1.1 100 Continue + +HTTP/1.1 201 Created +Content-Length: 0 +Date: Wed, 12 Mar 2014 16:34:52 GMT +Location: http://localhost:8031/iq/services/v7/rest/terminology/entries/a918fccf-4a94-4398-b260-4d792289952c +``` + +For this service call to succeed, the terminology database schemas +of the sent data and of the current database have to be compatible. +The terminology database schema is the definition of the field names and types, list items, etc. +In case of mismatches, the data is either inserted incompletely or might be rejected entirely with a 4xx error code. + +### Deployment of Terminology + +After terms and entries have been created or updated using the above method, they're not immediately available for +checking. +To make the new or updated terms available for checking, the terminology needs to be "deployed". Currently, triggering a +"deploy" of the terminology just causes all running language servers to reload their language configuration, which +includes the loading of the terminology. +Please note that a language becomes unavailable for checking for a certain amount of time up to several +minutes. Therefore terminology deployments should be scheduled for convenient times and not just done after each term +or entry update. + +You only need to (re)deploy terms/entries in domains and languages the language configuration uses for +checking. For instance, when you've updated only the Arabic translation of a term, and there's no language +server running for Arabic, a "deploy" isn’t necessary. + +Required privileges: + +- Resources - Reload server configuration + +To deploy the terminology, call `PUT` on `/deployTerminology`: + +```bash +curl -i -H "Authorization: session ee7ac269aed25b4e" -X PUT http://${serverHostName}:8031/iq/services/v7/rest/terminology/deployTerminology +``` + +```text +HTTP/1.1 204 No Content +Content-Length: 0 +Date: Wed, 12 Mar 2014 16:34:52 GMT +``` + +If the call is authorized, it always returns 204 (No Content). + +### Deletion of Entries + +Entire entries can be removed by calling `DELETE` on `/entries/{entryUUID}`. If an entry existed and could be deleted +successfully, the service returns 204 (No Content). Otherwise, if there’s no entry under the specified UUID, the +service returns 410 (Gone). + +Required Privilege + +- Terminology - Edit Terms + +Example: + +```bash +curl -i -H "Authorization: session ee7ac269aed25b4e" -X DELETE http://${serverHostName}:8031/iq/services/v7/rest/terminology/entries/a70b25cd-89a9-49c6-8548-87f846188b19 +``` + +```text +HTTP/1.1 410 Gone +Content-Length: 0 +Date: Wed, 12 Mar 2014 16:34:52 GMT +``` + +### Upload of Multimedia Files + +A multimedia object can be uploaded to the Core Platform specifying a unique file name. We recommend using a scheme +based on newly generated UUIDs plus a readable part and the file extension. If an existing filename is used, the old one +will be replaced. + +To transfer a media file to the Core Platform the term API service, call `POST` on `/media/{finaName}`. + +Supported media types are: + +- `image/*`: all images types, for example, `image/png`, `image/gif`, etc. +- `application/pdf` + +Required privileges: + +- Terminology - Import terms (implies "Edit terms") + +Return codes: + +- 201 (Created) in the case of success. The Location header contains the URL of the uploaded content. +- 404 (Not Found) if the filename contains a `/`. + +Example: + +```bash +curl -i -H "Authorization: session ee7ac269aed25b4e" -H "Content-Type: image/png" -X POST http://${serverHostName}:8031/iq/services/v7/rest/terminology/media/nav_bullet_red.png --data-binary "@nav_bullet_red.png" +``` + +```text +HTTP/1.1 201 Created +Content-Length: 0 +Date: Wed, 12 Mar 2014 16:34:52 GMT +Location: http://@rab.local:8031/uploadedImages/nav_bullet_red.png +``` + +### Download of Multimedia Files + +A multimedia object that has been uploaded through this API can be downloaded using the unique filename. To achieve +this, call `GET` on `/media/{filename}`. + +Required privileges: + +- Terminology - Export terms (implies "Read terms") + +Return codes: + +- In case of success, 200 (OK) and the response body contains the media file. +- 404 (Not Found) if the filename doesn't exist. + +Example: + +```bash +curl -i -H "Authorization: session ee7ac269aed25b4e" -H "Accept: image/png" -X GET http://${serverHostName}:8031/iq/services/v7/rest/terminology/media/nav_bullet_red.png +``` + +```text +HTTP/1.1 200 OK +Content-Type: image/png +Date: Wed, 12 Mar 2014 16:34:52 GMT +Transfer-Encoding: chunked +?PNG +IHDR ????tEXtSoftwareAdobe ImageReadyq?e<XIDATx?b??????? ħ?? ?9?x?#??(?bidA??v ?G] ?B??ӑ7q?? ?D?_?? ???0-'?,??͹IEND?B`? +``` diff --git a/term-api.md b/term-api.md deleted file mode 100644 index 374dfb54..00000000 --- a/term-api.md +++ /dev/null @@ -1,699 +0,0 @@ -# Acrolinx Terminology API v7 - -## Deprecation Note - -**Warning:** Communication using the SDL *MultiTerm XML* format is deprecated. -While it still works today, support can be removed at any time. - -## Preliminaries - -All service operations are demonstrated by a `curl` (cf. [curl man page](http://curl.haxx.se/docs/manpage.html)) command -line that can be executed against a real Acrolinx Core Platform installation, replacing any variable references -`${variable}` by the appropriate values. - -### Authorization - -Before invoking any Terminology API, the Acrolinx Integration must authorize and acquire a session. -The authorization itself isn’t part of the Terminology API, but the [Core Platform Core API](README.md#authentication). -API Requests without a valid session ID in the `Authorization` HTTP header field fail: - -```bash -curl -i -H "Accept: application/vnd.acrolinx.mtf+xml" -X GET http://${serverHostName}:8031/iq/services/v7/rest/terminology/entries/a918fccf-4a94-4398-b260-4d792289952c -``` - -```text -HTTP/1.1 403 Forbidden -Content-Type: application/json -Date: Wed, 12 Mar 2014 16:34:51 GMT -exception_message: Invalid session (no such session) -exception_type: com.acrolinx.services.faults.InvalidSessionFault -Transfer-Encoding: chunked - -{ - "message": "Invalid session (no such session)", - "errors": { - "exception_type": "com.acrolinx.services.faults.InvalidSessionFault", - "exception_message": "Invalid session (no such session)" - } -} -``` - -### Acquiring a Session - -Using the authentication token, the integration now needs to open a session, specifying the session-type (always -`TERMINOLOGY` for usage of the terminology API) and the signature of the integration (see section Signatures below). - -Example of a session request body: - -```json -{ - "sessionType": "TERMINOLOGY", - "clientSignature": "SW50ZWdyYXRpb25EZXZlbG9wbWVudERlbW9Pbmx5", - "clientInfo": { - "buildNumber": "unknown", - "clientHostname": "localhost", - "version": "0.1", - "name": "Terminology Test Client", - "clientHostApplication": "unknown", - "clientLoginName": "unknown" - } -} -``` - -To request a session, do a `POST` on `/iq/services/v3/rest/core/requestSession`: - -```bash -curl -i -H "Content-Type: application/json; charset=UTF-8" -H "authToken: ${authToken}" -H "connection: keep-alive" -X POST http://${serverHostName}:8031/iq/services/v3/rest/core/requestSession -d "{\"sessionType\":\"TERMINOLOGY\",\"clientSignature\":\"${clientSignature}\",\"clientInfo\":{\"name\":\"terminology-example\",\"version\":\"1\",\"buildNumber\":\"1\",\"clientLoginName\":\"unknown\",\"clientHostname\":\"${clientHostName}\",\"clientHostApplication\":\"unknown\"}}" -``` - -```text - HTTP/1.1 200 OK - Content-Type: text/plain - Date: Wed, 12 Mar 2014 16:34:51 GMT - Content-Length: 16 - - 56429c06fbd5da74 -``` - -The returned session token should be used in subsequent requests to the Terminology API. It’s valid until -the session is released by the integration or by the Core Platform. -As the license limits the number of concurrently opened sessions, -an integration mustn’t forget to release a session before acquiring a new session token. - -### Releasing a Session - -A session can be released by a `DELETE` on `/iq/services/v3/rest/core/releaseSession`, providing the session as path -parameter: - -```bash -curl -i -X DELETE http://${serverHostName}:8031/iq/services/v3/rest/core/releaseSession/${session2} -``` - -```text -HTTP/1.1 204 No Content -Content-Length: 0 -Date: Wed, 12 Mar 2014 16:34:51 GMT -``` - -#### Signatures - -An integration must identify itself to the Core Platform by means of a unique signature. This signature tells the Core -Platform which integration is trying to communicate to it. Depending on the signature the communication might be allowed. -Signatures can be enabled individually in the Core Platform's license. To request a session with the Core Platform, an integration's -signature is one of the required parameters. If the signature is unknown to the Core Platform, -no session can be opened and further communication isn’t possible. - -Acrolinx issues specific signatures to integrators. - -## Terminology Service Methods - -The prefix to all v7 terminology API service paths is `http://${serverHostName}:8031/iq/services/v7/rest/terminology`. - -Required privileges: - -- for all terminology service API methods, the user must have at least the `Access API-based terminology applications` - privilege - -### Configuration - -Before invoking one of the Terminology API services for the result format SDL MultiTerm, the Core Platform must be -configured correctly. This includes that there are XSL transformations from ACTIF to SDL MultiTerm XML and SDL MultiTerm -Definition XDT. The needed XSL style sheets will be available as part of the Core Platform resources. - -The availability of those resources can be checked in the Acrolinx Dashboard on -`Terminology -> Import and Export -> Import/Export -> Custom File Format`. - -### Media/Content Types - -Except for application-specific XML data (ACTIF resp. SDL MultiTerm XML/XDT data), request, and response data is usually -either plain text or in JSON format. The encoding is usually assumed to be UTF-8. - -With some service methods, you can control the format of the return values by means of the standard HTTP `Accept` header. - -Service methods that accept application-specific body data rely on the correct setting of the standard HTTP -`Content-Type` header. - -The supported media types are listed where applicable. - -### Getting Existing Entries by UUID or ID - -Supported media types: - -- `application/vnd.acrolinx.actif+xml`: return entries as ACTIF in XML -- `application/vnd.acrolinx.mtf+xml`: return entries as SDL MultiTerm XML - -Required privilege: - -- Terminology - View Terms - -This functionality is provided by `GET` `/entries`. There are two variants of this operation: - -- asking for a single UUID or ID -- asking for many UUIDs or IDs - -For asking for only one entry simply, append its UUID to the service URI: - -```bash -curl -i -H "Accept: application/vnd.acrolinx.mtf+xml" -H "Authorization: session ee7ac269aed25b4e" -X GET http://${serverHostName}:8031/iq/services/v7/rest/terminology/entries/a918fccf-4a94-4398-b260-4d792289952c -``` - -```text -HTTP/1.1 200 OK -Content-Type: application/vnd.acrolinx.mtf+xml -Date: Wed, 12 Mar 2014 16:34:51 GMT -Content-Length: 8521 - -13a918fccf-4a94-4398-b260-4d792289952cadmin2011-06-28T11:55:28+02:00admin2014-02-03T11:00:04return airpreferredTechnical_Namesundefined domain120bdf01-4818-4a2c-bcea-4f875b6b129a13711976956060undefinedundefinedundefinedunprocessedundefinedadmin2011-06-28T11:55:28+02:00admin2014-02-03T11:00:04text nicht vorhandenproposedundefined domain680e0ea1-90f1-48ab-9ec9-5a362360692d13711976956220undefinedundefinedundefinedunprocessedundefinedadmin2011-06-28T12:11:20+02:00marco.aeschimann@ch.sauter-bc.com2011-07-05T10:54:28+02:00text nicht vorhandenproposedundefined domain01352af7-73e6-4024-9433-930846681b5613711976956300undefinedundefinedundefinedunprocessedundefinedadmin2011-06-28T12:11:19+02:00eric.schneider@ch.sauter-bc.com2011-09-13T10:47:25+02:00AbluftmengeproposedTechnical_Namesundefined domain44641d47-ddf3-4bb4-b1d4-a22a3fb42f6413711976956460undefinedundefinedundefinedunprocessedundefinedadmin2011-06-28T11:55:28+02:00admin2014-02-03T10:59:47débit d'air reprispreferredTechnical_Namesundefined domain5334a674-848b-44a3-8b42-1756d38717ef13711976956140undefinedundefinedundefinedunprocessedundefinedadmin2011-06-28T11:55:28+02:00admin2014-02-03T10:59:54débit d'évacuationdeprecatedTechnical_Namesundefined domain38e4ce12-4175-465e-a26f-4bb6d8a7ea1513711976956540undefinedundefinedundefinedunprocessedundefinedadmin2011-06-28T11:55:28+02:00admin2014-02-03T10:59:58text nicht vorhandenproposedundefined domain7958d666-8511-4c0e-aef1-d0f4748d2d4613711976956380undefinedundefinedundefinedunprocessedundefinedadmin2011-06-28T12:11:18+02:00admin2011-08-30T11:55:38+02:00 -``` - -This works the same way for entry IDs (the server determines by the format of the passed ID string whether it’s a UUID or -an ID): - -```bash -curl -i -H "Accept: application/vnd.acrolinx.mtf+xml" -H "Authorization: session ee7ac269aed25b4e" -X GET http://${serverHostName}:8031/iq/services/v7/rest/terminology/entries/13 -``` - -```text -HTTP/1.1 200 OK -Content-Type: application/vnd.acrolinx.mtf+xml -Date: Wed, 12 Mar 2014 16:34:51 GMT -Content-Length: 8521 - -13a918fccf-4a94-4398-b260-4d792289952cadmin2011-06-28T11:55:28+02:00admin2014-02-03T11:00:04return airpreferredTechnical_Namesundefined domain120bdf01-4818-4a2c-bcea-4f875b6b129a13711976956060undefinedundefinedundefinedunprocessedundefinedadmin2011-06-28T11:55:28+02:00admin2014-02-03T11:00:04text nicht vorhandenproposedundefined domain680e0ea1-90f1-48ab-9ec9-5a362360692d13711976956220undefinedundefinedundefinedunprocessedundefinedadmin2011-06-28T12:11:20+02:00marco.aeschimann@ch.sauter-bc.com2011-07-05T10:54:28+02:00text nicht vorhandenproposedundefined domain01352af7-73e6-4024-9433-930846681b5613711976956300undefinedundefinedundefinedunprocessedundefinedadmin2011-06-28T12:11:19+02:00eric.schneider@ch.sauter-bc.com2011-09-13T10:47:25+02:00AbluftmengeproposedTechnical_Namesundefined domain44641d47-ddf3-4bb4-b1d4-a22a3fb42f6413711976956460undefinedundefinedundefinedunprocessedundefinedadmin2011-06-28T11:55:28+02:00admin2014-02-03T10:59:47débit d'air reprispreferredTechnical_Namesundefined domain5334a674-848b-44a3-8b42-1756d38717ef13711976956140undefinedundefinedundefinedunprocessedundefinedadmin2011-06-28T11:55:28+02:00admin2014-02-03T10:59:54débit d'évacuationdeprecatedTechnical_Namesundefined domain38e4ce12-4175-465e-a26f-4bb6d8a7ea1513711976956540undefinedundefinedundefinedunprocessedundefinedadmin2011-06-28T11:55:28+02:00admin2014-02-03T10:59:58text nicht vorhandenproposedundefined domain7958d666-8511-4c0e-aef1-d0f4748d2d4613711976956380undefinedundefinedundefinedunprocessedundefinedadmin2011-06-28T12:11:18+02:00admin2011-08-30T11:55:38+02:00 -``` - -For the more general case, to ask for many entries at the same time specify the UUIDs (or IDs) as a comma-separated list -after the `/entries/` endpoint URL: - -```bash -curl -i -H "Accept: application/vnd.acrolinx.mtf+xml" -H "Authorization: session ee7ac269aed25b4e" -H "Content-Type: application/json" -X GET http://${serverHostName}:8031/iq/services/v7/rest/terminology/entries/a918fccf-4a94-4398-b260-4d792289952c,ee1c8221-5ac2-465a-bcb8-2f329ba0da8a -``` - -```text -HTTP/1.1 200 OK -Content-Type: application/vnd.acrolinx.mtf+xml -Date: Wed, 12 Mar 2014 16:34:51 GMT -Content-Length: 11081 - -1391421694240ee1c8221-5ac2-465a-bcb8-2f329ba0da8aadmin2014-02-03T11:01:34admin2014-02-03T11:01:36neuer TermpreferredTechnical_Names79425649-0a70-458a-8cf8-910539b9a1f313911896143950undefinedundefinedundefinedunprocessedundefinedadmin2014-02-03T11:01:34admin2014-02-03T11:01:36new termproposedTechnical_Names06208308-e8ca-4dbd-91fd-add7ca4f5e9013911896145610undefinedundefinedundefinedunprocessedundefinedadmin2014-02-03T11:01:51admin2014-02-03T11:01:5113a918fccf-4a94-4398-b260-4d792289952cadmin2011-06-28T11:55:28+02:00admin2014-02-03T11:00:04return airpreferredTechnical_Namesundefined domain120bdf01-4818-4a2c-bcea-4f875b6b129a13711976956060undefinedundefinedundefinedunprocessedundefinedadmin2011-06-28T11:55:28+02:00admin2014-02-03T11:00:04text nicht vorhandenproposedundefined domain680e0ea1-90f1-48ab-9ec9-5a362360692d13711976956220undefinedundefinedundefinedunprocessedundefinedadmin2011-06-28T12:11:20+02:00marco.aeschimann@ch.sauter-bc.com2011-07-05T10:54:28+02:00text nicht vorhandenproposedundefined domain01352af7-73e6-4024-9433-930846681b5613711976956300undefinedundefinedundefinedunprocessedundefinedadmin2011-06-28T12:11:19+02:00eric.schneider@ch.sauter-bc.com2011-09-13T10:47:25+02:00AbluftmengeproposedTechnical_Namesundefined domain44641d47-ddf3-4bb4-b1d4-a22a3fb42f6413711976956460undefinedundefinedundefinedunprocessedundefinedadmin2011-06-28T11:55:28+02:00admin2014-02-03T10:59:47débit d'air reprispreferredTechnical_Namesundefined domain5334a674-848b-44a3-8b42-1756d38717ef13711976956140undefinedundefinedundefinedunprocessedundefinedadmin2011-06-28T11:55:28+02:00admin2014-02-03T10:59:54débit d'évacuationdeprecatedTechnical_Namesundefined domain38e4ce12-4175-465e-a26f-4bb6d8a7ea1513711976956540undefinedundefinedundefinedunprocessedundefinedadmin2011-06-28T11:55:28+02:00admin2014-02-03T10:59:58text nicht vorhandenproposedundefined domain7958d666-8511-4c0e-aef1-d0f4748d2d4613711976956380undefinedundefinedundefinedunprocessedundefinedadmin2011-06-28T12:11:18+02:00admin2011-08-30T11:55:38+02:00 -``` - -**Note: The length of the request URL is limited by any HTTP server implementation. Based to our tests, we don't -recommend exceeding the value of 4000 characters.** - -### Querying the Term Base Structure - -Supported media types: - -- `application/vnd.acrolinx.actif+xml`: return schema as ACTIF in XML -- `application/vnd.acrolinx.mtf+xdt`: return entries as SDL MultiTerm XDT - -Required privilege: - -- Terminology - View Terms - -This functionality is provided by GET `/schema`. The structure of the Acrolinx term base can then be retrieved as -follows (in the example the SDL MultiTerm XDT representation is requested): - -```bash -curl -i -H "Accept: application/vnd.acrolinx.mtf+xdt" -H "Authorization: session ee7ac269aed25b4e" -X GET http://${serverHostName}:8031/iq/services/v7/rest/terminology/schema -``` - -```text -HTTP/1.1 200 OK -Content-Type: application/vnd.acrolinx.mtf+xdt -Date: Wed, 12 Mar 2014 16:34:52 GMT -Content-Length: 21990 - -Entry level0110ENTRY_UUID1001sourceOfDefinition1000definition1000Project ID1000imageURL1000Index level2110Term level3110Status1100domain1110MORPHOSYNTACTIC_RESTRICTION1001TERM_UUID1001TERM_ID1000VARIANTS_CONFIGURATIONS1001HISTORY_EVENT1001assignedTo1000project1000termType1000externalCrossReference1000processStatus1000geographicalUsage1000crossReference1000Number1000sourceOfTerm1000Usage note1000customer1000Unit1000Part of Speech1000gender1000Core1000Phrase1000note space1000context1000ARArabicfalseBGBulgarianfalseCSCzechfalseDEGermanfalseENEnglishfalseEN-GBEnglish (UK)falseEN-USEnglish (USA)falseESSpanishfalseFRFrenchfalseITItalianfalseJAJapanesefalseKOKoreanfalseNLDutchfalseNONorwegianfalsePTPortuguesefalseRURussianfalseSVSwedishfalseZHChinesefalseZH-CNChinese (PRC)falseZH-TWChinese (Taiwan)falseENTRY_UUIDTextFsourceOfDefinitionTextFdefinitionTextFProject IDTextFimageURLMultimedia FileFStatusPicklistproposedproposed_from_searchdeprecatedadmittedpreferrednon-termstopwordno-single-termFdomainPicklistundefined domaincustomerSpecial SymbolsDemoSwitchesKeitaidenwaKanaKanjiUsageADSLMFPDruckerAcrolinxStandard_TerminologyRoutersBelkinD-LinkCiscoPhoneASD-STE100Technical_NamesTN_1_Official_Parts_InformationTN_2_Locations_On_Machines_Vehicles_Or_EquipmentTN_3_Tools_Or_EquipmentTN_4_Materials_Consumables_Or_Unwanted_MatterTN_5_Facilities_And_InfrastructureTN_6_Circuits_Or_SystemsTN_7_Mathematical_Scientific_Or_Engineering_TermsTN_8_NavigationTN_9_Numbers_Units_Of_Measurement_Or_Dial_MarkingsTN_10_Quoted_TextTN_11_Persons_Groups_Or_BodiesTN_12_Body_PartsTN_13_Common_Personal_EffectsTN_14_Medical_TermsTN_15_Documents_Or_ManualsTN_16_Names_Headings_And_Topics_In_SpecificationsTN_17_Technical_Records_Standards_Specifications_Or_RegulationsTN_18_Environmental_ConditionsTN_19_ColorsTN_20_Damage_TermsTN_UnclassifiedTechnical_VerbsTV_1_Manufacturing_ProcessesTV_2_Computer_Processes_And_ApplicationsTV_3_DescriptionsTV_UnclassifiedS1000D Bike Data SetFMORPHOSYNTACTIC_RESTRICTIONPicklistallnounverbadjectiveadverbadpositionprepositiondeterminerconjunctionpronounprefixsuffixFTERM_UUIDTextFTERM_IDTextFVARIANTS_CONFIGURATIONSTextFHISTORY_EVENTTextFassignedToTextFprojectTextFtermTypePicklisttrademarkundefinedfull formacronymabbreviationshort formvariantphraseFexternalCrossReferenceTextFprocessStatusPicklistunprocessedprovisionally processedfinalizedreview requestedFgeographicalUsageTextFcrossReferenceTextFNumberTextFsourceOfTermTextFUsage noteTextFcustomerTextFUnitTextFPart of SpeechPicklistadjectiveadverbnounotherproper nounundefinedverbFgenderPicklistundefinedmasculinefeminineneuterotherFCorePicklistundefinedcoreFPhraseTextFnote spaceTextFcontextTextF10Exported from Acrolinx at 2014-03-12 17:34:52 -``` - -### Querying for Available Filters - -The only supported media type is `application/json`. - -Required privilege: - -- Terminology - View Terms - -The terminology service API offers an operation to get the ids/names of all filters for term search operations, that are -available to the user in the current session. The available filters can be retrieved by `GET` to `/filters`: - -```bash -curl -i -H "Accept: application/json" -H "Authorization: session ee7ac269aed25b4e" -X GET http://${serverHostName}:8031/iq/services/v7/rest/terminology/filters -``` - -```text -HTTP/1.1 200 OK -Content-Type: application/json -Date: Wed, 12 Mar 2014 16:34:52 GMT -Transfer-Encoding: chunked - -{ - "user": "admin", - "filters": [ - { - "id": "Preferred Technical Names" - }, - { - "id": "SEO" - }, - { - "id": "Images" - } -] -} -``` - -The filters can be referenced by their `id` in a search API operation, described in the next section. - -### Searching Terms - -Terms can be searched by: - -- term `name`, supporting '%' as wildcard; -- `language` id -- `domains` an array of one or several domain names -- `filter` id -- or any combination of the above - -The individual fields of the search criteria need to be "escaped" by their unicode positions in case they contain -characters that would otherwise break the JSON request string. For example, the apostrophe/single quote character `'` is -escaped as `\u0027`. - -The search API supports pagination to retrieve only a certain subset of the result set. The parameters are: - -- `offset`, the index of the first term to display (starting from 0, where the terms are always sorted ascending by - their name) -- `limit`, the maximal number of terms to return, starting from `offset`; if < 1, no limit is imposed - -The only supported media type for request as well as result is `application/json`. - -Required privilege: - -- Terminology - View Terms - -The search-terms service function requires a request object in the format illustrated by the following example: - -```json -{ - "criteria": { - "name": "d\\u00e9bit%", - "language": "fr", - "domains": ["Technical Names", "Demo"], - "filter": "Preferred Technical Names" - }, - "pagination": { - "offset": 0, - "limit": -1 - } -} -``` - -The `criteria` and `pagination` values are mandatory, as well as `offset` and `limit`, but you can leave out (or set to -`null`) those fields of `criteria` that aren’t required by a specific query (for `domains` you can also pass an empty -array `[]`). - -The criteria that exist in the search request are then combined by AND (if `domains` contains more than one value, they’re - combined into a domain filter by OR-ing them) in the resulting filter. - -You can then search with those settings by submitting a `POST`-request to `/searchTerms`: - -```bash -curl -i -H "Content-Type: application/json; charset=UTF-8" -H "Accept: application/json" -H "Authorization: session ee7ac269aed25b4e" -X POST http://${serverHostName}:8031/iq/services/v7/rest/terminology/searchTerms -d '{"criteria":{"name":"d%","language": "fr","domains":["undefined domain", "Technical Names"], "filter":null},"pagination":{"offset": 0,"limit": -1}}' -``` - -```text -HTTP/1.1 200 OK -Content-Type: application/json -Date: Wed, 12 Mar 2014 16:34:52 GMT -Transfer-Encoding: chunked - -{ - "terms": [ - { - "name": "débit d\u0027air repris", - "status": "preferred", - "domains": [ - "Technical_Names", - "undefined domain" - ], - "uuid": "5334a674-848b-44a3-8b42-1756d38717ef", - "entry": { - "uuid": "a918fccf-4a94-4398-b260-4d792289952c", - "id": "13" - } - }, - { - "name": "débit d\u0027évacuation", - "status": "deprecated", - "domains": [ - "Technical_Names", - "undefined domain" - ], - "uuid": "38e4ce12-4175-465e-a26f-4bb6d8a7ea15", - "entry": { - "uuid": "a918fccf-4a94-4398-b260-4d792289952c", - "id": "13" - } - } - ], - "search": { - "pagination": { - "offset": 0, - "limit": -1 - }, - "criteria": { - "name": "d%", - "language": "fr", - "filter": null, - "domains": [ - "undefined domain", - "Technical Names" - ] - } - }, - "totalResultCount": 2 -} -``` - -(Note: there exists indeed a domain name `undefined domain` in the Core Platform default setup; -that value doesn't indicate the absence of a value for the domain.) - -The response is a JSON object with the following attributes: - -- `search` contains your search criteria and pagination settings; you could reuse that object for subsequent calls with - the same criteria -- `totalResultCount` is the total number of hits for the search, before applying the pagination limit -- `terms`: an array of term objects, each containing the attributes `name`, `status`, `domains`, `uuid` (the UUID of the - term: use that UUID to identify the specific term data from the full entry that you retrieve by the entry UUID), - `entry`; `entry` again is an object with two attributes `uuid` and `id`, the UUID, and ID of the entry. Using the entry - UUID or ID you can then retrieve the entire entry via `GET` `/entries` (see above). - -If there are no matching terms (or you request an offset greater than the result count), `terms` will be an empty array. -If your search request refers to a nonexistent filter, the server will respond with a 400 (Bad Request). - -### Getting Terms with Search Criteria - -You can also search for terms using an older method called `findTerms`, which supports some search criteria that -aren’t available in the `searchTerms` method above, and which also returns the result in a specified target format, -just like `get entries` described above. - -The following search criteria are supported: - -- term `surface` (name), supporting '%' as wildcard -- `language` id -- `domain` - a single domain name -- `entry ID/UUID` - an array of entry IDs or entry UUIDs -- custom criteria - an array of `field=value` strings, where `field` is one of the following ACTIF field names: - + `term/id` - + `term/uuid` - + `entry/id` - + `enty/uuid` - + `term/creation-date-time` (prepend with `<` or `>` to find terms created before or after the given date) - + `term/last-modification-date-time` (prepend with `<` or `>` to find terms modified before or after the given date) - + `term/creator-user-name` - + `term/last-modifier` - + any custom field name (as it appears in ACTIF) - -The individual fields of the search criteria need to be "escaped" by their unicode positions in case they contain -characters that would otherwise break the JSON request string. For example, the apostrophe/single quote character `'` is -escaped as `\u0027`. - -All criteria are combined with `AND` when the term filter is constructed. All criteria are optional; if you don’t give -any criteria, the result includes all terms. - -The desired result format needs to be specified in the required `format` attribute of the request object (not in the -`Accept` HTTP header). The supported media types are the same as for the "get entries" method above: - -- `application/vnd.acrolinx.actif+xml`: return terms as ACTIF in XML -- `application/vnd.acrolinx.mtf+xml`: return terms as SDL MultiTerm XML - -Finally, you can optionally have the term base structure (schema) included in the response by setting the `withSchema` -attribute to `true`. - -Required privilege: - -- Terminology - View Terms - -The find-terms service function requires a request object in the format illustrated by the following example: - -```json -{ - "surface": "d\\u00e9bit%", - "language": "fr", - "domain": ["Demo"], - "customCriteria": [ - "term/creation-date-time=<2012-05-10T11:41:00", - "customWorkflowStatus=reviewed" - ], - "withSchema": false, - "format": "application/vnd.acrolinx.mtf+xml" -} -``` - -You can then search with those settings by `POST`ing the request to `/findTerms/`. (Note that the terminology -session is part of the URL here; the `Authorization` header is ignored.) - -```bash -curl -i -H \"Content-Type: application/json; charset=UTF-8\" -X POST http://${serverHostName}:8031/iq/services/v7/rest/terminology/findTerms/ee7ac269aed25b4e -d '{"name":"d%","language": "fr","customCriteria":["term/uuid=a918fccf-4a94-4398-b260-4d792289952c"], "format":"application/vnd.acrolinx.mtf+xml"}' -``` - -```text -HTTP/1.1 200 OK -Content-Type: application/vnd.acrolinx.mtf+xml -Date: Wed, 12 Mar 2014 16:34:51 GMT -Content-Length: 8521 - -13a918fccf-4a94-4398-b260-4d792289952cadmin2011-06-28T11:55:28+02:00admin2014-02-03T11:00:04return airpreferredTechnical_Namesundefined domain120bdf01-4818-4a2c-bcea-4f875b6b129a13711976956060undefinedundefinedundefinedunprocessedundefinedadmin2011-06-28T11:55:28+02:00admin2014-02-03T11:00:04text nicht vorhandenproposedundefined domain680e0ea1-90f1-48ab-9ec9-5a362360692d13711976956220undefinedundefinedundefinedunprocessedundefinedadmin2011-06-28T12:11:20+02:00marco.aeschimann@ch.sauter-bc.com2011-07-05T10:54:28+02:00text nicht vorhandenproposedundefined domain01352af7-73e6-4024-9433-930846681b5613711976956300undefinedundefinedundefinedunprocessedundefinedadmin2011-06-28T12:11:19+02:00eric.schneider@ch.sauter-bc.com2011-09-13T10:47:25+02:00AbluftmengeproposedTechnical_Namesundefined domain44641d47-ddf3-4bb4-b1d4-a22a3fb42f6413711976956460undefinedundefinedundefinedunprocessedundefinedadmin2011-06-28T11:55:28+02:00admin2014-02-03T10:59:47débit d'air reprispreferredTechnical_Namesundefined domain5334a674-848b-44a3-8b42-1756d38717ef13711976956140undefinedundefinedundefinedunprocessedundefinedadmin2011-06-28T11:55:28+02:00admin2014-02-03T10:59:54débit d'évacuationdeprecatedTechnical_Namesundefined domain38e4ce12-4175-465e-a26f-4bb6d8a7ea1513711976956540undefinedundefinedundefinedunprocessedundefinedadmin2011-06-28T11:55:28+02:00admin2014-02-03T10:59:58text nicht vorhandenproposedundefined domain7958d666-8511-4c0e-aef1-d0f4748d2d4613711976956380undefinedundefinedundefinedunprocessedundefinedadmin2011-06-28T12:11:18+02:00admin2011-08-30T11:55:38+02:00 -``` - -### Searching Entry UUIDs and IDs by Domain - -You can retrieve all or only the entries (represented by their UUID and ID) of specific domains by using the -`searchEntries` service endpoint. This service works similar to the "search terms" service, but you can only specify a -list of domains as search criterion, for example: - -```json -{ - "criteria": { - "domains": ["Technical_Names", "Demo"] - } -} -``` - -- Passing a nonempty array will get you all entries that contain at least one term that is assigned to at least one of - the specified domains. -- Passing an empty array for domains will get you all entries. - -Example: - -```bash -curl -i -H "Content-Type: application/json; charset=UTF-8" -H "Accept: application/json" -H "Authorization: session ee7ac269aed25b4e" -X POST http://${serverHostName}:8031/iq/services/v7/rest/terminology/searchEntries -d '{"criteria":{"domains":["undefined domain", "Technical_Names"]}}' -``` - -```text -HTTP/1.1 200 OK -Content-Type: application/json -Date: Wed, 12 Mar 2014 16:34:52 GMT -Transfer-Encoding: chunked - -{ - "entries": [ - { - "uuid": "a918fccf-4a94-4398-b260-4d792289952c", - "id": "13" - }, - { - "uuid": "ee1c8221-5ac2-465a-bcb8-2f329ba0da8a", - "id": "1391421694240" - } - ], - "search": { - "criteria": { - "domains": [ - "undefined domain", - "Technical_Names" - ] - } - }, - "totalResultCount": 2 -} -``` - -The response is a JSON object with the following attributes: - -- `search` contains your search criteria -- `totalResultCount` is the total number of entries matching the criterion -- `entries`: an array of entries, each containing the attributes `id`, and `uuid`. Using the entry UUID or ID you can then - retrieve the entire entry via `GET` `/entries` (see above). - -### Creation and Update of Entries and Terms - -Entries and their terms can be created and updated by `POST`ing the respective ACTIF or SDL MultiTerm XML representation -to `/entries`. -Whether an existing entry is updated or a new entry created crucially depends on the entry UUID specified in the sent -data. -If the entry UUID references an existing entry in the database, all terms and fields of the entry will be replaced by -the sent data. -Specifically, if the sent entry data contains fewer terms than the existing entry in the database, those terms missing -from the sent entry data will be deleted. - -Otherwise, that is, no entry of the same UUID exists, a new entry will be created. - -Supported media types are: - -- `application/vnd.acrolinx.actif+xml`: ACTIF in XML -- `application/vnd.acrolinx.mtf+xml`: SDL MultiTerm XML - -Required privileges: - -- Terminology - Import terms (implies "Edit terms") -- Terminology - Change the status of a term - -Return codes: - -- For both creation and update, the return code is 201 (created) and the "Location" header gets the - URL of the inserted/updated entry. -- If the input data doesn't contain an entry that needs to be created or updated, you'll see a 204 (no content). -- If the input data contains more than one entry (which is allowed), all entries in the input data will be created or updated respectively. However, - the "Location" header will only contain the URL of one of them. - -Example (sending [example-entry.actif.xml](doc/example-entry.actif.xml)): - -```bash -curl -i -H "Accept: application/json" -H "Content-Type: application/vnd.acrolinx.actif+xml" -H "Authorization: session ee7ac269aed25b4e" -X POST http://${serverHostName}:8031/iq/services/v7/rest/terminology/entries -d "`cat doc/example-entry.actif.xml`" -``` - -```text -HTTP/1.1 100 Continue - -HTTP/1.1 201 Created -Content-Length: 0 -Date: Wed, 12 Mar 2014 16:34:52 GMT -Location: http://localhost:8031/iq/services/v7/rest/terminology/entries/a918fccf-4a94-4398-b260-4d792289952c -``` - -For this service call to succeed, the terminology database schemas -of the sent data and of the current database have to be compatible. -The terminology database schema is the definition of the field names and types, list items, etc. -In case of mismatches, the data is either inserted incompletely or might be rejected entirely with a 4xx error code. - -### Deployment of Terminology - -After terms and entries have been created or updated using the above method, they're not immediately available for -checking. -To make the new or updated terms available for checking, the terminology needs to be "deployed". Currently, triggering a -"deploy" of the terminology just causes all running language servers to reload their language configuration, which -includes the loading of the terminology. -Please note that a language becomes unavailable for checking for a certain amount of time up to several -minutes. Therefore terminology deployments should be scheduled for convenient times and not just done after each term -or entry update. - -You only need to (re)deploy terms/entries in domains and languages the language configuration uses for -checking. For instance, when you've updated only the Arabic translation of a term, and there's no language -server running for Arabic, a "deploy" isn’t necessary. - -Required privileges: - -- Resources - Reload server configuration - -To deploy the terminology, call `PUT` on `/deployTerminology`: - -```bash -curl -i -H "Authorization: session ee7ac269aed25b4e" -X PUT http://${serverHostName}:8031/iq/services/v7/rest/terminology/deployTerminology -``` - -```text -HTTP/1.1 204 No Content -Content-Length: 0 -Date: Wed, 12 Mar 2014 16:34:52 GMT -``` - -If the call is authorized, it always returns 204 (No Content). - -### Deletion of Entries - -Entire entries can be removed by calling `DELETE` on `/entries/{entryUUID}`. If an entry existed and could be deleted -successfully, the service returns 204 (No Content). Otherwise, if there’s no entry under the specified UUID, the -service returns 410 (Gone). - -Required Privilege - -- Terminology - Edit Terms - -Example: - -```bash -curl -i -H "Authorization: session ee7ac269aed25b4e" -X DELETE http://${serverHostName}:8031/iq/services/v7/rest/terminology/entries/a70b25cd-89a9-49c6-8548-87f846188b19 -``` - -```text -HTTP/1.1 410 Gone -Content-Length: 0 -Date: Wed, 12 Mar 2014 16:34:52 GMT -``` - -### Upload of Multimedia Files - -A multimedia object can be uploaded to the Core Platform specifying a unique file name. We recommend using a scheme -based on newly generated UUIDs plus a readable part and the file extension. If an existing filename is used, the old one -will be replaced. - -To transfer a media file to the Core Platform the term API service, call `POST` on `/media/{finaName}`. - -Supported media types are: - -- `image/*`: all images types, for example, `image/png`, `image/gif`, etc. -- `application/pdf` - -Required privileges: - -- Terminology - Import terms (implies "Edit terms") - -Return codes: - -- 201 (Created) in the case of success. The Location header contains the URL of the uploaded content. -- 404 (Not Found) if the filename contains a `/`. - -Example: - -```bash -curl -i -H "Authorization: session ee7ac269aed25b4e" -H "Content-Type: image/png" -X POST http://${serverHostName}:8031/iq/services/v7/rest/terminology/media/nav_bullet_red.png --data-binary "@nav_bullet_red.png" -``` - -```text -HTTP/1.1 201 Created -Content-Length: 0 -Date: Wed, 12 Mar 2014 16:34:52 GMT -Location: http://@rab.local:8031/uploadedImages/nav_bullet_red.png -``` - -### Download of Multimedia Files - -A multimedia object that has been uploaded through this API can be downloaded using the unique filename. To achieve -this, call `GET` on `/media/{filename}`. - -Required privileges: - -- Terminology - Export terms (implies "Read terms") - -Return codes: - -- In case of success, 200 (OK) and the response body contains the media file. -- 404 (Not Found) if the filename doesn't exist. - -Example: - -```bash -curl -i -H "Authorization: session ee7ac269aed25b4e" -H "Accept: image/png" -X GET http://${serverHostName}:8031/iq/services/v7/rest/terminology/media/nav_bullet_red.png -``` - -```text -HTTP/1.1 200 OK -Content-Type: image/png -Date: Wed, 12 Mar 2014 16:34:52 GMT -Transfer-Encoding: chunked -?PNG -IHDR ????tEXtSoftwareAdobe ImageReadyq?e<XIDATx?b??????? ħ?? ?9?x?#??(?bidA??v ?G] ?B??ӑ7q?? ?D?_?? ???0-'?,??͹IEND?B`? -``` From f47be23526420224563b2fa255489ef9b2814b94 Mon Sep 17 00:00:00 2001 From: Robert Barbey Date: Mon, 10 Mar 2025 15:39:47 +0100 Subject: [PATCH 02/18] docs: rearranged intro to Term API --- apiary.apib | 169 +++++++++++++++++++++++----------------------------- 1 file changed, 74 insertions(+), 95 deletions(-) diff --git a/apiary.apib b/apiary.apib index 823319cf..62179762 100644 --- a/apiary.apib +++ b/apiary.apib @@ -7781,140 +7781,119 @@ This will download data only with the fields `checkId`, `date`, `guidelineId` an ## Deprecation Note -**Warning:** Communication using the SDL *MultiTerm XML* format is deprecated. -While it still works today, support can be removed at any time. +**Warning:** Communication using the SDL *MultiTerm XML* format is +deprecated. While it still works today, support can be removed at any +time. -## Preliminaries +## Configuration -All service operations are demonstrated by a `curl` (cf. [curl man page](http://curl.haxx.se/docs/manpage.html)) command -line that can be executed against a real Acrolinx Core Platform installation, replacing any variable references -`${variable}` by the appropriate values. +Before invoking one of the Terminology API services for the SDL +MultiTerm result format, the Core Platform must be configured +correctly. This includes that there are XSL transformations from ACTIF +format to SDL MultiTerm XML and SDL MultiTerm Definition XDT. The +needed XSL style sheets will be available as part of the Core Platform +resources. -### Authorization +The availability of those resources can be checked in the Acrolinx +dashboard on `Style -> Term import and Export -> Custom File Format`. -Before invoking any Terminology API, the Acrolinx Integration must authorize and acquire a session. -The authorization itself isn’t part of the Terminology API, but the [Core Platform Core API](README.md#authentication). -API Requests without a valid session ID in the `Authorization` HTTP header field fail: +## Media/Content Types -```bash -curl -i -H "Accept: application/vnd.acrolinx.mtf+xml" -X GET http://${serverHostName}:8031/iq/services/v7/rest/terminology/entries/a918fccf-4a94-4398-b260-4d792289952c -``` +Except for application-specific XML data (ACTIF resp. SDL MultiTerm +XML/XDT data), request, and response data is usually either plain text +or in JSON format. The encoding is usually assumed to be UTF-8. -```text -HTTP/1.1 403 Forbidden -Content-Type: application/json -Date: Wed, 12 Mar 2014 16:34:51 GMT -exception_message: Invalid session (no such session) -exception_type: com.acrolinx.services.faults.InvalidSessionFault -Transfer-Encoding: chunked +With some service methods, you can control the format of the return +values by means of the standard HTTP `Accept` header. -{ - "message": "Invalid session (no such session)", - "errors": { - "exception_type": "com.acrolinx.services.faults.InvalidSessionFault", - "exception_message": "Invalid session (no such session)" - } -} -``` +Service methods that accept application-specific body data rely on the +correct setting of the standard HTTP `Content-Type` header. -### Acquiring a Session +The supported media types are listed where applicable. -Using the authentication token, the integration now needs to open a session, specifying the session-type (always -`TERMINOLOGY` for usage of the terminology API) and the signature of the integration (see section Signatures below). +## Authentication and Authorization -Example of a session request body: +Before invoking any Terminology API, the Acrolinx Integration must +authorize and acquire a session. The authorization itself isn’t part +of the Terminology API. API requests without a valid session ID in the +`Authorization` HTTP header field fail with a `403 Forbbiden` +response: -```json +``` { - "sessionType": "TERMINOLOGY", - "clientSignature": "SW50ZWdyYXRpb25EZXZlbG9wbWVudERlbW9Pbmx5", - "clientInfo": { - "buildNumber": "unknown", - "clientHostname": "localhost", - "version": "0.1", - "name": "Terminology Test Client", - "clientHostApplication": "unknown", - "clientLoginName": "unknown" + "message": "Invalid session (no such session)", + "errors": { + "exception_type": "com.acrolinx.services.faults.InvalidSessionFault", + "exception_message": "Invalid session (no such session)" } } ``` -To request a session, do a `POST` on `/iq/services/v3/rest/core/requestSession`: - -```bash -curl -i -H "Content-Type: application/json; charset=UTF-8" -H "authToken: ${authToken}" -H "connection: keep-alive" -X POST http://${serverHostName}:8031/iq/services/v3/rest/core/requestSession -d "{\"sessionType\":\"TERMINOLOGY\",\"clientSignature\":\"${clientSignature}\",\"clientInfo\":{\"name\":\"terminology-example\",\"version\":\"1\",\"buildNumber\":\"1\",\"clientLoginName\":\"unknown\",\"clientHostname\":\"${clientHostName}\",\"clientHostApplication\":\"unknown\"}}" -``` +For all terminology service API methods, the user must have at least +the `Access API-based terminology applications` privilege. -```text - HTTP/1.1 200 OK - Content-Type: text/plain - Date: Wed, 12 Mar 2014 16:34:51 GMT - Content-Length: 16 +### Acquiring a Session [POST /iq/services/v3/rest/core/requestSession] - 56429c06fbd5da74 -``` +Using the authentication token, the integration now needs to open a +session, specifying the session-type (always `TERMINOLOGY` for usage +of the Terminology API) and the signature of the integration (see +Signatures section further up). -The returned session token should be used in subsequent requests to the Terminology API. It’s valid until -the session is released by the integration or by the Core Platform. -As the license limits the number of concurrently opened sessions, -an integration mustn’t forget to release a session before acquiring a new session token. +The returned session token should be used in subsequent requests to +the Terminology API. It’s valid until the session is released by the +integration or by the Core Platform. As the license limits the number +of concurrently opened sessions, an integration mustn’t forget to +release a session before acquiring a new session token. -### Releasing a Session ++ Request -A session can be released by a `DELETE` on `/iq/services/v3/rest/core/releaseSession`, providing the session as path -parameter: + + Header -```bash -curl -i -X DELETE http://${serverHostName}:8031/iq/services/v3/rest/core/releaseSession/${session2} -``` + authToken: your_access_token -```text -HTTP/1.1 204 No Content -Content-Length: 0 -Date: Wed, 12 Mar 2014 16:34:51 GMT -``` + + Body -#### Signatures + { + "sessionType": "TERMINOLOGY", + "clientSignature": "SW50ZWdyYXRpb25EZXZlbG9wbWVudERlbW9Pbmx5", + "clientInfo": { + "buildNumber": "unknown", + "clientHostname": "localhost", + "version": "0.1", + "name": "Terminology Test Client", + "clientHostApplication": "unknown", + "clientLoginName": "unknown" + } + } -An integration must identify itself to the Core Platform by means of a unique signature. This signature tells the Core -Platform which integration is trying to communicate to it. Depending on the signature the communication might be allowed. -Signatures can be enabled individually in the Core Platform's license. To request a session with the Core Platform, an integration's -signature is one of the required parameters. If the signature is unknown to the Core Platform, -no session can be opened and further communication isn’t possible. ++ Response (200 text/plain) -Acrolinx issues specific signatures to integrators. + 56429c06fbd5da74 -## Terminology Service Methods -The prefix to all v7 terminology API service paths is `http://${serverHostName}:8031/iq/services/v7/rest/terminology`. +### Releasing a Session [DELETE /iq/services/v3/rest/core/requestSession/{id}] -Required privileges: +A session can be released by a `DELETE` on +`/iq/services/v3/rest/core/releaseSession`, providing the session as +path parameter. -- for all terminology service API methods, the user must have at least the `Access API-based terminology applications` - privilege ++ Parameters -### Configuration + + id: `56429c06fbd5da74z` (required, string) - session ID -Before invoking one of the Terminology API services for the result format SDL MultiTerm, the Core Platform must be -configured correctly. This includes that there are XSL transformations from ACTIF to SDL MultiTerm XML and SDL MultiTerm -Definition XDT. The needed XSL style sheets will be available as part of the Core Platform resources. ++ Request -The availability of those resources can be checked in the Acrolinx Dashboard on -`Terminology -> Import and Export -> Import/Export -> Custom File Format`. + + Headers -### Media/Content Types + authToken: your_access_token -Except for application-specific XML data (ACTIF resp. SDL MultiTerm XML/XDT data), request, and response data is usually -either plain text or in JSON format. The encoding is usually assumed to be UTF-8. -With some service methods, you can control the format of the return values by means of the standard HTTP `Accept` header. ++ Response 204 -Service methods that accept application-specific body data rely on the correct setting of the standard HTTP -`Content-Type` header. -The supported media types are listed where applicable. +## Term entries [/iq/services/v9/rest/terminology] -### Getting Existing Entries by UUID or ID +### Get by UUID or ID [GET /entries/{id}] Supported media types: From 406838691f882e6d4f4262c1ea62f0dd80c67eac Mon Sep 17 00:00:00 2001 From: Robert Barbey Date: Mon, 10 Mar 2025 15:41:22 +0100 Subject: [PATCH 03/18] docs: migrated entries, schema and filters --- apiary.apib | 641 +++++++++++----------------------------------------- 1 file changed, 133 insertions(+), 508 deletions(-) diff --git a/apiary.apib b/apiary.apib index 62179762..2b7f66c0 100644 --- a/apiary.apib +++ b/apiary.apib @@ -7909,549 +7909,174 @@ This functionality is provided by `GET` `/entries`. There are two variants of th - asking for a single UUID or ID - asking for many UUIDs or IDs -For asking for only one entry simply, append its UUID to the service URI: +For asking for only one entry simply append its UUID to the service +URI. This works the same way for requesting multiple entries, just +pass a comma-separated list of IDs in the URL. The server determines +by the format of the passed ID string whether it’s a UUID or an ID. -```bash -curl -i -H "Accept: application/vnd.acrolinx.mtf+xml" -H "Authorization: session ee7ac269aed25b4e" -X GET http://${serverHostName}:8031/iq/services/v7/rest/terminology/entries/a918fccf-4a94-4398-b260-4d792289952c -``` - -```text -HTTP/1.1 200 OK -Content-Type: application/vnd.acrolinx.mtf+xml -Date: Wed, 12 Mar 2014 16:34:51 GMT -Content-Length: 8521 - -13a918fccf-4a94-4398-b260-4d792289952cadmin2011-06-28T11:55:28+02:00admin2014-02-03T11:00:04return airpreferredTechnical_Namesundefined domain120bdf01-4818-4a2c-bcea-4f875b6b129a13711976956060undefinedundefinedundefinedunprocessedundefinedadmin2011-06-28T11:55:28+02:00admin2014-02-03T11:00:04text nicht vorhandenproposedundefined domain680e0ea1-90f1-48ab-9ec9-5a362360692d13711976956220undefinedundefinedundefinedunprocessedundefinedadmin2011-06-28T12:11:20+02:00marco.aeschimann@ch.sauter-bc.com2011-07-05T10:54:28+02:00text nicht vorhandenproposedundefined domain01352af7-73e6-4024-9433-930846681b5613711976956300undefinedundefinedundefinedunprocessedundefinedadmin2011-06-28T12:11:19+02:00eric.schneider@ch.sauter-bc.com2011-09-13T10:47:25+02:00AbluftmengeproposedTechnical_Namesundefined domain44641d47-ddf3-4bb4-b1d4-a22a3fb42f6413711976956460undefinedundefinedundefinedunprocessedundefinedadmin2011-06-28T11:55:28+02:00admin2014-02-03T10:59:47débit d'air reprispreferredTechnical_Namesundefined domain5334a674-848b-44a3-8b42-1756d38717ef13711976956140undefinedundefinedundefinedunprocessedundefinedadmin2011-06-28T11:55:28+02:00admin2014-02-03T10:59:54débit d'évacuationdeprecatedTechnical_Namesundefined domain38e4ce12-4175-465e-a26f-4bb6d8a7ea1513711976956540undefinedundefinedundefinedunprocessedundefinedadmin2011-06-28T11:55:28+02:00admin2014-02-03T10:59:58text nicht vorhandenproposedundefined domain7958d666-8511-4c0e-aef1-d0f4748d2d4613711976956380undefinedundefinedundefinedunprocessedundefinedadmin2011-06-28T12:11:18+02:00admin2011-08-30T11:55:38+02:00 -``` - -This works the same way for entry IDs (the server determines by the format of the passed ID string whether it’s a UUID or -an ID): - -```bash -curl -i -H "Accept: application/vnd.acrolinx.mtf+xml" -H "Authorization: session ee7ac269aed25b4e" -X GET http://${serverHostName}:8031/iq/services/v7/rest/terminology/entries/13 -``` - -```text -HTTP/1.1 200 OK -Content-Type: application/vnd.acrolinx.mtf+xml -Date: Wed, 12 Mar 2014 16:34:51 GMT -Content-Length: 8521 - -13a918fccf-4a94-4398-b260-4d792289952cadmin2011-06-28T11:55:28+02:00admin2014-02-03T11:00:04return airpreferredTechnical_Namesundefined domain120bdf01-4818-4a2c-bcea-4f875b6b129a13711976956060undefinedundefinedundefinedunprocessedundefinedadmin2011-06-28T11:55:28+02:00admin2014-02-03T11:00:04text nicht vorhandenproposedundefined domain680e0ea1-90f1-48ab-9ec9-5a362360692d13711976956220undefinedundefinedundefinedunprocessedundefinedadmin2011-06-28T12:11:20+02:00marco.aeschimann@ch.sauter-bc.com2011-07-05T10:54:28+02:00text nicht vorhandenproposedundefined domain01352af7-73e6-4024-9433-930846681b5613711976956300undefinedundefinedundefinedunprocessedundefinedadmin2011-06-28T12:11:19+02:00eric.schneider@ch.sauter-bc.com2011-09-13T10:47:25+02:00AbluftmengeproposedTechnical_Namesundefined domain44641d47-ddf3-4bb4-b1d4-a22a3fb42f6413711976956460undefinedundefinedundefinedunprocessedundefinedadmin2011-06-28T11:55:28+02:00admin2014-02-03T10:59:47débit d'air reprispreferredTechnical_Namesundefined domain5334a674-848b-44a3-8b42-1756d38717ef13711976956140undefinedundefinedundefinedunprocessedundefinedadmin2011-06-28T11:55:28+02:00admin2014-02-03T10:59:54débit d'évacuationdeprecatedTechnical_Namesundefined domain38e4ce12-4175-465e-a26f-4bb6d8a7ea1513711976956540undefinedundefinedundefinedunprocessedundefinedadmin2011-06-28T11:55:28+02:00admin2014-02-03T10:59:58text nicht vorhandenproposedundefined domain7958d666-8511-4c0e-aef1-d0f4748d2d4613711976956380undefinedundefinedundefinedunprocessedundefinedadmin2011-06-28T12:11:18+02:00admin2011-08-30T11:55:38+02:00 -``` - -For the more general case, to ask for many entries at the same time specify the UUIDs (or IDs) as a comma-separated list -after the `/entries/` endpoint URL: - -```bash -curl -i -H "Accept: application/vnd.acrolinx.mtf+xml" -H "Authorization: session ee7ac269aed25b4e" -H "Content-Type: application/json" -X GET http://${serverHostName}:8031/iq/services/v7/rest/terminology/entries/a918fccf-4a94-4398-b260-4d792289952c,ee1c8221-5ac2-465a-bcb8-2f329ba0da8a -``` - -```text -HTTP/1.1 200 OK -Content-Type: application/vnd.acrolinx.mtf+xml -Date: Wed, 12 Mar 2014 16:34:51 GMT -Content-Length: 11081 - -1391421694240ee1c8221-5ac2-465a-bcb8-2f329ba0da8aadmin2014-02-03T11:01:34admin2014-02-03T11:01:36neuer TermpreferredTechnical_Names79425649-0a70-458a-8cf8-910539b9a1f313911896143950undefinedundefinedundefinedunprocessedundefinedadmin2014-02-03T11:01:34admin2014-02-03T11:01:36new termproposedTechnical_Names06208308-e8ca-4dbd-91fd-add7ca4f5e9013911896145610undefinedundefinedundefinedunprocessedundefinedadmin2014-02-03T11:01:51admin2014-02-03T11:01:5113a918fccf-4a94-4398-b260-4d792289952cadmin2011-06-28T11:55:28+02:00admin2014-02-03T11:00:04return airpreferredTechnical_Namesundefined domain120bdf01-4818-4a2c-bcea-4f875b6b129a13711976956060undefinedundefinedundefinedunprocessedundefinedadmin2011-06-28T11:55:28+02:00admin2014-02-03T11:00:04text nicht vorhandenproposedundefined domain680e0ea1-90f1-48ab-9ec9-5a362360692d13711976956220undefinedundefinedundefinedunprocessedundefinedadmin2011-06-28T12:11:20+02:00marco.aeschimann@ch.sauter-bc.com2011-07-05T10:54:28+02:00text nicht vorhandenproposedundefined domain01352af7-73e6-4024-9433-930846681b5613711976956300undefinedundefinedundefinedunprocessedundefinedadmin2011-06-28T12:11:19+02:00eric.schneider@ch.sauter-bc.com2011-09-13T10:47:25+02:00AbluftmengeproposedTechnical_Namesundefined domain44641d47-ddf3-4bb4-b1d4-a22a3fb42f6413711976956460undefinedundefinedundefinedunprocessedundefinedadmin2011-06-28T11:55:28+02:00admin2014-02-03T10:59:47débit d'air reprispreferredTechnical_Namesundefined domain5334a674-848b-44a3-8b42-1756d38717ef13711976956140undefinedundefinedundefinedunprocessedundefinedadmin2011-06-28T11:55:28+02:00admin2014-02-03T10:59:54débit d'évacuationdeprecatedTechnical_Namesundefined domain38e4ce12-4175-465e-a26f-4bb6d8a7ea1513711976956540undefinedundefinedundefinedunprocessedundefinedadmin2011-06-28T11:55:28+02:00admin2014-02-03T10:59:58text nicht vorhandenproposedundefined domain7958d666-8511-4c0e-aef1-d0f4748d2d4613711976956380undefinedundefinedundefinedunprocessedundefinedadmin2011-06-28T12:11:18+02:00admin2011-08-30T11:55:38+02:00 -``` - -**Note: The length of the request URL is limited by any HTTP server implementation. Based to our tests, we don't -recommend exceeding the value of 4000 characters.** - -### Querying the Term Base Structure - -Supported media types: - -- `application/vnd.acrolinx.actif+xml`: return schema as ACTIF in XML -- `application/vnd.acrolinx.mtf+xdt`: return entries as SDL MultiTerm XDT - -Required privilege: - -- Terminology - View Terms - -This functionality is provided by GET `/schema`. The structure of the Acrolinx term base can then be retrieved as -follows (in the example the SDL MultiTerm XDT representation is requested): - -```bash -curl -i -H "Accept: application/vnd.acrolinx.mtf+xdt" -H "Authorization: session ee7ac269aed25b4e" -X GET http://${serverHostName}:8031/iq/services/v7/rest/terminology/schema -``` - -```text -HTTP/1.1 200 OK -Content-Type: application/vnd.acrolinx.mtf+xdt -Date: Wed, 12 Mar 2014 16:34:52 GMT -Content-Length: 21990 - -Entry level0110ENTRY_UUID1001sourceOfDefinition1000definition1000Project ID1000imageURL1000Index level2110Term level3110Status1100domain1110MORPHOSYNTACTIC_RESTRICTION1001TERM_UUID1001TERM_ID1000VARIANTS_CONFIGURATIONS1001HISTORY_EVENT1001assignedTo1000project1000termType1000externalCrossReference1000processStatus1000geographicalUsage1000crossReference1000Number1000sourceOfTerm1000Usage note1000customer1000Unit1000Part of Speech1000gender1000Core1000Phrase1000note space1000context1000ARArabicfalseBGBulgarianfalseCSCzechfalseDEGermanfalseENEnglishfalseEN-GBEnglish (UK)falseEN-USEnglish (USA)falseESSpanishfalseFRFrenchfalseITItalianfalseJAJapanesefalseKOKoreanfalseNLDutchfalseNONorwegianfalsePTPortuguesefalseRURussianfalseSVSwedishfalseZHChinesefalseZH-CNChinese (PRC)falseZH-TWChinese (Taiwan)falseENTRY_UUIDTextFsourceOfDefinitionTextFdefinitionTextFProject IDTextFimageURLMultimedia FileFStatusPicklistproposedproposed_from_searchdeprecatedadmittedpreferrednon-termstopwordno-single-termFdomainPicklistundefined domaincustomerSpecial SymbolsDemoSwitchesKeitaidenwaKanaKanjiUsageADSLMFPDruckerAcrolinxStandard_TerminologyRoutersBelkinD-LinkCiscoPhoneASD-STE100Technical_NamesTN_1_Official_Parts_InformationTN_2_Locations_On_Machines_Vehicles_Or_EquipmentTN_3_Tools_Or_EquipmentTN_4_Materials_Consumables_Or_Unwanted_MatterTN_5_Facilities_And_InfrastructureTN_6_Circuits_Or_SystemsTN_7_Mathematical_Scientific_Or_Engineering_TermsTN_8_NavigationTN_9_Numbers_Units_Of_Measurement_Or_Dial_MarkingsTN_10_Quoted_TextTN_11_Persons_Groups_Or_BodiesTN_12_Body_PartsTN_13_Common_Personal_EffectsTN_14_Medical_TermsTN_15_Documents_Or_ManualsTN_16_Names_Headings_And_Topics_In_SpecificationsTN_17_Technical_Records_Standards_Specifications_Or_RegulationsTN_18_Environmental_ConditionsTN_19_ColorsTN_20_Damage_TermsTN_UnclassifiedTechnical_VerbsTV_1_Manufacturing_ProcessesTV_2_Computer_Processes_And_ApplicationsTV_3_DescriptionsTV_UnclassifiedS1000D Bike Data SetFMORPHOSYNTACTIC_RESTRICTIONPicklistallnounverbadjectiveadverbadpositionprepositiondeterminerconjunctionpronounprefixsuffixFTERM_UUIDTextFTERM_IDTextFVARIANTS_CONFIGURATIONSTextFHISTORY_EVENTTextFassignedToTextFprojectTextFtermTypePicklisttrademarkundefinedfull formacronymabbreviationshort formvariantphraseFexternalCrossReferenceTextFprocessStatusPicklistunprocessedprovisionally processedfinalizedreview requestedFgeographicalUsageTextFcrossReferenceTextFNumberTextFsourceOfTermTextFUsage noteTextFcustomerTextFUnitTextFPart of SpeechPicklistadjectiveadverbnounotherproper nounundefinedverbFgenderPicklistundefinedmasculinefeminineneuterotherFCorePicklistundefinedcoreFPhraseTextFnote spaceTextFcontextTextF10Exported from Acrolinx at 2014-03-12 17:34:52 -``` - -### Querying for Available Filters - -The only supported media type is `application/json`. - -Required privilege: - -- Terminology - View Terms - -The terminology service API offers an operation to get the ids/names of all filters for term search operations, that are -available to the user in the current session. The available filters can be retrieved by `GET` to `/filters`: - -```bash -curl -i -H "Accept: application/json" -H "Authorization: session ee7ac269aed25b4e" -X GET http://${serverHostName}:8031/iq/services/v7/rest/terminology/filters -``` - -```text -HTTP/1.1 200 OK -Content-Type: application/json -Date: Wed, 12 Mar 2014 16:34:52 GMT -Transfer-Encoding: chunked - -{ - "user": "admin", - "filters": [ - { - "id": "Preferred Technical Names" - }, - { - "id": "SEO" - }, - { - "id": "Images" - } -] -} -``` - -The filters can be referenced by their `id` in a search API operation, described in the next section. - -### Searching Terms +**Note:** The length of the request URL is limited by any HTTP server +implementation. Based on our tests, we don't recommend exceeding the +value of 4000 characters. -Terms can be searched by: ++ Parameters -- term `name`, supporting '%' as wildcard; -- `language` id -- `domains` an array of one or several domain names -- `filter` id -- or any combination of the above + + id: (required, string) -The individual fields of the search criteria need to be "escaped" by their unicode positions in case they contain -characters that would otherwise break the JSON request string. For example, the apostrophe/single quote character `'` is -escaped as `\u0027`. + Either a single term entry ID or a comma-separated list of entry IDs. -The search API supports pagination to retrieve only a certain subset of the result set. The parameters are: ++ Request ACTIF + + Headers + authToken: your_access_token + Authorization: session your_session_id + Accept: application/vnd.acrolinx.mtf+xml -- `offset`, the index of the first term to display (starting from 0, where the terms are always sorted ascending by - their name) -- `limit`, the maximal number of terms to return, starting from `offset`; if < 1, no limit is imposed ++ Response 200 (application/vnd.acrolinx.actif+xml) -The only supported media type for request as well as result is `application/json`. + + Body -Required privilege: + + + + + + + + en + + + red + foggy + cold + cloudy + 077061bc-d9ab-455d-a078-bb1fb648440e_f2f455eb5898c6568524f6ca87236342.jpg + 1309938647786 + 459a8ff0-dfab-49d6-927f-6c456f194168 + + + 802.11n technology + en + preferred + D-Link + 6183eceb-33e4-4b5e-b721-0ac34eb78fb4 + 1309883915302 + 0 + 2011-07-06T08:02:35.383Z + admin + 2024-06-26T14:38:51.230Z + peter.bernds@acrolinx.com + unprocessed + undefined + undefined + undefined + + string + + + + + 802.11 network switch + en + preferred + Belkin + 077061bc-d9ab-455d-a078-bb1fb648440e + 1309883964051 + 0 + 2011-07-06T08:15:24.073Z + admin + 2024-06-26T14:38:51.342Z + peter.bernds@acrolinx.com + unprocessed + light red + undefined + undefined + undefined + + base (analyzed) + network + 1 + noun + + + admin + 2016-11-21T17:01:51.887Z + COMMENT + ttt + + + + + + + ++ Request SDL Multiterm format -- Terminology - View Terms + + Headers -The search-terms service function requires a request object in the format illustrated by the following example: + Authorization: session your_session_id + Accept: application/vnd.acrolinx.mtf+xml -```json -{ - "criteria": { - "name": "d\\u00e9bit%", - "language": "fr", - "domains": ["Technical Names", "Demo"], - "filter": "Preferred Technical Names" - }, - "pagination": { - "offset": 0, - "limit": -1 - } -} -``` ++ Response 200 (application/vnd.acrolinx.mtf+xml) -The `criteria` and `pagination` values are mandatory, as well as `offset` and `limit`, but you can leave out (or set to -`null`) those fields of `criteria` that aren’t required by a specific query (for `domains` you can also pass an empty -array `[]`). - -The criteria that exist in the search request are then combined by AND (if `domains` contains more than one value, they’re - combined into a domain filter by OR-ing them) in the resulting filter. + + Body -You can then search with those settings by submitting a `POST`-request to `/searchTerms`: + 13a918fccf-4a94-4398-b260-4d792289952cadmin2011-06-28T11:55:28+02:00admin2014-02-03T11:00:04return airpreferredTechnical_Namesundefined domain120bdf01-4818-4a2c-bcea-4f875b6b129a13711976956060undefinedundefinedundefinedunprocessedundefinedadmin2011-06-28T11:55:28+02:00admin2014-02-03T11:00:04text nicht vorhandenproposedundefined domain680e0ea1-90f1-48ab-9ec9-5a362360692d13711976956220undefinedundefinedundefinedunprocessedundefinedadmin2011-06-28T12:11:20+02:00marco.aeschimann@ch.sauter-bc.com2011-07-05T10:54:28+02:00text nicht vorhandenproposedundefined domain01352af7-73e6-4024-9433-930846681b5613711976956300undefinedundefinedundefinedunprocessedundefinedadmin2011-06-28T12:11:19+02:00eric.schneider@ch.sauter-bc.com2011-09-13T10:47:25+02:00AbluftmengeproposedTechnical_Namesundefined domain44641d47-ddf3-4bb4-b1d4-a22a3fb42f6413711976956460undefinedundefinedundefinedunprocessedundefinedadmin2011-06-28T11:55:28+02:00admin2014-02-03T10:59:47débit d'air reprispreferredTechnical_Namesundefined domain5334a674-848b-44a3-8b42-1756d38717ef13711976956140undefinedundefinedundefinedunprocessedundefinedadmin2011-06-28T11:55:28+02:00admin2014-02-03T10:59:54débit d'évacuationdeprecatedTechnical_Namesundefined domain38e4ce12-4175-465e-a26f-4bb6d8a7ea1513711976956540undefinedundefinedundefinedunprocessedundefinedadmin2011-06-28T11:55:28+02:00admin2014-02-03T10:59:58text nicht vorhandenproposedundefined domain7958d666-8511-4c0e-aef1-d0f4748d2d4613711976956380undefinedundefinedundefinedunprocessedundefinedadmin2011-06-28T12:11:18+02:00admin2011-08-30T11:55:38+02:00 -```bash -curl -i -H "Content-Type: application/json; charset=UTF-8" -H "Accept: application/json" -H "Authorization: session ee7ac269aed25b4e" -X POST http://${serverHostName}:8031/iq/services/v7/rest/terminology/searchTerms -d '{"criteria":{"name":"d%","language": "fr","domains":["undefined domain", "Technical Names"], "filter":null},"pagination":{"offset": 0,"limit": -1}}' -``` ++ Response 406 -```text -HTTP/1.1 200 OK -Content-Type: application/json -Date: Wed, 12 Mar 2014 16:34:52 GMT -Transfer-Encoding: chunked + + Body -{ - "terms": [ - { - "name": "débit d\u0027air repris", - "status": "preferred", - "domains": [ - "Technical_Names", - "undefined domain" - ], - "uuid": "5334a674-848b-44a3-8b42-1756d38717ef", - "entry": { - "uuid": "a918fccf-4a94-4398-b260-4d792289952c", - "id": "13" - } - }, - { - "name": "débit d\u0027évacuation", - "status": "deprecated", - "domains": [ - "Technical_Names", - "undefined domain" - ], - "uuid": "38e4ce12-4175-465e-a26f-4bb6d8a7ea15", - "entry": { - "uuid": "a918fccf-4a94-4398-b260-4d792289952c", - "id": "13" + { + "error": "No terminology export transformation stylesheet available for 'application/vnd.acrolinx.mtf+xml'", + "code": "cantServeRequestedMediaType", + "data": {} } - } - ], - "search": { - "pagination": { - "offset": 0, - "limit": -1 - }, - "criteria": { - "name": "d%", - "language": "fr", - "filter": null, - "domains": [ - "undefined domain", - "Technical Names" - ] - } - }, - "totalResultCount": 2 -} -``` - -(Note: there exists indeed a domain name `undefined domain` in the Core Platform default setup; -that value doesn't indicate the absence of a value for the domain.) - -The response is a JSON object with the following attributes: - -- `search` contains your search criteria and pagination settings; you could reuse that object for subsequent calls with - the same criteria -- `totalResultCount` is the total number of hits for the search, before applying the pagination limit -- `terms`: an array of term objects, each containing the attributes `name`, `status`, `domains`, `uuid` (the UUID of the - term: use that UUID to identify the specific term data from the full entry that you retrieve by the entry UUID), - `entry`; `entry` again is an object with two attributes `uuid` and `id`, the UUID, and ID of the entry. Using the entry - UUID or ID you can then retrieve the entire entry via `GET` `/entries` (see above). -If there are no matching terms (or you request an offset greater than the result count), `terms` will be an empty array. -If your search request refers to a nonexistent filter, the server will respond with a 400 (Bad Request). +## Schema [/iq/services/v9/rest/terminology/schema] -### Getting Terms with Search Criteria +### Get term base structure [GET] -You can also search for terms using an older method called `findTerms`, which supports some search criteria that -aren’t available in the `searchTerms` method above, and which also returns the result in a specified target format, -just like `get entries` described above. +Retrieves the structure of the Acrolinx term base. -The following search criteria are supported: - -- term `surface` (name), supporting '%' as wildcard -- `language` id -- `domain` - a single domain name -- `entry ID/UUID` - an array of entry IDs or entry UUIDs -- custom criteria - an array of `field=value` strings, where `field` is one of the following ACTIF field names: - + `term/id` - + `term/uuid` - + `entry/id` - + `enty/uuid` - + `term/creation-date-time` (prepend with `<` or `>` to find terms created before or after the given date) - + `term/last-modification-date-time` (prepend with `<` or `>` to find terms modified before or after the given date) - + `term/creator-user-name` - + `term/last-modifier` - + any custom field name (as it appears in ACTIF) - -The individual fields of the search criteria need to be "escaped" by their unicode positions in case they contain -characters that would otherwise break the JSON request string. For example, the apostrophe/single quote character `'` is -escaped as `\u0027`. - -All criteria are combined with `AND` when the term filter is constructed. All criteria are optional; if you don’t give -any criteria, the result includes all terms. - -The desired result format needs to be specified in the required `format` attribute of the request object (not in the -`Accept` HTTP header). The supported media types are the same as for the "get entries" method above: - -- `application/vnd.acrolinx.actif+xml`: return terms as ACTIF in XML -- `application/vnd.acrolinx.mtf+xml`: return terms as SDL MultiTerm XML - -Finally, you can optionally have the term base structure (schema) included in the response by setting the `withSchema` -attribute to `true`. - -Required privilege: - -- Terminology - View Terms ++ Request -The find-terms service function requires a request object in the format illustrated by the following example: + + Headers -```json -{ - "surface": "d\\u00e9bit%", - "language": "fr", - "domain": ["Demo"], - "customCriteria": [ - "term/creation-date-time=<2012-05-10T11:41:00", - "customWorkflowStatus=reviewed" - ], - "withSchema": false, - "format": "application/vnd.acrolinx.mtf+xml" -} -``` + Authorization: session your_session_id + Accept: application/vnd.acrolinx.actif+xml -You can then search with those settings by `POST`ing the request to `/findTerms/`. (Note that the terminology -session is part of the URL here; the `Authorization` header is ignored.) ++ Response 200 (application/vnd.acrolinx.actif+xml) -```bash -curl -i -H \"Content-Type: application/json; charset=UTF-8\" -X POST http://${serverHostName}:8031/iq/services/v7/rest/terminology/findTerms/ee7ac269aed25b4e -d '{"name":"d%","language": "fr","customCriteria":["term/uuid=a918fccf-4a94-4398-b260-4d792289952c"], "format":"application/vnd.acrolinx.mtf+xml"}' -``` + + Body -```text -HTTP/1.1 200 OK -Content-Type: application/vnd.acrolinx.mtf+xml -Date: Wed, 12 Mar 2014 16:34:51 GMT -Content-Length: 8521 + enen-JPen-USen-GBdejazhzh-CNzh-TWarfritkoruessvmulnobgcsnlptsprachesub1sub2truefalsestringbase (analyzed)adjectiveadverbnounotherproper nounundefinedverballnounverbadjectiveadverbadpositionprepositiondeterminerconjunctionpronounprefixsuffixNew_WordsPlain_EnglishSmart Techundefined domaineven more undefinedcustomerex customerSpecial SymbolsDemoSwitchesKeitaidenwaKanaKanjiUsageADSLMFPDruckerAcrolinxStandard_TerminologyRoutersBelkinD-LinkCiscoPhoneASD-STE100Technical_NamesTN_1_Official_Parts_InformationTN_2_Locations_On_Machines_Vehicles_Or_EquipmentTN_3_Tools_Or_EquipmentTN_4_Materials_Consumables_Or_Unwanted_MatterTN_5_Facilities_And_InfrastructureTN_6_Circuits_Or_SystemsTN_7_Mathematical_Scientific_Or_Engineering_TermsTN_8_NavigationTN_9_Numbers_Units_Of_Measurement_Or_Dial_MarkingsTN_10_Quoted_TextTN_11_Persons_Groups_Or_BodiesTN_12_Body_PartsTN_13_Common_Personal_EffectsTN_14_Medical_TermsTN_15_Documents_Or_ManualsTN_16_Names_Headings_And_Topics_In_SpecificationsTN_17_Technical_Records_Standards_Specifications_Or_RegulationsTN_18_Environmental_ConditionsTN_19_ColorsTN_20_Damage_TermsTN_UnclassifiedTechnical_VerbsTV_1_Manufacturing_ProcessesTV_2_Computer_Processes_And_ApplicationsTV_3_DescriptionsTV_UnclassifiedS1000D Bike Data SetDental Floss Tycoonproposedproposed_from_searchdeprecatedadmittedpreferrednon-termstopwordno-single-termundefinedwamcoldsunnycloudyfoggyrainyhotunprocessedprovisionally processedfinalizedreview requestedundefinedmasculinefeminineneuterotherundefinedfull formacronymabbreviationshort formvariantphraseundefinedredlight reddark redcarmesingreenblueyellowundefinedhotblueproposedundefined domainunprocesseddark redundefinedundefinedundefined -13a918fccf-4a94-4398-b260-4d792289952cadmin2011-06-28T11:55:28+02:00admin2014-02-03T11:00:04return airpreferredTechnical_Namesundefined domain120bdf01-4818-4a2c-bcea-4f875b6b129a13711976956060undefinedundefinedundefinedunprocessedundefinedadmin2011-06-28T11:55:28+02:00admin2014-02-03T11:00:04text nicht vorhandenproposedundefined domain680e0ea1-90f1-48ab-9ec9-5a362360692d13711976956220undefinedundefinedundefinedunprocessedundefinedadmin2011-06-28T12:11:20+02:00marco.aeschimann@ch.sauter-bc.com2011-07-05T10:54:28+02:00text nicht vorhandenproposedundefined domain01352af7-73e6-4024-9433-930846681b5613711976956300undefinedundefinedundefinedunprocessedundefinedadmin2011-06-28T12:11:19+02:00eric.schneider@ch.sauter-bc.com2011-09-13T10:47:25+02:00AbluftmengeproposedTechnical_Namesundefined domain44641d47-ddf3-4bb4-b1d4-a22a3fb42f6413711976956460undefinedundefinedundefinedunprocessedundefinedadmin2011-06-28T11:55:28+02:00admin2014-02-03T10:59:47débit d'air reprispreferredTechnical_Namesundefined domain5334a674-848b-44a3-8b42-1756d38717ef13711976956140undefinedundefinedundefinedunprocessedundefinedadmin2011-06-28T11:55:28+02:00admin2014-02-03T10:59:54débit d'évacuationdeprecatedTechnical_Namesundefined domain38e4ce12-4175-465e-a26f-4bb6d8a7ea1513711976956540undefinedundefinedundefinedunprocessedundefinedadmin2011-06-28T11:55:28+02:00admin2014-02-03T10:59:58text nicht vorhandenproposedundefined domain7958d666-8511-4c0e-aef1-d0f4748d2d4613711976956380undefinedundefinedundefinedunprocessedundefinedadmin2011-06-28T12:11:18+02:00admin2011-08-30T11:55:38+02:00 -``` +## Filters [/iq/services/v9/rest/terminology/filters] -### Searching Entry UUIDs and IDs by Domain +### Get available filters [GET] -You can retrieve all or only the entries (represented by their UUID and ID) of specific domains by using the -`searchEntries` service endpoint. This service works similar to the "search terms" service, but you can only specify a -list of domains as search criterion, for example: +Returns the ids/names of all filters for term search operations, that +are available to the user in the current session. The filters can be +referenced by their `id` in a search API operation, described in the +next section. -```json -{ - "criteria": { - "domains": ["Technical_Names", "Demo"] - } -} -``` ++ Request -- Passing a nonempty array will get you all entries that contain at least one term that is assigned to at least one of - the specified domains. -- Passing an empty array for domains will get you all entries. + + Headers -Example: + Authorization: session your_session_id -```bash -curl -i -H "Content-Type: application/json; charset=UTF-8" -H "Accept: application/json" -H "Authorization: session ee7ac269aed25b4e" -X POST http://${serverHostName}:8031/iq/services/v7/rest/terminology/searchEntries -d '{"criteria":{"domains":["undefined domain", "Technical_Names"]}}' -``` ++ Response 200 (application/json) -```text -HTTP/1.1 200 OK -Content-Type: application/json -Date: Wed, 12 Mar 2014 16:34:52 GMT -Transfer-Encoding: chunked + + Body -{ - "entries": [ { - "uuid": "a918fccf-4a94-4398-b260-4d792289952c", - "id": "13" - }, - { - "uuid": "ee1c8221-5ac2-465a-bcb8-2f329ba0da8a", - "id": "1391421694240" - } - ], - "search": { - "criteria": { - "domains": [ - "undefined domain", - "Technical_Names" - ] + "user": "admin", + "filters": [{ + "id": "Preferred Technical Names" + }, { + "id": "SEO" + }, { + "id": "Images" + }] } - }, - "totalResultCount": 2 -} -``` - -The response is a JSON object with the following attributes: - -- `search` contains your search criteria -- `totalResultCount` is the total number of entries matching the criterion -- `entries`: an array of entries, each containing the attributes `id`, and `uuid`. Using the entry UUID or ID you can then - retrieve the entire entry via `GET` `/entries` (see above). - -### Creation and Update of Entries and Terms - -Entries and their terms can be created and updated by `POST`ing the respective ACTIF or SDL MultiTerm XML representation -to `/entries`. -Whether an existing entry is updated or a new entry created crucially depends on the entry UUID specified in the sent -data. -If the entry UUID references an existing entry in the database, all terms and fields of the entry will be replaced by -the sent data. -Specifically, if the sent entry data contains fewer terms than the existing entry in the database, those terms missing -from the sent entry data will be deleted. - -Otherwise, that is, no entry of the same UUID exists, a new entry will be created. - -Supported media types are: - -- `application/vnd.acrolinx.actif+xml`: ACTIF in XML -- `application/vnd.acrolinx.mtf+xml`: SDL MultiTerm XML - -Required privileges: - -- Terminology - Import terms (implies "Edit terms") -- Terminology - Change the status of a term - -Return codes: - -- For both creation and update, the return code is 201 (created) and the "Location" header gets the - URL of the inserted/updated entry. -- If the input data doesn't contain an entry that needs to be created or updated, you'll see a 204 (no content). -- If the input data contains more than one entry (which is allowed), all entries in the input data will be created or updated respectively. However, - the "Location" header will only contain the URL of one of them. - -Example (sending [example-entry.actif.xml](doc/example-entry.actif.xml)): - -```bash -curl -i -H "Accept: application/json" -H "Content-Type: application/vnd.acrolinx.actif+xml" -H "Authorization: session ee7ac269aed25b4e" -X POST http://${serverHostName}:8031/iq/services/v7/rest/terminology/entries -d "`cat doc/example-entry.actif.xml`" -``` - -```text -HTTP/1.1 100 Continue - -HTTP/1.1 201 Created -Content-Length: 0 -Date: Wed, 12 Mar 2014 16:34:52 GMT -Location: http://localhost:8031/iq/services/v7/rest/terminology/entries/a918fccf-4a94-4398-b260-4d792289952c -``` - -For this service call to succeed, the terminology database schemas -of the sent data and of the current database have to be compatible. -The terminology database schema is the definition of the field names and types, list items, etc. -In case of mismatches, the data is either inserted incompletely or might be rejected entirely with a 4xx error code. - -### Deployment of Terminology - -After terms and entries have been created or updated using the above method, they're not immediately available for -checking. -To make the new or updated terms available for checking, the terminology needs to be "deployed". Currently, triggering a -"deploy" of the terminology just causes all running language servers to reload their language configuration, which -includes the loading of the terminology. -Please note that a language becomes unavailable for checking for a certain amount of time up to several -minutes. Therefore terminology deployments should be scheduled for convenient times and not just done after each term -or entry update. -You only need to (re)deploy terms/entries in domains and languages the language configuration uses for -checking. For instance, when you've updated only the Arabic translation of a term, and there's no language -server running for Arabic, a "deploy" isn’t necessary. - -Required privileges: - -- Resources - Reload server configuration - -To deploy the terminology, call `PUT` on `/deployTerminology`: - -```bash -curl -i -H "Authorization: session ee7ac269aed25b4e" -X PUT http://${serverHostName}:8031/iq/services/v7/rest/terminology/deployTerminology -``` - -```text -HTTP/1.1 204 No Content -Content-Length: 0 -Date: Wed, 12 Mar 2014 16:34:52 GMT -``` - -If the call is authorized, it always returns 204 (No Content). - -### Deletion of Entries - -Entire entries can be removed by calling `DELETE` on `/entries/{entryUUID}`. If an entry existed and could be deleted -successfully, the service returns 204 (No Content). Otherwise, if there’s no entry under the specified UUID, the -service returns 410 (Gone). - -Required Privilege - -- Terminology - Edit Terms - -Example: - -```bash -curl -i -H "Authorization: session ee7ac269aed25b4e" -X DELETE http://${serverHostName}:8031/iq/services/v7/rest/terminology/entries/a70b25cd-89a9-49c6-8548-87f846188b19 -``` - -```text -HTTP/1.1 410 Gone -Content-Length: 0 -Date: Wed, 12 Mar 2014 16:34:52 GMT -``` - -### Upload of Multimedia Files - -A multimedia object can be uploaded to the Core Platform specifying a unique file name. We recommend using a scheme -based on newly generated UUIDs plus a readable part and the file extension. If an existing filename is used, the old one -will be replaced. - -To transfer a media file to the Core Platform the term API service, call `POST` on `/media/{finaName}`. - -Supported media types are: - -- `image/*`: all images types, for example, `image/png`, `image/gif`, etc. -- `application/pdf` - -Required privileges: - -- Terminology - Import terms (implies "Edit terms") - -Return codes: - -- 201 (Created) in the case of success. The Location header contains the URL of the uploaded content. -- 404 (Not Found) if the filename contains a `/`. - -Example: - -```bash -curl -i -H "Authorization: session ee7ac269aed25b4e" -H "Content-Type: image/png" -X POST http://${serverHostName}:8031/iq/services/v7/rest/terminology/media/nav_bullet_red.png --data-binary "@nav_bullet_red.png" -``` - -```text -HTTP/1.1 201 Created -Content-Length: 0 -Date: Wed, 12 Mar 2014 16:34:52 GMT -Location: http://@rab.local:8031/uploadedImages/nav_bullet_red.png -``` - -### Download of Multimedia Files - -A multimedia object that has been uploaded through this API can be downloaded using the unique filename. To achieve -this, call `GET` on `/media/{filename}`. - -Required privileges: - -- Terminology - Export terms (implies "Read terms") - -Return codes: - -- In case of success, 200 (OK) and the response body contains the media file. -- 404 (Not Found) if the filename doesn't exist. - -Example: - -```bash -curl -i -H "Authorization: session ee7ac269aed25b4e" -H "Accept: image/png" -X GET http://${serverHostName}:8031/iq/services/v7/rest/terminology/media/nav_bullet_red.png -``` - -```text -HTTP/1.1 200 OK -Content-Type: image/png -Date: Wed, 12 Mar 2014 16:34:52 GMT -Transfer-Encoding: chunked -?PNG -IHDR ????tEXtSoftwareAdobe ImageReadyq?e<XIDATx?b??????? ħ?? ?9?x?#??(?bidA??v ?G] ?B??ӑ7q?? ?D?_?? ???0-'?,??͹IEND?B`? -``` From 48a5494593c339f4b952999f251f6237e956395c Mon Sep 17 00:00:00 2001 From: Robert Barbey Date: Tue, 11 Mar 2025 11:26:01 +0100 Subject: [PATCH 04/18] docs: find terms --- apiary.apib | 265 ++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 265 insertions(+) diff --git a/apiary.apib b/apiary.apib index 2b7f66c0..042b380f 100644 --- a/apiary.apib +++ b/apiary.apib @@ -7148,6 +7148,39 @@ you'll see a response other than `200`. ## RandomPassword + value (string) - a random, policy-compliant password +## FindTermsRequest ++ surface (string) ++ language (string) ++ domain (string) ++ entryId (string) ++ customCriteria (array[string]) ++ format (required, string) ++ withSchema (boolean) + +## SearchRequest (object) ++ criteria (SearchRequestCriteria) ++ pagination (SearchRequestPagination) + +### SearchRequestCriteria (object) ++ name (string) ++ language (string) ++ domains (array[string]) ++ filter (string) + +### SearchRequestPagination (object) ++ offset (number) ++ limit (number) + +## SearchResult (object) ++ terms (array[Term]) ++ search (SearchRequest) ++ totalResultsCount (number) + +### Term (object) ++ name (string) ++ status (string) ++ domains (array[string]) + # Group Reporting API The reporting API provides direct access to raw check data and raw issue data. @@ -8080,3 +8113,235 @@ next section. }] } +## Search [/iq/services/v9/rest/terminology/searchTerms] + +### by criteria [POST] + +Terms can be searched by: + +* term `name`, supporting `%` as wildcard; +* `language` id +* `domains` an array of one or several domain names +* `filter` id +* or any combination of the above + +The individual fields of the search criteria need to be "escaped" by +their unicode positions in case they contain characters that would +otherwise break the JSON request string. For example, the +apostrophe/single quote character `'` is escaped as `\u0027`. + +The search API supports pagination to retrieve only a certain subset +of the result set. The parameters are: + +* `offset`, the index of the first term to display (starting from 0, +where the terms are always sorted ascending by their name) +* `limit`, the maximal number of terms to return, starting from +offset; if < 1, no limit is imposed. + +The only supported media type for request as well as +result is application/json. + +The search-terms service function requires a request object in the +format illustrated by the following example: + +``` +{ + "criteria": { + "name": "d\\u00e9bit%", + "language": "fr", + "domains": ["Technical Names", "Demo"], + "filter": "Preferred Technical Names" + }, + "pagination": { + "offset": 0, + "limit": -1 + } +} +``` + +The `criteria` and `pagination` values are mandatory, as well as +`offset` and `limit`, but you can leave out (or set to `null`) those +fields of criteria that aren’t required by a specific query (for +domains you can also pass an empty array `[]`). + +The criteria that exist in the search request are then combined by AND +(if domains contains more than one value, they're combined into a +domain filter by OR-ing them) in the resulting filter. + +The response is a JSON object with the following attributes: + +* `search` contains your search criteria and pagination settings; you +could reuse that object for subsequent calls with the same criteria +* `totalResultCount` is the total number of hits for the search, +before applying the pagination limit +* `terms`: an array of term objects, each containing the attributes +`name`, `status`, `domains`, `uuid` (the UUID of the term: use that +UUID to identify the specific term data from the full entry that you +retrieve by the entry UUID), `entry`; entry again is an object with +two attributes uuid and id, the UUID, and ID of the entry. Using the +entry UUID or ID you can then retrieve the entire entry via `GET +/entries` (see above). + +If there are no matching terms (or you request +an offset greater than the result count), terms will be an empty +array. If your search request refers to a nonexistent filter, the +server will respond with a 400 (Bad Request). + + ++ Request + + Header + Authorization: session your_session_id + + + Attributes (SearchRequest) + + + Body + {} + ++ Response 200 (application/json) + + + Attributes (SearchResult) + + + Body + { + "terms": [{ + "name": "debit d\u0027air repris", + "status": "preferred", + "domains": ["Technical_Names", "undefined domain"], + "uuid": "5334a674-848b-44a3-8b42-1756d38717ef", + "entry": { + "uuid": "a918fccf-4a94-4398-b260-4d792289952c", + "id": "13" + } + }, { + "name": "debit d\u0027évacuation", + "status": "deprecated", + "domains": ["Technical_Names", "undefined domain"], + "uuid": "38e4ce12-4175-465e-a26f-4bb6d8a7ea15", + "entry": { + "uuid": "a918fccf-4a94-4398-b260-4d792289952c", + "id": "13" + } + }], + "search": { + "pagination": { + "offset": 0, + "limit": -1 + }, + "criteria": { + "name": "d%", + "language": "fr", + "filter": null, + "domains": ["undefined domain","Technical Names"] + } + }, + "totalResultCount": 2 + } + +### Find terms [GET /iq/services/v9/rest/terminology/findTerms/{sessionId}] + +You can also search for terms using an older method called +`findTerms,` which supports some search criteria that aren't available +in the `searchTerms` method above, and which also returns the result +in a specified target format, just like get entries described above. + +The following search criteria are supported: + +* term `surface` (name), supporting `%` as wildcard +* `language` id +* `domain` - a single domain name +* `entry` ID/UUID - an array of entry IDs or entry UUIDs +* custom `criteria` - an array of `field=value` strings, where field is one of the following ACTIF field names: + * `term/id` + * `term/uuid` + * `entry/id` + * `entry/uuid` + * `term/creation-date-time` (prepend with `<` or `>` to find terms + created before or after the given date) + * `term/last-modification-date-time` (prepend with `<` or `>` to + find terms modified before or after the given date) + * `term/creator-user-name` + * `term/last-modifier` + * any custom field name (as it appears in ACTIF) + +The individual fields of the search criteria need to be "escaped" by +their unicode positions in case they contain characters that would +otherwise break the JSON request string. For example, the +apostrophe/single quote character `'` is escaped as `\u0027`. + +All criteria are combined with AND when the term filter is +constructed. All criteria are optional; if you don’t give any +criteria, the result includes all terms. + +The desired result format needs to be specified in the required format +attribute of the request object (not in the Accept HTTP header). The +supported media types are the same as for the "get entries" method +above: + +* `application/vnd.acrolinx.actif+xml`: return terms as ACTIF in XML +* `application/vnd.acrolinx.mtf+xml`: return terms as SDL MultiTerm XML + +Finally, you can optionally have the term base structure (schema) +included in the response by setting the `withSchema` attribute to +true. + ++ Parameters + + + sessionId (string,required) + + The current session ID + ++ Request + + + Attributes (FindTermsRequest) + + + Headers + + Content-Type: application/json + ++ Response 200 (text/plain) + + + Body + + + + + + en + + undefined + 1307356662917 + ff61f9ce-9c23-4874-bb98-cc58456b8734 + + + 2-Loch-Buchse + de + preferred + ADSL + 6c2b681c-0d2f-4820-9833-8b2d35ab6fe8 + 22946 + 0 + 2011-06-06T10:37:42.963Z + admin + 2024-06-26T14:38:51.282Z + peter.bernds@acrolinx.com + finalized + undefined + undefined + undefined + + base (analyzed) + 2-Loch-Buchse + 1 + noun + + + peter.bernds@acrolinx.com + 2024-06-25T13:51:47.671Z + COMMENT + Test + + + + + + From 3740cc5b30f504511461d0826f55b770ebc823ea Mon Sep 17 00:00:00 2001 From: Robert Barbey Date: Tue, 11 Mar 2025 11:58:45 +0100 Subject: [PATCH 05/18] docs: search entries --- apiary.apib | 82 ++++++++++++++++++++++++++++++++++++++++++++++++++--- 1 file changed, 78 insertions(+), 4 deletions(-) diff --git a/apiary.apib b/apiary.apib index 042b380f..9c3bf293 100644 --- a/apiary.apib +++ b/apiary.apib @@ -7157,6 +7157,21 @@ you'll see a response other than `200`. + format (required, string) + withSchema (boolean) +## SearchEntriesRequest ++ critera (SearchEntriesCriteria) + +### SearchEntriesCriteria ++ domains (array[string]) + +## SearchEntriesResult ++ entries (array[SearchEntryResult]) ++ search (SearchEntriesRequest) ++ totalResultCount (number) + +### SearchEntryResult ++ uuid (string) ++ id (string) + ## SearchRequest (object) + criteria (SearchRequestCriteria) + pagination (SearchRequestPagination) @@ -8113,9 +8128,7 @@ next section. }] } -## Search [/iq/services/v9/rest/terminology/searchTerms] - -### by criteria [POST] +## Search terms [POST /iq/services/v9/rest/terminology/searchTerms] Terms can be searched by: @@ -8237,7 +8250,8 @@ server will respond with a 400 (Bad Request). "totalResultCount": 2 } -### Find terms [GET /iq/services/v9/rest/terminology/findTerms/{sessionId}] + +## Find terms [GET /iq/services/v9/rest/terminology/findTerms/{sessionId}] You can also search for terms using an older method called `findTerms,` which supports some search criteria that aren't available @@ -8345,3 +8359,63 @@ true. + +## Search entries [POST /iq/services/v9/rest/terminology/searchEntries] + +You can retrieve all or only the entries (represented by their UUID +and ID) of specific domains by using the searchEntries service +endpoint. This service works similar to the "search terms" service, +but you can only specify a list of domains as search criterion, for +example: + +``` +{ + "criteria": { + "domains": ["Technical_Names", "Demo"] + } +} +``` + +Passing a nonempty array will get you all entries that contain at +least one term that is assigned to at least one of the specified +domains. Passing an empty array for domains will get you all entries. + ++ Request + + + Attributes (SearchEntriesRequest) + + + Headers + + Authorization: session + + + Body + + {"criteria":{"domains":["undefined domain", "Technical_Names"]}} + ++ Response 200 (application/json) + + + Attributes (SearchEntriesResult) + + + Body + + { + "entries": [ + { + "uuid": "a918fccf-4a94-4398-b260-4d792289952c", + "id": "13" + }, + { + "uuid": "ee1c8221-5ac2-465a-bcb8-2f329ba0da8a", + "id": "1391421694240" + } + ], + "search": { + "criteria": { + "domains": [ + "undefined domain", + "Technical_Names" + ] + } + }, + "totalResultCount": 2 +} From 2018d78a67031eaa21fbb1d91390f9156aba983b Mon Sep 17 00:00:00 2001 From: Robert Barbey Date: Tue, 11 Mar 2025 15:45:27 +0100 Subject: [PATCH 06/18] docs: added deletion of terms --- apiary.apib | 60 +++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 60 insertions(+) diff --git a/apiary.apib b/apiary.apib index 9c3bf293..8bad96c8 100644 --- a/apiary.apib +++ b/apiary.apib @@ -8079,6 +8079,66 @@ value of 4000 characters. "data": {} } +### Delete [DELETE] + +Entire entries can be removed by calling DELETE on +/entries/{entryUUID}. If an entry existed and could be deleted +successfully, the service returns 204 (No Content). Otherwise, if +there’s no entry under the specified UUID, the service returns 410 +(Gone). + +Required Privilege + +Terminology - Edit Terms + ++ Response 410 + +## Editing term entries [/iq/services/v9/rest/terminology/entries] + +### Create and update [PUT] + +Entries and their terms can be created and updated by POSTing the +respective ACTIF or SDL MultiTerm XML representation to /entries. +Whether an existing entry is updated or a new entry created crucially +depends on the entry UUID specified in the sent data. If the entry +UUID references an existing entry in the database, all terms and +fields of the entry will be replaced by the sent data. Specifically, +if the sent entry data contains fewer terms than the existing entry in +the database, those terms missing from the sent entry data will be +deleted. + +Otherwise, that is, no entry of the same UUID exists, a new entry will +be created. + +Supported media types are: + +* application/vnd.acrolinx.actif+xml: ACTIF in XML +* application/vnd.acrolinx.mtf+xml: SDL MultiTerm XML + +Required privileges: + +* Terminology - Import terms (implies "Edit terms") +* Terminology - Change the status of a term + +For both creation and update, the return code is 201 (created) and the +"Location" header gets the URL of the inserted/updated entry. If the +input data doesn't contain an entry that needs to be created or +updated, you'll see a 204 (no content). If the input data contains +more than one entry (which is allowed), all entries in the input data +will be created or updated respectively. However, the "Location" +header will only contain the URL of one of them. + ++ Request + + + Headers + + Authorization: session + ++ Response 200 (application/json) + + + Body + {} + ## Schema [/iq/services/v9/rest/terminology/schema] ### Get term base structure [GET] From b456ff97a8811c859a3cb865715dc2ec7451e967 Mon Sep 17 00:00:00 2001 From: Robert Barbey Date: Tue, 11 Mar 2025 15:45:46 +0100 Subject: [PATCH 07/18] docs: updated the doc to reflect v9 of the Term API --- apiary.apib | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/apiary.apib b/apiary.apib index 8bad96c8..e20ed3af 100644 --- a/apiary.apib +++ b/apiary.apib @@ -7825,7 +7825,7 @@ This will download data only with the fields `checkId`, `date`, `guidelineId` an "message": "Something went wrong. Try again or contact Acrolinx Support." } -# Group Terminology API v7 +# Group Terminology API v9 ## Deprecation Note From dd28cc1186fc5cea1f3f1c9c576ca43d86677114 Mon Sep 17 00:00:00 2001 From: Robert Barbey Date: Tue, 11 Mar 2025 15:46:22 +0100 Subject: [PATCH 08/18] docs: unified paths --- apiary.apib | 12 ++++++++---- 1 file changed, 8 insertions(+), 4 deletions(-) diff --git a/apiary.apib b/apiary.apib index e20ed3af..46cf2f54 100644 --- a/apiary.apib +++ b/apiary.apib @@ -7939,9 +7939,9 @@ path parameter. + Response 204 -## Term entries [/iq/services/v9/rest/terminology] +## Term entries [/iq/services/v9/rest/terminology/entries/{id}] -### Get by UUID or ID [GET /entries/{id}] +### Get by UUID or ID [GET] Supported media types: @@ -8188,7 +8188,9 @@ next section. }] } -## Search terms [POST /iq/services/v9/rest/terminology/searchTerms] +## Search terms [/iq/services/v9/rest/terminology/searchTerms] + +### by criteria [POST] Terms can be searched by: @@ -8311,7 +8313,9 @@ server will respond with a 400 (Bad Request). } -## Find terms [GET /iq/services/v9/rest/terminology/findTerms/{sessionId}] +## Find terms [/iq/services/v9/rest/terminology/findTerms/{sessionId}] + +### by criteria [POST] You can also search for terms using an older method called `findTerms,` which supports some search criteria that aren't available From 25092b942152835c52e1a46ebdff010d06e4b33b Mon Sep 17 00:00:00 2001 From: Robert Barbey Date: Tue, 11 Mar 2025 15:47:17 +0100 Subject: [PATCH 09/18] docs: improved formatting --- apiary.apib | 12 +++++++++++- 1 file changed, 11 insertions(+), 1 deletion(-) diff --git a/apiary.apib b/apiary.apib index 46cf2f54..8effd95b 100644 --- a/apiary.apib +++ b/apiary.apib @@ -8328,7 +8328,8 @@ The following search criteria are supported: * `language` id * `domain` - a single domain name * `entry` ID/UUID - an array of entry IDs or entry UUIDs -* custom `criteria` - an array of `field=value` strings, where field is one of the following ACTIF field names: +* custom `criteria` - an array of `field=value` strings, where field + is one of the following ACTIF field names: * `term/id` * `term/uuid` * `entry/id` @@ -8444,6 +8445,15 @@ Passing a nonempty array will get you all entries that contain at least one term that is assigned to at least one of the specified domains. Passing an empty array for domains will get you all entries. +The response is a JSON object with the following attributes: + +* `search` contains your search criteria +* `totalResultCount` is the total number of entries matching the + criterion +* `entries`: an array of entries, each containing the attributes `id`, + and `uuid`. Using the entry UUID or ID you can then retrieve the + entire entry via `GET /entries` (see above). + + Request + Attributes (SearchEntriesRequest) From 76e6a8fe721b9f0a6eb8bbba9439860558cf316d Mon Sep 17 00:00:00 2001 From: Robert Barbey Date: Tue, 11 Mar 2025 15:47:37 +0100 Subject: [PATCH 10/18] docs: added doc for deploying terminology --- apiary.apib | 26 ++++++++++++++++++++++++++ 1 file changed, 26 insertions(+) diff --git a/apiary.apib b/apiary.apib index 8effd95b..8a0be8d5 100644 --- a/apiary.apib +++ b/apiary.apib @@ -8493,3 +8493,29 @@ The response is a JSON object with the following attributes: }, "totalResultCount": 2 } + +## Deployment of Terminology [PUT /iq/services/v9/rest/terminology/deployTerminology] + +After terms and entries have been created or updated using the above +method, they're not immediately available for checking. To make the +new or updated terms available for checking, the terminology needs to +be "deployed". Currently, triggering a "deploy" of the terminology +just causes all running language servers to reload their language +configuration, which includes the loading of the terminology. Please +note that a language becomes unavailable for checking for a certain +amount of time up to several minutes. Therefore terminology +deployments should be scheduled for convenient times and not just done +after each term or entry update. + +You only need to (re)deploy terms/entries in domains and languages the +language configuration uses for checking. For instance, when you've +updated only the Arabic translation of a term, and there's no language +server running for Arabic, a "deploy" isn’t necessary. + ++ Request + + + Headers + + Authorization: session + ++ Response 204 From f4517fea9c26e235b0b721df2ee61c230108830b Mon Sep 17 00:00:00 2001 From: Robert Barbey Date: Tue, 11 Mar 2025 15:47:52 +0100 Subject: [PATCH 11/18] docs: added doc about uploading and downloading media files --- apiary.apib | 59 +++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 59 insertions(+) diff --git a/apiary.apib b/apiary.apib index 8a0be8d5..6acaa4e5 100644 --- a/apiary.apib +++ b/apiary.apib @@ -8519,3 +8519,62 @@ server running for Arabic, a "deploy" isn’t necessary. Authorization: session + Response 204 + +## Media files [/iq/services/v9/rest/terminology/media/{filename}] + +### Upload [POST] + +A multimedia object can be uploaded to the Core Platform specifying a +unique file name. We recommend using a scheme based on newly generated +UUIDs plus a readable part and the file extension. If an existing +filename is used, the old one will be replaced. + +To transfer a media file to the Core Platform the term API service, +call POST on /media/{finaName}. + +Supported media types are: + +image/*: all images types, for example, image/png, image/gif, etc. +application/pdf +Required privileges: + +Terminology - Import terms (implies "Edit terms") +Return codes: + +201 (Created) in the case of success. The Location header contains the URL of the uploaded content. +404 (Not Found) if the filename contains a /. + ++ Request + + + Headers + + Authorization: session + ++ Response 201 + + + Headers + + Location: koko + + +### Download [GET] + +A multimedia object that has been uploaded through this API can be +downloaded using the unique filename. To achieve this, call GET on +/media/{filename}. + +Required privileges: + +Terminology - Export terms (implies "Read terms") +Return codes: + +In case of success, 200 (OK) and the response body contains the media file. +404 (Not Found) if the filename doesn't exist. + ++ Request + + + Headers + + Authorization: session + ++ Response 200 From cd5ea1930f305cb25d5e31aaf6c7df783bf2107b Mon Sep 17 00:00:00 2001 From: Robert Barbey Date: Tue, 11 Mar 2025 16:02:14 +0100 Subject: [PATCH 12/18] docs: fixed linting issues with headers --- apiary.apib | 38 +++++++++++++++++++++----------------- 1 file changed, 21 insertions(+), 17 deletions(-) diff --git a/apiary.apib b/apiary.apib index 6acaa4e5..54a9f55f 100644 --- a/apiary.apib +++ b/apiary.apib @@ -7897,7 +7897,7 @@ release a session before acquiring a new session token. + Header - authToken: your_access_token + authToken: your_access_token + Body @@ -7933,7 +7933,7 @@ path parameter. + Headers - authToken: your_access_token + authToken: your_access_token + Response 204 @@ -7973,10 +7973,12 @@ value of 4000 characters. Either a single term entry ID or a comma-separated list of entry IDs. + Request ACTIF + + Headers - authToken: your_access_token - Authorization: session your_session_id - Accept: application/vnd.acrolinx.mtf+xml + + authToken: your_access_token + Authorization: session your_session_id + Accept: application/vnd.acrolinx.mtf+xml + Response 200 (application/vnd.acrolinx.actif+xml) @@ -8060,8 +8062,8 @@ value of 4000 characters. + Headers - Authorization: session your_session_id - Accept: application/vnd.acrolinx.mtf+xml + Authorization: session your_session_id + Accept: application/vnd.acrolinx.mtf+xml + Response 200 (application/vnd.acrolinx.mtf+xml) @@ -8132,7 +8134,7 @@ header will only contain the URL of one of them. + Headers - Authorization: session + Authorization: session + Response 200 (application/json) @@ -8149,8 +8151,8 @@ Retrieves the structure of the Acrolinx term base. + Headers - Authorization: session your_session_id - Accept: application/vnd.acrolinx.actif+xml + Authorization: session your_session_id + Accept: application/vnd.acrolinx.actif+xml + Response 200 (application/vnd.acrolinx.actif+xml) @@ -8171,7 +8173,7 @@ next section. + Headers - Authorization: session your_session_id + Authorization: session your_session_id + Response 200 (application/json) @@ -8264,8 +8266,10 @@ server will respond with a 400 (Bad Request). + Request + + Header - Authorization: session your_session_id + + Authorization: session your_session_id + Attributes (SearchRequest) @@ -8375,7 +8379,7 @@ true. + Headers - Content-Type: application/json + Content-Type: application/json + Response 200 (text/plain) @@ -8460,7 +8464,7 @@ The response is a JSON object with the following attributes: + Headers - Authorization: session + Authorization: session + Body @@ -8516,7 +8520,7 @@ server running for Arabic, a "deploy" isn’t necessary. + Headers - Authorization: session + Authorization: session + Response 204 @@ -8548,13 +8552,13 @@ Return codes: + Headers - Authorization: session + Authorization: session + Response 201 + Headers - Location: koko + Location: koko ### Download [GET] From 2a4c1bcc547983fcadf16a1977d3a7572c4ad2dc Mon Sep 17 00:00:00 2001 From: Robert Barbey Date: Wed, 12 Mar 2025 10:25:19 +0100 Subject: [PATCH 13/18] docs: formatting --- apiary.apib | 990 +++++++++++++++++++++++++++++++++++++++++----------- 1 file changed, 788 insertions(+), 202 deletions(-) diff --git a/apiary.apib b/apiary.apib index 54a9f55f..b3e7f7ae 100644 --- a/apiary.apib +++ b/apiary.apib @@ -7901,20 +7901,20 @@ release a session before acquiring a new session token. + Body - { - "sessionType": "TERMINOLOGY", - "clientSignature": "SW50ZWdyYXRpb25EZXZlbG9wbWVudERlbW9Pbmx5", - "clientInfo": { - "buildNumber": "unknown", - "clientHostname": "localhost", - "version": "0.1", - "name": "Terminology Test Client", - "clientHostApplication": "unknown", - "clientLoginName": "unknown" + { + "sessionType": "TERMINOLOGY", + "clientSignature": "SW50ZWdyYXRpb25EZXZlbG9wbWVudERlbW9Pbmx5", + "clientInfo": { + "buildNumber": "unknown", + "clientHostname": "localhost", + "version": "0.1", + "name": "Terminology Test Client", + "clientHostApplication": "unknown", + "clientLoginName": "unknown" + } } - } -+ Response (200 text/plain) ++ Response 200 (text/plain) 56429c06fbd5da74 @@ -7968,7 +7968,7 @@ value of 4000 characters. + Parameters - + id: (required, string) + + id: `7bd1ee3f-8e46-4a1f-bd45-a3c18981f731` (required, string) Either a single term entry ID or a comma-separated list of entry IDs. @@ -7984,79 +7984,79 @@ value of 4000 characters. + Body - - - - - - - - en - - - red - foggy - cold - cloudy - 077061bc-d9ab-455d-a078-bb1fb648440e_f2f455eb5898c6568524f6ca87236342.jpg - 1309938647786 - 459a8ff0-dfab-49d6-927f-6c456f194168 - - - 802.11n technology - en - preferred - D-Link - 6183eceb-33e4-4b5e-b721-0ac34eb78fb4 - 1309883915302 - 0 - 2011-07-06T08:02:35.383Z - admin - 2024-06-26T14:38:51.230Z - peter.bernds@acrolinx.com - unprocessed - undefined - undefined - undefined - - string - - - - - 802.11 network switch - en - preferred - Belkin - 077061bc-d9ab-455d-a078-bb1fb648440e - 1309883964051 - 0 - 2011-07-06T08:15:24.073Z - admin - 2024-06-26T14:38:51.342Z - peter.bernds@acrolinx.com - unprocessed - light red - undefined - undefined - undefined - - base (analyzed) - network - 1 - noun - - - admin - 2016-11-21T17:01:51.887Z - COMMENT - ttt - - - - - - + + + + + + + + en + + + red + foggy + cold + cloudy + 077061bc-d9ab-455d-a078-bb1fb648440e_f2f455eb5898c6568524f6ca87236342.jpg + 1309938647786 + 459a8ff0-dfab-49d6-927f-6c456f194168 + + + 802.11n technology + en + preferred + D-Link + 6183eceb-33e4-4b5e-b721-0ac34eb78fb4 + 1309883915302 + 0 + 2011-07-06T08:02:35.383Z + admin + 2024-06-26T14:38:51.230Z + peter.bernds@acrolinx.com + unprocessed + undefined + undefined + undefined + + string + + + + + 802.11 network switch + en + preferred + Belkin + 077061bc-d9ab-455d-a078-bb1fb648440e + 1309883964051 + 0 + 2011-07-06T08:15:24.073Z + admin + 2024-06-26T14:38:51.342Z + peter.bernds@acrolinx.com + unprocessed + light red + undefined + undefined + undefined + + base (analyzed) + network + 1 + noun + + + admin + 2016-11-21T17:01:51.887Z + COMMENT + ttt + + + + + + + Request SDL Multiterm format @@ -8069,22 +8069,376 @@ value of 4000 characters. + Body - 13a918fccf-4a94-4398-b260-4d792289952cadmin2011-06-28T11:55:28+02:00admin2014-02-03T11:00:04return airpreferredTechnical_Namesundefined domain120bdf01-4818-4a2c-bcea-4f875b6b129a13711976956060undefinedundefinedundefinedunprocessedundefinedadmin2011-06-28T11:55:28+02:00admin2014-02-03T11:00:04text nicht vorhandenproposedundefined domain680e0ea1-90f1-48ab-9ec9-5a362360692d13711976956220undefinedundefinedundefinedunprocessedundefinedadmin2011-06-28T12:11:20+02:00marco.aeschimann@ch.sauter-bc.com2011-07-05T10:54:28+02:00text nicht vorhandenproposedundefined domain01352af7-73e6-4024-9433-930846681b5613711976956300undefinedundefinedundefinedunprocessedundefinedadmin2011-06-28T12:11:19+02:00eric.schneider@ch.sauter-bc.com2011-09-13T10:47:25+02:00AbluftmengeproposedTechnical_Namesundefined domain44641d47-ddf3-4bb4-b1d4-a22a3fb42f6413711976956460undefinedundefinedundefinedunprocessedundefinedadmin2011-06-28T11:55:28+02:00admin2014-02-03T10:59:47débit d'air reprispreferredTechnical_Namesundefined domain5334a674-848b-44a3-8b42-1756d38717ef13711976956140undefinedundefinedundefinedunprocessedundefinedadmin2011-06-28T11:55:28+02:00admin2014-02-03T10:59:54débit d'évacuationdeprecatedTechnical_Namesundefined domain38e4ce12-4175-465e-a26f-4bb6d8a7ea1513711976956540undefinedundefinedundefinedunprocessedundefinedadmin2011-06-28T11:55:28+02:00admin2014-02-03T10:59:58text nicht vorhandenproposedundefined domain7958d666-8511-4c0e-aef1-d0f4748d2d4613711976956380undefinedundefinedundefinedunprocessedundefinedadmin2011-06-28T12:11:18+02:00admin2011-08-30T11:55:38+02:00 + + + + 13 + + a918fccf-4a94-4398-b260-4d792289952c + + + admin + 2011-06-28T11:55:28+02:00 + + + admin + 2014-02-03T11:00:04 + + + + + return air + + preferred + + + Technical_Names + + + undefined domain + + + 120bdf01-4818-4a2c-bcea-4f875b6b129a + + + 1371197695606 + + + 0 + + + undefined + + + undefined + + + undefined + + + unprocessed + + + undefined + + + + + + admin + 2011-06-28T11:55:28+02:00 + + + admin + 2014-02-03T11:00:04 + + + + + + + text nicht vorhanden + + proposed + + + undefined domain + + + 680e0ea1-90f1-48ab-9ec9-5a362360692d + + + 1371197695622 + + + 0 + + + undefined + + + undefined + + + undefined + + + unprocessed + + + undefined + + + + + + admin + 2011-06-28T12:11:20+02:00 + + + peter.bernds@acrolinx.com + 2011-07-05T10:54:28+02:00 + + + + + + + text nicht vorhanden + + proposed + + + undefined domain + + + 01352af7-73e6-4024-9433-930846681b56 + + + 1371197695630 + + + 0 + + + undefined + + + undefined + + + undefined + + + unprocessed + + + undefined + + + + + + admin + 2011-06-28T12:11:19+02:00 + + + peter.bernds@acrolinx.com + 2011-09-13T10:47:25+02:00 + + + + + + + Abluftmenge + + proposed + + + Technical_Names + + + undefined domain + + + 44641d47-ddf3-4bb4-b1d4-a22a3fb42f64 + + + 1371197695646 + + + 0 + + + undefined + + + undefined + + + undefined + + + unprocessed + + + undefined + + + + + + admin + 2011-06-28T11:55:28+02:00 + + + admin + 2014-02-03T10:59:47 + + + + + + + débit d'air repris + + preferred + + + Technical_Names + + + undefined domain + + + 5334a674-848b-44a3-8b42-1756d38717ef + + + 1371197695614 + + + 0 + + + undefined + + + undefined + + + undefined + + + unprocessed + + + undefined + + + + + + admin + 2011-06-28T11:55:28+02:00 + + + admin + 2014-02-03T10:59:54 + + + + débit d'évacuation + + deprecated + + + Technical_Names + + + undefined domain + + + 38e4ce12-4175-465e-a26f-4bb6d8a7ea15 + + + 1371197695654 + + + 0 + + + undefined + + + undefined + + + undefined + + + unprocessed + + + undefined + + + + + + admin + 2011-06-28T11:55:28+02:00 + + + admin + 2014-02-03T10:59:58 + + + + + + + text nicht vorhanden + + proposed + + + undefined domain + + + 7958d666-8511-4c0e-aef1-d0f4748d2d46 + + + 1371197695638 + + + 0 + + + undefined + + + undefined + + + undefined + + + unprocessed + + + undefined + + + + + + admin + 2011-06-28T12:11:18+02:00 + + + admin + 2011-08-30T11:55:38+02:00 + + + + + + Response 406 + Body - { - "error": "No terminology export transformation stylesheet available for 'application/vnd.acrolinx.mtf+xml'", - "code": "cantServeRequestedMediaType", - "data": {} - } + { + "error": "No terminology export transformation stylesheet available for 'application/vnd.acrolinx.mtf+xml'", + "code": "cantServeRequestedMediaType", + "data": {} + } ### Delete [DELETE] Entire entries can be removed by calling DELETE on -/entries/{entryUUID}. If an entry existed and could be deleted +`/entries/{entryUUID}`. If an entry existed and could be deleted successfully, the service returns 204 (No Content). Otherwise, if there’s no entry under the specified UUID, the service returns 410 (Gone). @@ -8139,7 +8493,8 @@ header will only contain the URL of one of them. + Response 200 (application/json) + Body - {} + + {} ## Schema [/iq/services/v9/rest/terminology/schema] @@ -8158,7 +8513,242 @@ Retrieves the structure of the Acrolinx term base. + Body - enen-JPen-USen-GBdejazhzh-CNzh-TWarfritkoruessvmulnobgcsnlptsprachesub1sub2truefalsestringbase (analyzed)adjectiveadverbnounotherproper nounundefinedverballnounverbadjectiveadverbadpositionprepositiondeterminerconjunctionpronounprefixsuffixNew_WordsPlain_EnglishSmart Techundefined domaineven more undefinedcustomerex customerSpecial SymbolsDemoSwitchesKeitaidenwaKanaKanjiUsageADSLMFPDruckerAcrolinxStandard_TerminologyRoutersBelkinD-LinkCiscoPhoneASD-STE100Technical_NamesTN_1_Official_Parts_InformationTN_2_Locations_On_Machines_Vehicles_Or_EquipmentTN_3_Tools_Or_EquipmentTN_4_Materials_Consumables_Or_Unwanted_MatterTN_5_Facilities_And_InfrastructureTN_6_Circuits_Or_SystemsTN_7_Mathematical_Scientific_Or_Engineering_TermsTN_8_NavigationTN_9_Numbers_Units_Of_Measurement_Or_Dial_MarkingsTN_10_Quoted_TextTN_11_Persons_Groups_Or_BodiesTN_12_Body_PartsTN_13_Common_Personal_EffectsTN_14_Medical_TermsTN_15_Documents_Or_ManualsTN_16_Names_Headings_And_Topics_In_SpecificationsTN_17_Technical_Records_Standards_Specifications_Or_RegulationsTN_18_Environmental_ConditionsTN_19_ColorsTN_20_Damage_TermsTN_UnclassifiedTechnical_VerbsTV_1_Manufacturing_ProcessesTV_2_Computer_Processes_And_ApplicationsTV_3_DescriptionsTV_UnclassifiedS1000D Bike Data SetDental Floss Tycoonproposedproposed_from_searchdeprecatedadmittedpreferrednon-termstopwordno-single-termundefinedwamcoldsunnycloudyfoggyrainyhotunprocessedprovisionally processedfinalizedreview requestedundefinedmasculinefeminineneuterotherundefinedfull formacronymabbreviationshort formvariantphraseundefinedredlight reddark redcarmesingreenblueyellowundefinedhotblueproposedundefined domainunprocesseddark redundefinedundefinedundefined + + + + + + + + + en + en-JP + en-US + en-GB + de + ja + zh + zh-CN + zh-TW + ar + fr + it + ko + ru + es + sv + mul + no + bg + cs + nl + pt + sprache + sub1 + sub2 + + + true + false + + + string + base (analyzed) + + + adjective + adverb + noun + other + proper noun + undefined + verb + + + all + noun + verb + adjective + adverb + adposition + preposition + determiner + conjunction + pronoun + prefix + suffix + + + New_Words + Plain_English + Smart Tech + undefined domain + even more undefined + customer + ex customer + Special Symbols + Demo + Switches + Keitaidenwa + KanaKanjiUsage + ADSL + MFP + Drucker + Acrolinx + Standard_Terminology + Routers + Belkin + D-Link + Cisco + Phone + ASD-STE100 + Technical_Names + TN_1_Official_Parts_Information + TN_2_Locations_On_Machines_Vehicles_Or_Equipment + TN_3_Tools_Or_Equipment + TN_4_Materials_Consumables_Or_Unwanted_Matter + TN_5_Facilities_And_Infrastructure + TN_6_Circuits_Or_Systems + TN_7_Mathematical_Scientific_Or_Engineering_Terms + TN_8_Navigation + TN_9_Numbers_Units_Of_Measurement_Or_Dial_Markings + TN_10_Quoted_Text + TN_11_Persons_Groups_Or_Bodies + TN_12_Body_Parts + TN_13_Common_Personal_Effects + TN_14_Medical_Terms + TN_15_Documents_Or_Manuals + TN_16_Names_Headings_And_Topics_In_Specifications + TN_17_Technical_Records_Standards_Specifications_Or_Regulations + TN_18_Environmental_Conditions + TN_19_Colors + TN_20_Damage_Terms + TN_Unclassified + Technical_Verbs + TV_1_Manufacturing_Processes + TV_2_Computer_Processes_And_Applications + TV_3_Descriptions + TV_Unclassified + S1000D Bike Data Set + Dental Floss Tycoon + + + proposed + proposed_from_search + deprecated + admitted + preferred + non-term + stopword + no-single-term + + + undefined + wam + cold + sunny + cloudy + foggy + rainy + hot + + + unprocessed + provisionally processed + finalized + review requested + + + undefined + masculine + feminine + neuter + other + + + undefined + full form + acronym + abbreviation + short form + variant + phrase + + + undefined + red + light red + dark red + carmesin + green + blue + yellow + + + undefined + + + + + + + + + + + hot + + + + blue + + + + + proposed + + + undefined domain + + + + + + + + + + + + + + + unprocessed + + + dark red + + + undefined + + + + + + + undefined + + + + + + + undefined + + + + + ## Filters [/iq/services/v9/rest/terminology/filters] @@ -8179,16 +8769,16 @@ next section. + Body - { - "user": "admin", - "filters": [{ - "id": "Preferred Technical Names" + { + "user": "admin", + "filters": [{ + "id": "Preferred Technical Names" }, { - "id": "SEO" + "id": "SEO" }, { - "id": "Images" - }] - } + "id": "Images" + }] + } ## Search terms [/iq/services/v9/rest/terminology/searchTerms] @@ -8274,47 +8864,49 @@ server will respond with a 400 (Bad Request). + Attributes (SearchRequest) + Body - {} + + {} + Response 200 (application/json) + Attributes (SearchResult) + Body - { - "terms": [{ - "name": "debit d\u0027air repris", - "status": "preferred", - "domains": ["Technical_Names", "undefined domain"], - "uuid": "5334a674-848b-44a3-8b42-1756d38717ef", - "entry": { - "uuid": "a918fccf-4a94-4398-b260-4d792289952c", - "id": "13" - } - }, { - "name": "debit d\u0027évacuation", - "status": "deprecated", - "domains": ["Technical_Names", "undefined domain"], - "uuid": "38e4ce12-4175-465e-a26f-4bb6d8a7ea15", - "entry": { - "uuid": "a918fccf-4a94-4398-b260-4d792289952c", - "id": "13" - } - }], - "search": { - "pagination": { - "offset": 0, - "limit": -1 - }, - "criteria": { - "name": "d%", - "language": "fr", - "filter": null, - "domains": ["undefined domain","Technical Names"] - } + + { + "terms": [{ + "name": "debit d\u0027air repris", + "status": "preferred", + "domains": ["Technical_Names", "undefined domain"], + "uuid": "5334a674-848b-44a3-8b42-1756d38717ef", + "entry": { + "uuid": "a918fccf-4a94-4398-b260-4d792289952c", + "id": "13" + } + }, { + "name": "debit d\u0027évacuation", + "status": "deprecated", + "domains": ["Technical_Names", "undefined domain"], + "uuid": "38e4ce12-4175-465e-a26f-4bb6d8a7ea15", + "entry": { + "uuid": "a918fccf-4a94-4398-b260-4d792289952c", + "id": "13" + } + }], + "search": { + "pagination": { + "offset": 0, + "limit": -1 }, - "totalResultCount": 2 - } + "criteria": { + "name": "d%", + "language": "fr", + "filter": null, + "domains": ["undefined domain","Technical Names"] + } + }, + "totalResultCount": 2 + } ## Find terms [/iq/services/v9/rest/terminology/findTerms/{sessionId}] @@ -8385,49 +8977,49 @@ true. + Body - - - - - en - - undefined - 1307356662917 - ff61f9ce-9c23-4874-bb98-cc58456b8734 - - - 2-Loch-Buchse - de - preferred - ADSL - 6c2b681c-0d2f-4820-9833-8b2d35ab6fe8 - 22946 - 0 - 2011-06-06T10:37:42.963Z - admin - 2024-06-26T14:38:51.282Z - peter.bernds@acrolinx.com - finalized - undefined - undefined - undefined - - base (analyzed) - 2-Loch-Buchse - 1 - noun - - - peter.bernds@acrolinx.com - 2024-06-25T13:51:47.671Z - COMMENT - Test - - - - - - + + + + + en + + undefined + 1307356662917 + ff61f9ce-9c23-4874-bb98-cc58456b8734 + + + 2-Loch-Buchse + de + preferred + ADSL + 6c2b681c-0d2f-4820-9833-8b2d35ab6fe8 + 22946 + 0 + 2011-06-06T10:37:42.963Z + admin + 2024-06-26T14:38:51.282Z + peter.bernds@acrolinx.com + finalized + undefined + undefined + undefined + + base (analyzed) + 2-Loch-Buchse + 1 + noun + + + peter.bernds@acrolinx.com + 2024-06-25T13:51:47.671Z + COMMENT + Test + + + + + + ## Search entries [POST /iq/services/v9/rest/terminology/searchEntries] @@ -8468,7 +9060,7 @@ The response is a JSON object with the following attributes: + Body - {"criteria":{"domains":["undefined domain", "Technical_Names"]}} + {"criteria":{"domains":["undefined domain", "Technical_Names"]}} + Response 200 (application/json) @@ -8476,27 +9068,21 @@ The response is a JSON object with the following attributes: + Body - { - "entries": [ - { - "uuid": "a918fccf-4a94-4398-b260-4d792289952c", - "id": "13" - }, - { - "uuid": "ee1c8221-5ac2-465a-bcb8-2f329ba0da8a", - "id": "1391421694240" - } - ], - "search": { - "criteria": { - "domains": [ - "undefined domain", - "Technical_Names" - ] - } - }, - "totalResultCount": 2 -} + { + "entries": [{ + "uuid": "a918fccf-4a94-4398-b260-4d792289952c", + "id": "13" + }, { + "uuid": "ee1c8221-5ac2-465a-bcb8-2f329ba0da8a", + "id": "1391421694240" + }], + "search": { + "criteria": { + "domains": ["undefined domain", "Technical_Names"] + } + }, + "totalResultCount": 2 + } ## Deployment of Terminology [PUT /iq/services/v9/rest/terminology/deployTerminology] From 5ebc739d7eca8e572d38c9075129a2d93a4a4961 Mon Sep 17 00:00:00 2001 From: Robert Barbey Date: Wed, 12 Mar 2025 11:09:14 +0100 Subject: [PATCH 14/18] docs: restructured session methods --- apiary.apib | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/apiary.apib b/apiary.apib index b3e7f7ae..6a35a82b 100644 --- a/apiary.apib +++ b/apiary.apib @@ -7859,7 +7859,7 @@ correct setting of the standard HTTP `Content-Type` header. The supported media types are listed where applicable. -## Authentication and Authorization +## Authentication and Authorization [/iq/services/v3/rest/core] Before invoking any Terminology API, the Acrolinx Integration must authorize and acquire a session. The authorization itself isn’t part @@ -7880,7 +7880,7 @@ response: For all terminology service API methods, the user must have at least the `Access API-based terminology applications` privilege. -### Acquiring a Session [POST /iq/services/v3/rest/core/requestSession] +### Acquiring a Session [POST /requestSession] Using the authentication token, the integration now needs to open a session, specifying the session-type (always `TERMINOLOGY` for usage @@ -7919,7 +7919,7 @@ release a session before acquiring a new session token. 56429c06fbd5da74 -### Releasing a Session [DELETE /iq/services/v3/rest/core/requestSession/{id}] +### Releasing a Session [DELETE /requestSession/{id}] A session can be released by a `DELETE` on `/iq/services/v3/rest/core/releaseSession`, providing the session as @@ -7950,7 +7950,7 @@ Supported media types: Required privilege: -- Terminology - View Terms +- Terminology View Terms This functionality is provided by `GET` `/entries`. There are two variants of this operation: From 0c83641b9ab15ca0cfb85be65ab67a5b01beb539 Mon Sep 17 00:00:00 2001 From: Robert Barbey Date: Thu, 13 Mar 2025 17:24:22 +0100 Subject: [PATCH 15/18] feat: added action to build, upload and deploy docs --- .github/workflows/publish.yml | 42 +++++++++++++++++++++++++++++++++++ 1 file changed, 42 insertions(+) create mode 100644 .github/workflows/publish.yml diff --git a/.github/workflows/publish.yml b/.github/workflows/publish.yml new file mode 100644 index 00000000..59758be1 --- /dev/null +++ b/.github/workflows/publish.yml @@ -0,0 +1,42 @@ +--- +name: Build and publish API docs + +on: + workflow_dispatch: + +jobs: + build: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - name: Set up Ruby + uses: ruby/setup-ruby@ec02537da5712d66d4d50a0f33b7eb52773b5ed1 + with: + ruby-version: 3.3.5 + - name: Install apiary gem + run: gem install apiaryio + - name: Build apiary docs + run: | + mkdir public + apiary preview --output public/index.html + - name: Upload static files + uses: actions/upload-pages-artifact@v3 + with: + path: public/ + + deploy: + needs: build + + permissions: + pages: write + id-token: write + + environment: + name: github-pages + url: ${{ steps.deployment.outputs.page_url }} + + runs-on: ubuntu-latest + steps: + - name: Dpeloy to GitHub Pages + id: deployment + uses: actions/deploy-pages@v4 From a52d3be344e8bb495ef07af8d91c07877f616845 Mon Sep 17 00:00:00 2001 From: Sam Ford Date: Thu, 24 Apr 2025 13:11:21 +0100 Subject: [PATCH 16/18] docs: Remove 404 response from delete user docs, as we now return 204 even if the user did not exist in the first place --- apiary.apib | 14 -------------- 1 file changed, 14 deletions(-) diff --git a/apiary.apib b/apiary.apib index 6a35a82b..9db63c96 100644 --- a/apiary.apib +++ b/apiary.apib @@ -3965,20 +3965,6 @@ To read more about managing users and built-in users, see [User Management](http } } -+ Response 404 (application/json) - - // when the user wasn't found in the database based on its *id* - { - "links": {}, - "error": { - "reference": "e49d3cd5-330a-408d-84a1-e9ecf20677bf", - "detail": "An unspecific client error occurred.", - "type": "client", - "title": "Not Found", - "status": 404 - } - } - + Response 409 (application/json) // when you can't delete a user From 4a46008042b9343325f4d0c25214fa9a6ffb81fe Mon Sep 17 00:00:00 2001 From: Robert Barbey Date: Mon, 8 Sep 2025 10:12:12 +0200 Subject: [PATCH 17/18] chore: remove GH actions - we currently have no plans to change the publishing method for these API docs so we're removing the stub GH actions --- .github/dependabot.yml | 11 ------ .github/workflows/dependabot-auto-merge.yml | 22 ----------- .github/workflows/publish.yml | 42 --------------------- .github/workflows/run-lint.yml | 21 ----------- 4 files changed, 96 deletions(-) delete mode 100644 .github/dependabot.yml delete mode 100644 .github/workflows/dependabot-auto-merge.yml delete mode 100644 .github/workflows/publish.yml delete mode 100644 .github/workflows/run-lint.yml diff --git a/.github/dependabot.yml b/.github/dependabot.yml deleted file mode 100644 index b183e62f..00000000 --- a/.github/dependabot.yml +++ /dev/null @@ -1,11 +0,0 @@ -version: 2 -updates: - - package-ecosystem: "github-actions" - directory: "/" - schedule: - interval: "daily" - - package-ecosystem: "npm" - directory: "/" - schedule: - interval: "daily" - versioning-strategy: increase diff --git a/.github/workflows/dependabot-auto-merge.yml b/.github/workflows/dependabot-auto-merge.yml deleted file mode 100644 index 68098e88..00000000 --- a/.github/workflows/dependabot-auto-merge.yml +++ /dev/null @@ -1,22 +0,0 @@ -name: Dependabot auto-merge -on: pull_request - -permissions: - contents: write - pull-requests: write - -jobs: - dependabot: - runs-on: ubuntu-latest - if: ${{ github.actor == 'dependabot[bot]' }} - steps: - - name: Dependabot metadata - id: metadata - uses: dependabot/fetch-metadata@v2 - with: - github-token: '${{ secrets.GITHUB_TOKEN }}' - - name: Enable auto-merge for Dependabot PRs - run: gh pr merge --auto --squash "$PR_URL" - env: - PR_URL: ${{github.event.pull_request.html_url}} - GITHUB_TOKEN: ${{secrets.GITHUB_TOKEN}} diff --git a/.github/workflows/publish.yml b/.github/workflows/publish.yml deleted file mode 100644 index 59758be1..00000000 --- a/.github/workflows/publish.yml +++ /dev/null @@ -1,42 +0,0 @@ ---- -name: Build and publish API docs - -on: - workflow_dispatch: - -jobs: - build: - runs-on: ubuntu-latest - steps: - - uses: actions/checkout@v4 - - name: Set up Ruby - uses: ruby/setup-ruby@ec02537da5712d66d4d50a0f33b7eb52773b5ed1 - with: - ruby-version: 3.3.5 - - name: Install apiary gem - run: gem install apiaryio - - name: Build apiary docs - run: | - mkdir public - apiary preview --output public/index.html - - name: Upload static files - uses: actions/upload-pages-artifact@v3 - with: - path: public/ - - deploy: - needs: build - - permissions: - pages: write - id-token: write - - environment: - name: github-pages - url: ${{ steps.deployment.outputs.page_url }} - - runs-on: ubuntu-latest - steps: - - name: Dpeloy to GitHub Pages - id: deployment - uses: actions/deploy-pages@v4 diff --git a/.github/workflows/run-lint.yml b/.github/workflows/run-lint.yml deleted file mode 100644 index 8123f3bd..00000000 --- a/.github/workflows/run-lint.yml +++ /dev/null @@ -1,21 +0,0 @@ -name: Lint API Blueprint - -on: [push] - -jobs: - build: - runs-on: ubuntu-latest - - steps: - - name: Checkout - uses: actions/checkout@v4 - - - name: Setup Node - uses: actions/setup-node@v4 - with: - node-version: 20 - - - name: Install dependencies - run: npm ci - - - run: npm run lint From bb0dc3442c69bc1bda97d5cafc1c075fcebfa159 Mon Sep 17 00:00:00 2001 From: Robert Barbey Date: Fri, 7 Nov 2025 09:10:04 +0100 Subject: [PATCH 18/18] docs: added link to new home for Term API --- term-api.md | 5 +++++ 1 file changed, 5 insertions(+) create mode 100644 term-api.md diff --git a/term-api.md b/term-api.md new file mode 100644 index 00000000..adc58ecf --- /dev/null +++ b/term-api.md @@ -0,0 +1,5 @@ +# Terminology API + +This document has moved and is now part of the [Platform API documentation +hosted on +Apiary](https://acrolinxapi.docs.apiary.io/#reference/terminology-api-v9)