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 ConfigurationsResponse 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 CustomerConfiguration 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 CustomerConfiguration 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 CustomerConfiguration 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 QueryMatchBody date_range optional Find values inside the specified time interval constraint object gt optional Find values greater than the specified constraint value QueryMatchBody gte optional Find values greater than or equal to the specified constraint value QueryMatchBody key required The metadata key for which the constraint should be applied string lt optional Find values less than the specified constraint value QueryMatchBody lte optional Find values less than or equal to the specified constraint value QueryMatchBody match optional Equality constraint QueryMatchBody range optional Find values inside the specified interval constraint QueryRangeBody starts_with optional Find the beginning of a string QueryMatchBody 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 limit query required Query 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 Query 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 diversify limit optional Maximum number of recommendations with the same value for the selected metadata key limit 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 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