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/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 diff --git a/apiary.apib b/apiary.apib index 0dede0ad..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 @@ -7148,6 +7134,54 @@ 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) + +## 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) + +### 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. @@ -7776,3 +7810,1347 @@ 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 v9 + +## Deprecation Note + +**Warning:** Communication using the SDL *MultiTerm XML* format is +deprecated. While it still works today, support can be removed at any +time. + +## Configuration + +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. + +The availability of those resources can be checked in the Acrolinx +dashboard on `Style -> Term import and 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. + +## 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 +of the Terminology API. API requests without a valid session ID in the +`Authorization` HTTP header field fail with a `403 Forbbiden` +response: + +``` +{ + "message": "Invalid session (no such session)", + "errors": { + "exception_type": "com.acrolinx.services.faults.InvalidSessionFault", + "exception_message": "Invalid session (no such session)" + } +} +``` + +For all terminology service API methods, the user must have at least +the `Access API-based terminology applications` privilege. + +### 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 +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. + ++ Request + + + Header + + authToken: your_access_token + + + Body + + { + "sessionType": "TERMINOLOGY", + "clientSignature": "SW50ZWdyYXRpb25EZXZlbG9wbWVudERlbW9Pbmx5", + "clientInfo": { + "buildNumber": "unknown", + "clientHostname": "localhost", + "version": "0.1", + "name": "Terminology Test Client", + "clientHostApplication": "unknown", + "clientLoginName": "unknown" + } + } + ++ Response 200 (text/plain) + + 56429c06fbd5da74 + + +### 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 +path parameter. + ++ Parameters + + + id: `56429c06fbd5da74z` (required, string) - session ID + ++ Request + + + Headers + + authToken: your_access_token + + ++ Response 204 + + +## Term entries [/iq/services/v9/rest/terminology/entries/{id}] + +### Get by UUID or ID [GET] + +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. 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. + +**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. + ++ Parameters + + + id: `7bd1ee3f-8e46-4a1f-bd45-a3c18981f731` (required, string) + + 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 + ++ Response 200 (application/vnd.acrolinx.actif+xml) + + + 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 + + + + + + + ++ Request SDL Multiterm format + + + Headers + + Authorization: session your_session_id + Accept: application/vnd.acrolinx.mtf+xml + ++ Response 200 (application/vnd.acrolinx.mtf+xml) + + + Body + + + + + 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": {} + } + +### 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] + +Retrieves the structure of the Acrolinx term base. + ++ Request + + + Headers + + Authorization: session your_session_id + Accept: application/vnd.acrolinx.actif+xml + ++ Response 200 (application/vnd.acrolinx.actif+xml) + + + Body + + + + + + + + + + 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] + +### Get available filters [GET] + +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. + ++ Request + + + Headers + + Authorization: session your_session_id + ++ Response 200 (application/json) + + + Body + + { + "user": "admin", + "filters": [{ + "id": "Preferred Technical Names" + }, { + "id": "SEO" + }, { + "id": "Images" + }] + } + +## Search terms [/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 [/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 +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 + + + + + + + +## 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. + +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) + + + 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 + } + +## 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 + +## 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 diff --git a/term-api.md b/term-api.md index 374dfb54..adc58ecf 100644 --- a/term-api.md +++ b/term-api.md @@ -1,699 +1,5 @@ -# Acrolinx Terminology API v7 +# Terminology API -## 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`? -``` +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)