Redirect Rules

Redirect rules allow customers to alter the destination of users' queries. Imagine a user searches for shopping cart: redirects allow a customer to send this user to the shopping cart URL rather than a search result page for shopping cart products.

The redirect rule endpoint allows customers to define a set of patterns that are checked against search queries; if there is a match, the search endpoint returns a redirect response to the client pointing to the desired target URL (or alternative content identifier in mobile contexts).

Rules are matched in order of specificity, from most specific to least. This allows customers to set one redirect for a broad term, but override this with more specific keywords or phrases.

Redirect objects#

In this section the json objects that are sent to/returned by the API are described.

Redirect rule object#

The redirect rule object describes a complete redirect rule and may have multiple, separate match conditions (matches). For example, dog mattresses and dog beds could be defined to target the same URL.

Attribute	Type	Required?	Description
url	string	Yes	Target URL returned when a match happens
matches	List[RedirectRuleMatch]	Yes	List of match definitions
start_time	string	No	Time at which rule begins to apply (ISO8601 format preferred)
end_time	string	No	Time at which rule stops to apply (ISO8601 format preferred)
user_segments	List[str]	No	List of user segments
metadata	Object	No	Object with arbitrary metadata

Redirect rule match object#

The redirect rule match object is the definition of a match in a redirect rule.

Attribute	Type	Required?	Description
match_type	string	Yes	Match type (any of "EXACT", "UNORDERED" or "PHRASE")
pattern	string	Yes	Pattern that needs to be matched against the search query

where:

EXACT: means that the pattern needs to match the search query exactly.
UNORDERED: means that all tokens in the pattern need to match the search query, but not necessarily in the same order.
PHRASE: means that all tokens in the pattern need to match the search query, but the search query may include additional tokens.

Create redirect rule#

To create a redirect rule, the POST method needs to be used.

Shell

Create redirect rule

curl -X POST \
  -H "Content-Type: application/json" \
  -d '{"url": "<url>", "matches": [{"pattern": "<pattern>", "match_type": "EXACT"}]}'
  -u "[your token]:"
  "https://ac.cnstrc.com/v1/redirect_rules?key=[your API key]"

Response

{
  "id": 1,
  "start_time": null,
  "end_time": null,
  "user_segments": null,
  "metadata": null,
  "url": "<url>",
  "matches": [
    {
      "id": 1,
      "match_type": "EXACT",
      "pattern": "<pattern>"
    }
  ]
}

HTTP request#

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

JSON body#

The JSON body for the POST request needs to be a redirect rule object as defined in the redirect objects section.

Read all redirect rules#

To get all redirect rules, the GET method needs to be used.

Shell

Read all redirect rules

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

Response

{
  "redirect_rules": [
    {
      "id": 1,
      "start_time": null,
      "end_time": null,
      "user_segments": null,
      "metadata": null,
      "url": "<url>",
      "matches": [
        {
          "id": 1,
          "match_type": "EXACT",
          "pattern": "<pattern>"
        }
      ]
    }
  ]
}

HTTP request#

GET https://ac.cnstrc.com/v1/redirect_rules?key=[your API key]

URL Parameters#

Parameter	Required	Description
key	Yes	The index you'd like to to retrieve redirect rules from.
num_results_per_page	No	The number of rules to return. Defaults to 20.
page	No	The page of redirect rules to return. Defaults to 1.
query	No	Return redirect rules whose url or match pattern match the provided query.
status	No	One of "current" (return redirect rules that are currently active), "pending" (return redirect rules that will become active in the future), and "expired" (return redirect rules that are not active anymore).

Read redirect rule#

To get all redirect rules, the GET method needs to be used together with a redirect rule ID passed as part of the URL.

Shell

Read redirect rule

curl -X GET \
  -H "Content-Type: application/json" \
  -u "[your token]:"
  "https://ac.cnstrc.com/v1/redirect_rules/<redirect_rule_id>?key=[your API key]"

Response

{
  "id": 1,
  "start_time": null,
  "end_time": null,
  "user_segments": null,
  "metadata": null,
  "url": "<url>",
  "matches": [
    {
      "id": 1,
      "match_type": "EXACT",
      "pattern": "<pattern>"
    }
  ]
}

HTTP request#

GET https://ac.cnstrc.com/v1/redirect_rules/<redirect_rule_id>?key=[your API key]

Update redirect rule (completely)#

To update a redirect rule completely, use a PUT method and pass the redirect rule ID as part of the URL.

Shell

Update redirect rule (completely)

curl -X PUT \
  -H "Content-Type: application/json" \
  -d '{"url": "<new_url>", "matches": [{"pattern": "<new_pattern>", "match_type": "EXACT"}]}'
  -u "[your token]:"
  "https://ac.cnstrc.com/v1/redirect_rules/<redirect_rule_id>?key=[your API key]"

Response

{
  "id": 1,
  "start_time": null,
  "end_time": null,
  "user_segments": null,
  "metadata": null,
  "url": "<new_url>",
  "matches": [
    {
      "id": 2,
      "match_type": "EXACT",
      "pattern": "<new_pattern>"
    }
  ]
}

HTTP request#

PUT https://ac.cnstrc.com/v1/redirect_rules/<redirect_rule_id>?key=[your API key]

JSON body#

The JSON body for the PUT request needs to be a redirect rule object as defined in the redirect objects section.

Update redirect rule (partially)#

To update part of a redirect rule, such as by changing just the target URL but not the match criteria, the PATCH method should be used together with a redirect rule ID passed as part of the URL.

Shell

Update redirect rule (partially)

curl -X PATCH \
  -H "Content-Type: application/json" \
  -d '{"url": "<new_url>"}'
  -u "[your token]:"
  "https://ac.cnstrc.com/v1/redirect_rules/<redirect_rule_id>?key=[your API key]"

Response

{
  "id": 1,
  "start_time": null,
  "end_time": null,
  "user_segments": null,
  "metadata": null,
  "url": "<new_url>",
  "matches": [
    {
      "id": 1,
      "match_type": "EXACT",
      "pattern": "<pattern>"
    }
  ]
}

HTTP request#

PATCH https://ac.cnstrc.com/v1/redirect_rules/<redirect_rule_id>?key=[your API key]

JSON body#

The JSON body for the PATCH request needs to be a subset of the redirect rule object as defined in the redirect objects section.

Delete redirect rule#

To delete a redirect rule, the DELETE method needs to be used together with a redirect rule ID passed as part of the URL.

Shell

Delete redirect rule

curl -X DELETE \
  -H "Content-Type: application/json" \
  -d '{"url": "<new_url>"}'
  -u "[your token]:"
  "https://ac.cnstrc.com/v1/redirect_rules/<redirect_rule_id>?key=[your API key]"

Response

{
  "id": 1,
  "start_time": null,
  "end_time": null,
  "user_segments": null,
  "metadata": null,
  "url": "<new_url>",
  "matches": [
    {
      "id": 1,
      "match_type": "EXACT",
      "pattern": "<pattern>"
    }
  ]
}

HTTP request#

DELETE https://ac.cnstrc.com/v1/redirect_rules/<redirect_rule_id>?key=[your API key]