First Request Examples

The following examples will demonstrate how to search for a term by text, check its usage status, and edit the term text together with releasing it. Similarly, you can search, create, and edit any other terminology data.

The complete list of available methods for your Across version is available on your ALS installation at http://sitename/Across/crossTerm/, and the latest version can be downloaded here.

Search for Term by Text String

This example shows how to search for a term which matches the search string.

Tip

Note that there are also other possibilities to search for terminology, including wildcard search and search terms in text. To take a deeper look into them, check Searching Terminology via API.

The example query below will return all the terms with same stem as "application" on the language English - United States (LCID is 1033).

Method	POST
Request URL	http://localhost/Across/crossTerm/api/v2/Terms/Across.Services.CrossTerm.Api.V2.SearchTerms?$expand=FoundTerms
Request body	{ "query": { "TermNames": [ "application" ], "Parameters": { "SourceLanguage": 1033, "UseStemming": true } } }
Response	{ "@odata.context": "http://localhost/Across/crossTerm/api/v2/$metadata#TermsSearchResults", "value": [ { "Index": 0, "Count": 1, "Range": null, "FoundTerms": [ { "Id": 7, "Guid": "10a9a6e1-06b9-43ea-8984-08ba245d9633", "IsRawData": false, "Name": "application", "State": "Unreleased", "Created": "2019-07-18T07:58:05Z", "CreatorId": "e0946da0-64c4-42b6-9f02-94bb1774917b", "Modified": "2019-07-18T08:04:49.133Z", "ModifierId": "e0946da0-64c4-42b6-9f02-94bb1774917b", "EntryId": 3, "LanguageId": { "PrimaryLangId": 9, "SubLangId": 1 } } ] } ] }

Check Usage Status

crossTerm instances typically have a data category at term level which represents information on usage (standardization: should this term be used or not?). It is a picklist data category, the values of which are defined by special Usage flags. These flags are Recommended (term is preferred) and DoNotUse (term should not be used).

Tip

If a term was identified that should be avoided, it might be interesting to retrieve other terms of the same entry which could be used instead. To do that, refer to Finding Terms of Entry.

Example

The query for api/v2/Instances(key)/DataCategories will contain the description of this data category, among others.

"@odata.type": "#Across.Services.CrossTerm.Api.V2.PicklistDataCategory", "Id": 21, "Guid": "7d81fc02-184c-4d64-8241-d97d9454afbf", "Name": "Usage", "AllowMultipleValues": false, "Scope": "Term", "InstanceId": 1, "ParentId": null, 
     "Values": [ 
       { "Id": 45, "Guid": "8d7c76c5-9f0c-49e3-a59a-ac28db986212", "TextLong": "standard", "TextShort": "standard","Usage": "Recommended", "IsDefault": false, "DataCategoryId": 21 }, 
       { "Id": 46, "Guid": "2e087bdc-579f-4a56-b573-a549480cb628", "TextLong": "synonym", "TextShort": "syn", "Usage": "Normal", "IsDefault": false, "DataCategoryId": 21 }, 
       { "Id": 47, "Guid": "9cfd8dc8-8d9e-408e-a264-8aedc00e90be", "TextLong": "do not use", "TextShort": "do not use", "Usage": "DoNotUse", "IsDefault": false, "DataCategoryId": 21 } 
     ]

This information shows which properties of terms should be interpreted if the application is interested in usage information: It is the data category Usage.

Tip

Theoretically, more than one picklist at term level may have values with the flags Recommended and/or DoNotUse. However, in practice, there is usually only one such picklist, and all values of all other picklists have "Usage": "Normal".

The query for api/v2/Terms(key)/Properties will contain all properties of the term with this key. These are instantiations of data categories, for example of the Usage data category. In the following result example, we see that also at this level, the Usage flag is represented for each Property. To add their values as well, use api/v2/Terms(key)/Properties?$expand=Values.

Example Request

http://localhost/Across/crossTerm/api/v2/Terms(402)/Properties?$expand=Values

Example Result

{ 
  "@odata.context": "http://localhost/Across/crossTerm/api/v2/$metadata#Properties/Across.Services.CrossTerm.Api.V2.TermProperty(Values(PicklistValue()))", 
  "value": [ 
    { 
      "Id": 1824, 
      "Guid": "2a45050c-87b0-4f96-8a9c-a662961cbdb7", 
      "Name": "Usage", 
      "DataCategoryId": 21, 
      "ParentId": null, 
      "HasAdditionalInformation": false, 
      "TermId": 402, 
      "Values": [ 
        { 
          "@odata.type": "#Across.Services.CrossTerm.Api.V2.PicklistPropertyValue", 
          "Id": 1893, 
          "Guid": "af50ab1e-db72-4846-a264-484e30453786", 
          "PropertyId": 1824, 
          "Created": "2019-10-31T11:11:34.037Z", 
          "CreatorId": "b254ee5f-68ee-44d4-878b-9e7bbc8db34e", 
          "Modified": "2019-10-31T11:11:34.037Z", 
          "ModifierId": "b254ee5f-68ee-44d4-878b-9e7bbc8db34e", 
          "PicklistValueId": 45, 
          "PicklistValue": { 
            "Id": 45, 
            "Guid": "8d7c76c5-9f0c-49e3-a59a-ac28db986212", 
            "TextLong": "standard", 
            "TextShort": "standard", 
            "Usage": "Recommended", 
            "IsDefault": false, 
            "DataCategoryId": 21 
          } 
        } 
      ] 
    } 
  ] 
}

In this example, the usage of the term with the key 402 is recommended.

Edit Term Text and Set to "Released"

This example shows how to set text of a term and change its state.

The example query below will set text of term with ID = 7 to "application" and change the state of the term to "Released".

Method	PATCH (or MERGE)
Request URL	http://localhost/Across/crossTerm/api/v2/Terms(7)
Request body	{ "Name": "application", "State": "Released" }
Response	{ "@odata.context": "http://localhost/Across/crossTerm/api/v2/$metadata#Terms/$entity", "Id": 7, "Guid": "10a9a6e1-06b9-43ea-8984-08ba245d9633", "IsRawData": false, "Name": "application", "State": "Released", "Created": "2019-07-18T07:58:05Z", "CreatorId": "e0946da0-64c4-42b6-9f02-94bb1774917b", "Modified": "2019-07-18T08:04:49.133Z", "ModifierId": "e0946da0-64c4-42b6-9f02-94bb1774917b", "EntryId": 3, "LanguageId": { "PrimaryLangId": 9, "SubLangId": 1 } }