Skip to main content

Configure Sorting Options

The sort options API endpoints allow the customers to configure the sorting options that can be used to sort the search results. For example, a sorting option that sorts the search results according to the price field can be added.

Additional information​

Sort Option Fields​

FieldDescription
sort_orderDetermines the order the data will be sorted according to. This field can only have a value of "ascending" or "descending".
sort_byThis field is a unique identifier for sort options. There can be only one combination of a sort_order and sort_by combination. For instance, there can only be one sort option that has a sort_by value of price and a sort_order of "ascending".
positionAn integer that helps determine the order the sort options will be presented in. Has a default value of null
path_in_metadataPath in data to the field the data will be sorted according to.
display_nameDisplay name for the sort option. For instance, "Price (High - Low)". Has a default value of null

Creating new Sort Options​

Every sort option is identified by the combination of the sort_by and sort_order field, meaning that there can only be only one sort option with a certain sort_by and sort_order field. For instance, there can only be one sort option that has sort_by=price and sort_order="ascending". If a request to create a new sort option that has the same sort_by and sort_order combination is issued, an response containing an error message will created.

At any time, there can be at most 20 sorting options for each index key. If the maximum number of sorting options have been reached for an index key and a request to create another sort option has been issued, a response with an appropriate error message and code will be created.

Updating Sort Options​

As mentioned above, every sort option is identified by the combination of their sort_by and sort_order fields. Therefore, it is not possible to update these two fields. If any of these two fields must be changed, a PUT request to replace the sort option must be issued.

Retrieve Sort Options​

This endpoint can be used to retrieve all sort options for the given key, optionally filtered by sort_by.

curl -X GET -H "Content-Type: application/json" \
  -u"[your token]:" \
  "https://ac.cnstrc.com/v1/sort_options?key=[your index key]"
curl -X GET -H "Content-Type: application/json" \
  -u"[your token]:" \
  "https://ac.cnstrc.com/v1/sort_options?key=[your index key]&sort_by=[sort_by]"

HTTP Requests​

GET https://ac.cnstrc.com/v1/sort_options?key=[your index key]

GET https://ac.cnstrc.com/v1/sort_options?key=[your index key]&sort_by=[sort_by]

Response Format​

{
  "sort_options": [
    {
      "sort_by": "[sort_option_sort_by]",
      "sort_order": "[sort_option_order]",
      "path_in_metadata": "[sort_option_path]",
      "display_name": "[sort_option_display_name]",
      "position": "[sort_option_position]"
    },
    {
      "sort_by": "[other_sort_option_sort_by]",
      "sort_order": "[other_sort_option_order]",
      "path_in_metadata": "[other_sort_option_path]",
      "display_name": "[other_sort_option_display_name]",
      "position": "[other_sort_option_position]"
    }
  ]
}

If display_name is null, it will default to the value of sort_by while retrieving sort options.

Query Parameters​

ParameterRequired?Description
keyYesThe index you'd like to to retrieve results from.
sectionNoThe index section you'd like to retrieve results from.
sort_byNosort_by field of the sort options that you'd like to retrieve

Set Sort Options​

The PUT /v1/sort_options call can be used provide the set of sort options the search results can be sorted according to. All previous sort options will be replaced with the new set of sort options that are provided. At most 20 sort options can be provided.

products
curl -X PUT -H "Content-Type: application/json" \
  -d '{
    "sort_options": [
        {
            "sort_order": "ascending",
            "sort_by": "price",
            "path_in_metadata": "price",
            "display_name": "Price (Low to High)",
            "position": 1
        },
        {
            "sort_order": "descending",
            "sort_by": "price",
            "path_in_metadata": "price",
            "display_name": "Price (High to Low)",
            "position": 2
        },
        {
            "sort_order": "ascending",
            "sort_by": "brand_name",
            "path_in_metadata": "brand",
            "display_name": "Brand A-Z",
            "position": 3
        },
        {
            "sort_order": "ascending",
            "sort_by": "brand_name",
            "path_in_metadata": "brand",
            "display_name": "Brand Z-A"
        },
        {
            "sort_order": "descending",
            "sort_by": "Relevance",
            "path_in_metadata": "relevance"
        }
    ]
}' \
  -u"[your token]:" "https://ac.cnstrc.com/v1/sort_options?key=[your API key]"

When providing sort options, every combination of sort_by and sort_order must be unique. For instance, there can only be one sort option that has a sort_by with value price and a sort_order with value "ascending". If there are multiple sort options that have the same sort_by and sort_order field, an error message will be presented.

Response Format​

The values of the optional fields that were not provided while making the call will be filled with default values.

{
  "sort_options": [
    {
            "sort_order": "ascending",
            "sort_by": "price",
            "path_in_metadata": "price",
            "display_name": "Price (Low to High)"
            "position": 1
        },
        {
            "sort_order": "descending",
            "sort_by": "price"
            "path_in_metadata": "price",
            "display_name": "Price (High to Low)"
            "position": 2
        },
        {
            "sort_order": "ascending",
            "sort_by": "brand_name"
            "path_in_metadata": "brand",
            "display_name": "Brand A-Z"
            "position": 3
        },
        {
            "sort_order": "ascending",
            "sort_by": "brand_name"
            "path_in_metadata": "brand",
            "display_name": "Brand Z-A"
            "position": NULL
        },
        {
            "sort_order": "descending",
            "sort_by": "Relevance"
            "path_in_metadata": "relevance",
            "display_name": NULL
            "position": NULL
        }
  ]
}

HTTP Request​

PUT https://ac.cnstrc.com/v1/sort_options?key=[your API key]

JSON Parameters​

ParameterRequired?Description
sort_orderYesThe order the results will be sorted in. This parameter must be either "ascending" or "descending".
sort_byYesAn identifier for the sort option.
path_in_metadataYesThe path in data to the field that results will be sorted according to.
display_nameNoThe display name of the sort option that will be visible to the user.
positionNoThe position parameter is used to provide sort options in a specific order.

Removing Sort Options​

To delete sort options, issue a call to the DELETE /v1/sort_options endpoint. This will remove previously created sort options identified by the sort_by and sort_order JSON parameters.

products
curl -X DELETE -H "Content-Type: application/json" \
  -d '{
    "sort_options": [
        {
            "sort_order": "ascending",
            "sort_by": "price",
        },
        {
            "sort_order": "ascending",
            "sort_by": "brand_name"
        },
        {
            "sort_order": "descending",
            "sort_by": "brand_name"
        },
    ]
}' \
  -u"[your token]:" "https://ac.cnstrc.com/v1/sort_options?key=[your API key]"
info

The above command(s) return a 204 Success response on success.

HTTP Request​

DELETE https://ac.cnstrc.com/v1/sort_options?key=[your API key]

JSON Parameters​

ParameterRequired?Description
sort_orderYesThe order the results will be sorted in. This parameter must be either "ascending" or "descending".
sort_byYesAn identifier for the sort option.

Create Sort Option​

POST /v1/sort_option can be used to create a single sort option.

products
curl -X POST -H "Content-Type: application/json" \
  -d '{
        "sort_order": "ascending",
        "sort_by": "price",
        "path_in_metadata": "price",
        "display_name": "Price (Low to High)"
        "position": 1
    }' \
  -u"[your token]:" "https://ac.cnstrc.com/v1/sort_option?key=[your API key]"

Response Format​

The values of the optional fields that were not provided while making the call will be filled with default values.

{
    "sort_order": "ascending",
    "sort_by": "price",
    "path_in_metadata": "price",
    "display_name": "Price (Low to High)"
    "position": 1
}

When creating a sort option, a sort option with the same sort_by and sort_order fields should not already exist. Every combination of sort_by and sort_order among the sort options must be unique. Therefore, if there is another sort option with the same sort_by and sort_order fields, an error will occur.

HTTP Request​

POST https://ac.cnstrc.com/v1/sort_option?key=[your API key]

JSON Parameters​

ParameterRequired?Description
sort_orderYesThe order the results will be sorted in. This parameter must be either "ascending" or "descending".
sort_byYesAn identifier for the sort option.
path_in_metadataYesThe path in data to the field that results will be sorted according to.
display_nameNoThe display name of the sort option that will be visible to the user.
positionNoThe position parameter is used to provide sort options in a specific order.

Create or Replace Sort Option​

PUT /v1/sort_option/[sort_by]/[sort_order] can be used to create or replace the sort option with the sort_by and sort_order provided in the URL. If the sort option does not exist, a new sort option will be created with the values that are provided. If the sort option already exists, the existing sort option will be replaced with a new sort option with the values provided as JSON parameters.

products
curl -X PUT -H "Content-Type: application/json" \
  -d '{
        "path_in_metadata": "price",
        "display_name": "Price (High to Low)"
        "position": 1
    }' \
  -u"[your token]:" "https://ac.cnstrc.com/v1/sort_option/price/descending?key=[your API key]"

Response Format​

The values of the optional fields that were not provided while making the call will be filled with default values.

{
    "sort_order": "descending",
    "sort_by": "price",
    "path_in_metadata": "price",
    "display_name": "Price (High to Low)"
    "position": 1
}

HTTP Request​

PUT https://ac.cnstrc.com/v1/sort_option/[sort_by]/[sort_order]?key=[your API key]

URL Parameters​

ParameterDescription
sort_byThe sort_by identifier of the sort option you are looking to create or replace
sort_orderThe sort_order of the sort option you are looking to create or replace

JSON Parameters​

ParameterRequired?Description
path_in_metadataYesThe path in data to the field that results will be sorted according to.
display_nameNoThe display name of the sort option that will be visible to the user.
positionNoThe position parameter is used to provide sort options in a specific order.

Update Sort Option​

PATCH /v1/sort_option/[sort_by]/[sort_order] can be used to update the sort option identified by the sort_by and sort_order values that are provided in the URL.

products
curl -X PATCH -H "Content-Type: application/json" \
  -d '{
        "path_in_metadata": "price",
        "display_name": "New Display Name"
        "position": 1
    }' \
  -u"[your token]:" "https://ac.cnstrc.com/v1/sort_option/price/descending?key=[your API key]"

Response Format​

The values of the optional fields that were not provided while making the call will be filled with default values.

{
    "sort_order": "descending",
    "sort_by": "price",
    "path_in_metadata": "price",
    "display_name": "New Display Name"
    "position": 1
}

The sort option that has a sort_by value price and a sort_order value of descending will be updated with the values passed as JSON parameters.

HTTP Request​

PATCH https://ac.cnstrc.com/v1/sort_option/[sort_by]/[sort_order]?key=[your API key]

URL Parameters​

ParameterDescription
sort_byThe sort_by identifier of the sort option you are looking to create or replace
sort_orderThe sort_order of the sort option you are looking to create or replace

JSON Parameters​

ParameterRequired?Description
path_in_metadataYesThe path in data to the field that results will be sorted according to.
display_nameNoThe display name of the sort option that will be visible to the user.
positionNoThe position parameter is used to provide sort options in a specific order.