Synonyms API reference

edit

Synonyms API reference

edit

Provides synonym set management for Workplace Search queries.

In this API reference

edit

Synonyms API authentication

edit

Workplace Search APIs support multiple methods of authentication. To manage synonym sets, the valid authorization must belong to a member with the Admin role.

List synonym sets

edit
GET /api/ws/v1/synonyms

List synonym sets, optionally filtered by a term or list of terms. Issuing this call without any body parameters will default to the first page with a maximum of 25 results per page and sorted by the updated_at timestamp in descending order.

Body parameters can include:

page

optional

Provides optional keys of size and current. Specifies the number of results per page and which page the API should return. Defaults values are a size of 25 and a current of 1.

filter

optional

A single term or array of terms, used to filter the synonym sets by. Term filters will perform an exact match on terms within synonym sets.

sort

optional

Sort results asc or desc on the created_at or updated_at fields.

curl -X GET '<WORKPLACE_SEARCH_BASE_URL>/api/ws/v1/synonyms' \
-H 'Authorization: Bearer <ACCESS_TOKEN>' \
-H 'Content-Type: application/json' \
-d '{
    "page": {
        "current": "<INT>",
        "size": "<INT>"
    },
    "filter": {
        "terms": "<STRING>|<STRING ARRAY>"
    },
    "sort": {
        "created_at": "asc|desc",
        "updated_at": "asc|desc"
    }
}'
{
  "meta": {
    "page": {
      "current": 1,
      "total_pages": 1,
      "total_results": 10,
      "size": 25
    },
    "filter": { "terms": ["house", "books"] },
    "sort": {
      { "updated_at": "desc" },
      { "created_at": "asc" }
    }
  },
  "results": [
    {
        "id": "<ID>",
        "synonyms": ["house","home","abode"],
        "created_at": "2021-01-02T10:00:00Z",
        "updated_at": "2021-04-22T00:00:05Z"
    }, ...
  ]
}

Show single synonym set

edit
GET /api/ws/v1/synonyms/<ID>

Display a single synonym set by id.

curl -X GET '<WORKPLACE_SEARCH_BASE_URL>/api/ws/v1/synonyms/<ID>' \
-H 'Authorization: Bearer <ACCESS_TOKEN>'
{
    "id": "<ID>",
    "synonyms": ["house","home","abode"],
    "created_at": "2021-01-02T10:00:00Z",
    "updated_at": "2021-04-22T00:00:05Z"
}

Create synonym sets

edit

Synonym sets can be created individually or in batches of up to 100 at a time.

Create a single synonym set
edit
POST /api/ws/v1/synonyms

Provide an array of terms to create a single synonym set. If created successfully, the synonyms as well as the new synonym set ID will be returned. If any of the terms already exist, a 400 / Bad Request status code will be returned along with an error message indicating which terms already exist.

curl -X POST '<WORKPLACE_SEARCH_BASE_URL>/api/ws/v1/synonyms' \
-H 'Authorization: Bearer <ACCESS_TOKEN>' \
-H 'Content-Type: application/json' \
-d '{
    "synonyms": ["house", "home", "abode"]
}'
{
    "id": "<ID>",
    "synonyms": ["house","home","abode"]
}
Create a batch of synonym sets
edit
POST /api/ws/v1/synonyms

Provide up to 100 synonym sets to create in a single batch. For each successful set, the synonyms and the created ID will be returned in the results. If there are any errors with any of the sets to create, the has_errors flag will be set to true, and any errors will be given within the individual sets.

curl -X POST '<WORKPLACE_SEARCH_BASE_URL>/api/ws/v1/synonyms' \
-H 'Authorization: Bearer <ACCESS_TOKEN>' \
-H 'Content-Type: application/json' \
-d '{
    "synonym_sets": [
        { "synonyms": ["house", "home", "abode"] },
        { "synonyms": ["cat", "feline", "kitty"] },
        { "synonyms": ["mouses", "mice"] }
    ]
}'
{
    "has_errors": true,
    "synonym_sets": [
        {
            "synonyms": ["house","home","abode"],
            "errors": [
                "Duplicate terms - the following terms already exist in an existing synonym set: house, home"
            ]
        },
        {
            "id": "<ID>",
            "synonyms": ["cat","feline","kitty"]
        },
        {
            "id": "<ID>",
            "synonyms": ["mouse","mice","meeces"]
        }
    ]
}

Update a synonym set

edit
PUT /api/ws/v1/synonyms/<ID>

Updates a single synonym set.

All of the terms for the set will be replaced with the provided items.

curl -X PUT '<WORKPLACE_SEARCH_BASE_URL>/api/ws/v1/synonyms/<ID>' \
-H 'Authorization: Bearer <ACCESS_TOKEN>' \
-H 'Content-Type: application/json' \
-d '{
    "synonyms": ["house", "home", "dwelling"]
}'
{
    "id": "[ID]",
    "synonyms": ["house", "home", "dwelling"],
    "created_at": "2021-01-02T10:00:00Z",
    "updated_at": "2021-04-22T00:00:05Z"
}

Delete a synonym set

edit
DELETE /api/ws/v1/synonyms/<ID>

Deletes a single synonym set by ID.

curl -X DELETE '<WORKPLACE_SEARCH_BASE_URL>/api/ws/v1/synonyms/<ID>' \
-H 'Authorization: Bearer <ACCESS_TOKEN>'
{
    "deleted": true
}