Configurations API (removed from docs)

Creating, updating and fetching configurations from the Froomle platform is done through the Configurations API.

Specifications

GET /configurations

Description

Get all configuration IDs.

Responses

HTTP Code Description Schema

200

OK

Produces

  • application/json

Example HTTP response

Response 200
[ "winter_2020", "male_only", "discounted" ]

cURL Example

$ curl --location --request GET 'https://{subdomain}.froomle.com/api/configurations/default' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer X'

GET /configurations/{configuration_id}

Description

Get the configuration associated with configuration_id.

Parameters

Type Name Schema

Path

configuration_id
required

string

Responses

HTTP Code Description Schema

200

OK

404

Configuration not found

No Content

Produces

  • application/json

Example HTTP response

Response 200
{
  "configuration_id" : "<some_name>",
  "constraints" : [ {
    "_constraint_explanation" : "Limit the generated recommendations to contain at most 2 results which contain 'Brexit' in the metadata key 'article_title'",
    "limit" : {
      "max" : 2
    },
    "query" : {
      "contains" : {
        "value" : "Brexit"
      },
      "key" : "article_title"
    }
  }, {
    "_constraint_explanation" : "Include at least one result which has an exact match for 'domestic' for the metadata key 'section'",
    "limit" : {
      "min" : 1
    },
    "query" : {
      "key" : "section",
      "match" : {
        "value" : "domestic"
      }
    }
  }, {
    "_constraint_explanation" : "Results' 'section' key value must not be equal to 'SHE'",
    "query" : {
      "key" : "section",
      "match" : {
        "not" : {
          "value" : "SHE"
        }
      }
    }
  }, {
    "_constraint_explanation" : "Results' 'paywall_type' key value must have an exact match for 'paid'",
    "query" : {
      "key" : "paywall_type",
      "match" : {
        "value" : "paid"
      }
    }
  }, {
    "_constraint_explanation" : "Results' 'section' key value must either match 'Sport' or match the specified request body variable 'second_category' which has a fallback value of 'domestic'",
    "query" : {
      "key" : "section",
      "match" : {
        "or" : [ {
          "value" : "Sport"
        }, {
          "variable" : {
            "default" : "domestic",
            "name" : "second_category"
          }
        } ]
      }
    }
  }, {
    "_constraint_explanation" : "Results' 'price' key value must be located in the interval [10, 50]",
    "query" : {
      "key" : "price",
      "range" : {
        "max" : 50,
        "min" : 10
      }
    }
  }, {
    "_constraint_explanation" : "Results' 'brand' key value must exactly match the specified context item's 'brand' metadata key value",
    "query" : {
      "key" : "brand",
      "match" : {
        "variable" : {
          "context" : "item",
          "name" : "brand"
        }
      }
    }
  }, {
    "_diversify_explanation" : "The list of results should contain at most 3 items with the same value for the 'section' metadata key",
    "diversify" : {
      "key" : "section"
    },
    "limit" : {
      "max" : 3
    }
  } ],
  "preferences" : [ {
    "_preference_explanation" : "The color of the recommended items should preferably be green or red.",
    "query" : {
      "key" : "color",
      "or" : [ {
        "value" : "green"
      }, {
        "value" : "red"
      } ]
    }
  }, {
    "_preference_explanation" : "The surface area of the recommended items should preferably be at most the value specified in the request under `max_surface_area`.",
    "query" : {
      "key" : "surface_area",
      "lte" : {
        "variable" : {
          "name" : "max_surface_area"
        }
      }
    }
  } ]
}

Get the configuration associated with configuration_id.

cURL Example

$ curl --location --request GET 'https://{subdomain}.froomle.com/api/configurations/default' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer X'

POST /configurations

Description

Store a configuration.

Parameters

Type Name Schema

Body

body
required

Responses

HTTP Code Description Schema

200

Configuration was stored.

No Content

400

The configure body was not in the right format or was missing mandatory information.

No Content

415

The event body is not of type json.

No Content

501

Functionality not supported.

No Content

Consumes

  • application/json

Example HTTP request

Request body
{
  "configuration_id" : "<some_name>",
  "constraints" : [ {
    "_constraint_explanation" : "Limit the generated recommendations to contain at most 2 results which contain 'Brexit' in the metadata key 'article_title'",
    "limit" : {
      "max" : 2
    },
    "query" : {
      "contains" : {
        "value" : "Brexit"
      },
      "key" : "article_title"
    }
  }, {
    "_constraint_explanation" : "Include at least one result which has an exact match for 'domestic' for the metadata key 'section'",
    "limit" : {
      "min" : 1
    },
    "query" : {
      "key" : "section",
      "match" : {
        "value" : "domestic"
      }
    }
  }, {
    "_constraint_explanation" : "Results' 'section' key value must not be equal to 'SHE'",
    "query" : {
      "key" : "section",
      "match" : {
        "not" : {
          "value" : "SHE"
        }
      }
    }
  }, {
    "_constraint_explanation" : "Results' 'paywall_type' key value must have an exact match for 'paid'",
    "query" : {
      "key" : "paywall_type",
      "match" : {
        "value" : "paid"
      }
    }
  }, {
    "_constraint_explanation" : "Results' 'section' key value must either match 'Sport' or match the specified request body variable 'second_category' which has a fallback value of 'domestic'",
    "query" : {
      "key" : "section",
      "match" : {
        "or" : [ {
          "value" : "Sport"
        }, {
          "variable" : {
            "default" : "domestic",
            "name" : "second_category"
          }
        } ]
      }
    }
  }, {
    "_constraint_explanation" : "Results' 'price' key value must be located in the interval [10, 50]",
    "query" : {
      "key" : "price",
      "range" : {
        "max" : 50,
        "min" : 10
      }
    }
  }, {
    "_constraint_explanation" : "Results' 'brand' key value must exactly match the specified context item's 'brand' metadata key value",
    "query" : {
      "key" : "brand",
      "match" : {
        "variable" : {
          "context" : "item",
          "name" : "brand"
        }
      }
    }
  }, {
    "_diversify_explanation" : "The list of results should contain at most 3 items with the same value for the 'section' metadata key",
    "diversify" : {
      "key" : "section"
    },
    "limit" : {
      "max" : 3
    }
  } ],
  "preferences" : [ {
    "_preference_explanation" : "The color of the recommended items should preferably be green or red.",
    "query" : {
      "key" : "color",
      "or" : [ {
        "value" : "green"
      }, {
        "value" : "red"
      } ]
    }
  }, {
    "_preference_explanation" : "The surface area of the recommended items should preferably be at most the value specified in the request under `max_surface_area`.",
    "query" : {
      "key" : "surface_area",
      "lte" : {
        "variable" : {
          "name" : "max_surface_area"
        }
      }
    }
  } ]
}

Store a configuration.

cURL Example

$ curl --location --request POST 'https://{subdomain}.froomle.com/api/configurations' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer X' \
--data-raw '{
    "constraints": [
        {
            "diversify": {
                "key": "node"
            },
            "limit": {
                "max": 3
            }
        }
    ],
    "configuration_id": "default"
}'

PUT /configurations/{configuration_id}

Description

Store a configuration.

Parameters

Type Name Schema

Path

configuration_id
required

string

Body

body
required

Responses

HTTP Code Description Schema

200

Configuration was stored.

No Content

400

The configure body was not in the right format or was missing mandatory information.

No Content

415

The request body is not of type json.

No Content

500

Internal server error

No Content

501

Functionality not supported

No Content

Consumes

  • application/json

Example HTTP request

Request body
{
  "configuration_id" : "<some_name>",
  "constraints" : [ {
    "_constraint_explanation" : "Limit the generated recommendations to contain at most 2 results which contain 'Brexit' in the metadata key 'article_title'",
    "limit" : {
      "max" : 2
    },
    "query" : {
      "contains" : {
        "value" : "Brexit"
      },
      "key" : "article_title"
    }
  }, {
    "_constraint_explanation" : "Include at least one result which has an exact match for 'domestic' for the metadata key 'section'",
    "limit" : {
      "min" : 1
    },
    "query" : {
      "key" : "section",
      "match" : {
        "value" : "domestic"
      }
    }
  }, {
    "_constraint_explanation" : "Results' 'section' key value must not be equal to 'SHE'",
    "query" : {
      "key" : "section",
      "match" : {
        "not" : {
          "value" : "SHE"
        }
      }
    }
  }, {
    "_constraint_explanation" : "Results' 'paywall_type' key value must have an exact match for 'paid'",
    "query" : {
      "key" : "paywall_type",
      "match" : {
        "value" : "paid"
      }
    }
  }, {
    "_constraint_explanation" : "Results' 'section' key value must either match 'Sport' or match the specified request body variable 'second_category' which has a fallback value of 'domestic'",
    "query" : {
      "key" : "section",
      "match" : {
        "or" : [ {
          "value" : "Sport"
        }, {
          "variable" : {
            "default" : "domestic",
            "name" : "second_category"
          }
        } ]
      }
    }
  }, {
    "_constraint_explanation" : "Results' 'price' key value must be located in the interval [10, 50]",
    "query" : {
      "key" : "price",
      "range" : {
        "max" : 50,
        "min" : 10
      }
    }
  }, {
    "_constraint_explanation" : "Results' 'brand' key value must exactly match the specified context item's 'brand' metadata key value",
    "query" : {
      "key" : "brand",
      "match" : {
        "variable" : {
          "context" : "item",
          "name" : "brand"
        }
      }
    }
  }, {
    "_diversify_explanation" : "The list of results should contain at most 3 items with the same value for the 'section' metadata key",
    "diversify" : {
      "key" : "section"
    },
    "limit" : {
      "max" : 3
    }
  } ],
  "preferences" : [ {
    "_preference_explanation" : "The color of the recommended items should preferably be green or red.",
    "query" : {
      "key" : "color",
      "or" : [ {
        "value" : "green"
      }, {
        "value" : "red"
      } ]
    }
  }, {
    "_preference_explanation" : "The surface area of the recommended items should preferably be at most the value specified in the request under `max_surface_area`.",
    "query" : {
      "key" : "surface_area",
      "lte" : {
        "variable" : {
          "name" : "max_surface_area"
        }
      }
    }
  } ]
}

cURL Example

Update a configuration.

$ curl --location --request POST 'https://{subdomain}.froomle.com/api/configurations' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer X' \
--data-raw '{
    "constraints": [
        {
            "diversify": {
                "key": "node"
            },
            "limit": {
                "max": 3
            }
        }
    ],
    "configuration_id": "default"
}'

DELETE /configurations/{configuration_id}

Description

Delete a configuration.

Parameters

Type Name Schema

Path

configuration_id
required

string

Responses

HTTP Code Description Schema

200

Configuration was deleted successfully.

No Content

404

Configuration not found

No Content

500

Internal server error

No Content

Delete a configuration.

cURL Example

$ curl --location --request DELETE 'https://{subdomain}.froomle.com/api/configurations/{configuration_id}' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer X'

Definitions

ConfigurationsResponse

A list of the active configuration ids

Type : < string > array

CustomerConfiguration

Name Description Schema

configuration_id
required

The identifier used to reference the created configuration

string

constraints
optional

Array of either QueryConstraint or Diversify objects

< object > array

preferences
optional

Array of QueryPreference objects

< QueryPreference > array

Query

Defines a query (condition) which recommendations should match

Name Description Schema

contains
optional

Find a substring

date_range
optional

Find values inside the specified time interval constraint

object

gt
optional

Find values greater than the specified constraint value

gte
optional

Find values greater than or equal to the specified constraint value

key
required

The metadata key for which the constraint should be applied

string

lt
optional

Find values less than the specified constraint value

lte
optional

Find values less than or equal to the specified constraint value

match
optional

Equality constraint

range
optional

Find values inside the specified interval constraint

starts_with
optional

Find the beginning of a string

QueryConstraint

Defines a query constraint which recommendations must match and optionally a limit

Name Description Schema

limit
optional

Limit the max/min number of recommendations that should satisfy this constraint

query
required

limit

Name Description Schema

max
optional

Limit the maximum number of recommendations that should satisfy this constraint

integer

min
optional

Limit the minimum number of recommendations that should satisfy this constraint

integer

QueryPreference

Defines a query (condition) which recommendations should match. If not enough items satisfying the preferred condition are available, other items may still be returned.

Name Schema

query
required

weight
optional

integer

Diversify

Influence the recommendation generation to be more diverse by applying limits to the maximum number of recommendations with a certain property value

Name Description Schema

diversify
required

Specify a metadata key for which values should be distinct (or limited to a maximum amount) in the generated recommendations

limit
optional

Maximum number of recommendations with the same value for the selected metadata key

diversify

Name Description Schema

key
required

Metadata key

string

limit

Name Description Schema

max
optional

Maximum number of recommendations

integer

QueryComparator

Either an array of QueryValueOrVariable objects or a single QueryValueOrVariable object

QueryMatchBody

Key one of and, or, not with a Value QueryComparator or just a plain QueryValueOrVariable

QueryNot

One of: QueryValueOrVariable, {"or": QueryComparator} or {"and": QueryComparator}

QueryRangeBody

Name Description Schema

max
required

Upper bound value of the range

number

min
required

Lower bound value of the range

number

QueryValueOrVariable

A QueryValue or QueryVariable

QueryValue

Match a constraint using a hard coded value

Name Description Schema

value
required

A string, boolean or number

object

QueryVariable

Match a constraint using a variable which can be specified at recommendation request time

Name Description Schema

variable
required

Reference a variable by at least its name

variable

Name Description Schema

context
optional

The source of the variable, can be either request_body (default) to look inside the request body or item to look for the variable in the metadata of the specified context item

string

default
optional

A fallback value that is used when the variable is not set at request time either a string or number

object

name
required

Name of the variable which can be specified at recommendation request time

string

on_absent_drop
optional

Set to true if the constraint should be ignored if the variable is not specified in the request

boolean