api_entry_points.md

Personalization API entry points

The API entry points have consistent and predictable paths based on your configuration. Since entry point paths are resolved dynamically for each request based on your configuration, an update to your configuration will be reflected in the API entry points after your configuration is deployed via AWS AppConfig and the API functions have reloaded their configuration (every 45 seconds, by default).

OpenAPI/Swagger specification

Each time the application configuration is deployed in AppConfig, the solution will generate an OpenAPI/Swagger specification file based the configuration. The OpenAPI specification file is written to the /openapi folder in the staging bucket created as part of this project. If you selected to have the Swagger UI included in your deployment of this project, you can use the deployed Swagger UI to inspect and test your APIs (see screenshot below). The URL for the Swagger UI can be found in the CloudFormation output parameters from your deployment of this project. After changing and deploying the application configuration in AppConfig, just refresh the Swagger UI to have it reload the latest OpenAPI spec file from the staging bucket.

Swagger UI

Alternatively, you can use the generated OpenAPI specification file to test your APIs using a utility such as the Swagger Editor or Postman tool as well as generating clients for your APIs in a variety of programming languages. Just download the generated OpenAPI spec file from the S3 staging bucket and import it into the Swagger Editor or Postman.

Swagger editor

Postman

Host names

The OpenAPI specification file generated above will automatically include the host names for CloudFront (if configured) and API Gateway for your deployment. These host names are also provided as CloudFormation output parameters as described below.

• If you deployed with the API-Gateway-REST API entry point type:
  • Use the value of the RestApiEndpointUrl CloudFormation output parameter as your API root URL (you can also find this URL in the AWS console for API Gateway)
• If you deployed with CloudFront or Both cache scheme:
  • Use the value of the ApiCdnUrl CloudFormation output parameter as your API root URL (you can also find this URL in the AWS console for CloudFront)
• If you deployed with None cache scheme:
  • Use the value of the HttpApiEndpointUrl CloudFormation output parameter as your API root URL (you can also find this URL in the AWS console for CloudFront)

You can optionally setup your own domain name and SSL certifications for these endpoints. See the CloudFront and API Gateway documentation for detailed instructions.

Inference entry points

The inference entry points provide recommendations (inference) based on an API action, namespace, recommender, and action-specific required path parameters.

Recommend items API action

This entry point returns item recommendations for a specific user.

GET /recommend-items/{namespace}/{recommender}/{user_id}

Path parameters (required)

• {namespace}: Namespace path defined in your Personalization APIs configuration.
• {recommender}: Recommender path defined in your Personalization APIs configuration.
• {user_id}: Identifier of the user to retrieve recommendations.

Query string parameters (optional)

• numResults (integer): How many items to return in the response. The minimum supported value is 1 and the maximum value depends on the underlying recommender. For a Personalize campaign/recommender, the maximum is 500. If this parameter is not specified, the default is 25.
• filter (string): Amazon Personalize filter name or ARN to use in the GetRecommendations API call to the Personalize campaign/recommender for the configured recommender. This parameter overrides the filter associated with the recommender in the configuration.
• filterValues (string map): When the filter parameter is specified and the expression for the filter has dynamic variable(s), this parameter can be used to specify the value(s) to use for those variables. This parameter value must be a string map (JSON) encoded as a string. See the Personalize filter documentation for details and examples. This value is blended with the automatic filter rules associated with the recommender in the configuration.
• context (string map): Provides context for contextual recommendations as a string map (JSON) encoded as a string. This value is blended with the auto context rules in the configuration.
• decorateItems (boolean): Controls whether item IDs returned from the origin recommender are decorated with item metadata in the response. The values 1, yes, and true (case-insensitive) will be interpreted as true. Any other value will be interpreted as false. The default value is true. Since this parameter is included in the cache key for response caching, it is important to use consistent values across your client applications (to maximize cache hit rate).
• syntheticUser (boolean): Indicates whether the user specified in the {user_id} path parameter represents an individual user or a synthetic user representing one or more actual users. When combined with cache settings, this allows you to define a different cache policy for synthetic users. Since this parameter is included in the cache key for response caching, it is important to use consistent values across your client applications (to maximize cache hit rate).
• feature (string): Experiment feature name matching an experiment for the recommender in the configuration.

Examples

The example below assume the following simple configuration that includes one namespace (my-store) with one recommender (recommended-for-you) for the recommend-items API action type and one variation that resolves to an Amazon Personalize campaign:

{
    "namespaces": {
        "my-store": {
            "inferenceItemMetadata": {
                "type": "localdb"
            },
            "recommenders": {
                "recommend-items": {
                    "recommended-for-you": {
                        "variations": {
                            "user-personalization": {
                                "type": "personalize-campaign",
                                "arn": "arn:aws:personalize:[REGION]:[ACCOUNT]:campaign/[CAMPAIGN_NAME]",
                                "filters": [{
                                    "arn": "arn:aws:personalize:[REGION]:[ACCOUNT]:filter/[FILTER_NAME]"
                                }]
                            }
                        }
                    }
                }
            }
        }
    }
}

The GET URI path to get item recommendations for user 1234 from the above configuration would look like this:

GET /recommend-items/my-store/recommended-for-you/1234

The URI path starts with the API action type (recommend-items), then the namespace (my-store), then the recommender (recommended-for-you), and then finally the user ID (1234). Additional optional parameters, such as numResults, could be added as query string parameters. Note too that there is a filter defined in the configuration above. When a filter is declared in the configuration, it is automatically applied to GetRecommendations calls for the recommender variation. If the filter parameter is specified in the query string, it will override the filter(s) specified in the configuration.

Related items API action

This entry point returns related/similar item recommendations for a specific item.

GET /related-items/{namespace}/{recommender}/{item_id}

Path parameters (required)

• {namespace}: Namespace path defined in your Personalization APIs configuration.
• {recommender}: Recommender path defined in your Personalization APIs configuration.
• {item_id}: Identifier of the item to retrieve related item recommendations.

Query string parameters (optional)

• userId (string): User ID representing the user for this request. This parameter becomes required when a filter is specified using either the filter parameter or for the recommender in the configuration.
• numResults (integer): How many items to return in the response. The minimum supported value is 1 and the maximum value depends on the underlying recommender. For a Personalize campaign/recommender, the maximum is 500. If this parameter is not specified, the default is 25.
• filter (string): Amazon Personalize filter name or ARN to use in the GetRecommendations API call to the Personalize campaign/recommender for the configured recommender. This parameter overrides the filter associated with the recommender in the configuration.
• filterValues (string map): When the filter parameter is specified and the expression for the filter has dynamic variable(s), this parameter can be used to specify the value(s) to use for those variables. This parameter value must be a string map (JSON) encoded as a string. See the Personalize filter documentation for details and examples. This value is blended with the automatic filter rules associated with the recommender in the configuration.
• context (string map): Provides context for contextual recommendations as a string map (JSON) encoded as a string. This value is blended with the auto context rules in the configuration.
• decorateItems (boolean): Controls whether item IDs returned from the origin recommender are decorated with item metadata in the response. The values 1, yes, and true (case-insensitive) will be interpreted as true. Any other value will be interpreted as false. The default value is true. Since this parameter is included in the cache key for response caching, it is important to use consistent values across your client applications (to maximize cache hit rate).
• syntheticUser (boolean): Indicates whether the user specified in the userId parameter represents an individual user or a synthetic user representing one or more actual users. When combined with cache settings, this allows you to define a different cache policy for synthetic users. Since this parameter is included in the cache key for response caching, it is important to use consistent values across your client applications (to maximize cache hit rate).
• feature (string): Experiment feature name matching an experiment for the recommender in the configuration.

Rerank items API action

The following entry points rerank/reorder a list of items in order of predicted interest for a specific user. There are two variations of this action using different HTTP action verbs.

GET /rerank-items/{namespace}/{recommender}/{user_id}/{item_ids} (recommended)

POST /rerank-items/{namespace}/{recommender}/{user_id}

The {item_ids} path parameter must be a comma-delimited list of item IDs to rerank. For example, item_1,item_2,item_3. If your item IDs can include the comma character, you cannot use the GET variation and must use the POST variation instead.

The HTTP GET variation of this entry point is recommended since its responses can be cached. Responses for the HTTP POST variation cannot be cached. However, if the length of the constructed URL of the GET variation exceeds what is supported by your client application's HTTP client (varies), CloudFront (8192 bytes), or API Gateway (8192 bytes), the POST variation must be used instead.

If the POST variation is used, the request Content-Type should be application/json and the body of the request must be a JSON string array of the item IDs to rerank. For example:

[ "item_1", "item_2", "item_3" ]

Path parameters (required)

• {namespace}: Namespace path defined in your Personalization APIs configuration.
• {recommender}: Recommender path defined in your Personalization APIs configuration.
• {user_id}: Identifier of the user to rerank items based upon.
• {item_ids}: Item IDs formatted as a comma-delimited list (only required for the GET HTTP method).

Query string parameters (optional)

• filter (string): Amazon Personalize filter name or ARN to use in the GetPersonalizedRanking API call to the Personalize campaign/recommender for the configured recommender. This parameter overrides the filter associated with the recommender in the configuration.
• filterValues (string map): When the filter parameter is specified and the expression for the filter has dynamic variable(s), this parameter can be used to specify the value(s) to use for those variables. This parameter value must be a string map (JSON) encoded as a string. See the Personalize filter documentation for details and examples. This value is blended with the automatic filter rules associated with the recommender in the configuration.
• context (string map): Provides context for contextual recommendations as a string map (JSON) encoded as a string. This value is blended with the auto context rules in the configuration.
• decorateItems (boolean): Controls whether item IDs returned from the origin recommender are decorated with item metadata in the response. The values 1, yes, and true (case-insensitive) will be interpreted as true. Any other value will be interpreted as false. The default value is true. Since this parameter is included in the cache key for response caching, it is important to use consistent values across your client applications (to maximize cache hit rate).
• syntheticUser (boolean): Indicates whether the user specified in the {user_id} path parameter represents an individual user or a synthetic user representing one or more actual users. When combined with cache settings, this allows you to define a different cache policy for synthetic users. Since this parameter is included in the cache key for response caching, it is important to use consistent values across your client applications (to maximize cache hit rate).
• feature (string): Experiment feature name matching an experiment for the recommender in the configuration.

Events

The events entry point allows new user events/interactions and A/B test conversion events to be streamed to one or more event targets.

POST /events/{namespace}

Path parameters (required)

• {namespace}: Namespace path defined in your Personalization APIs configuration.

The request Content-Type should be application/json and the body of the request must be a JSON document that conforms to the following format (which is modeled on and extends the Amazon Personalize PutEvents API request format).

{
   "sessionId": "string",
   "userId": "string",
   "eventList": [
      {
         "eventId": "string",
         "eventType": "string",
         "eventValue": number,
         "impression": [ "string" ],
         "itemId": "string",
         "properties": "string",
         "recommendationId": "string",
         "sentAt": number
      }
   ],
   "experimentConversions": [
      {
          "recommender": "string",
          "feature": "string",
          "metric": "string",
          "value": number
      }
   ]
}

Notable differences from and extensions to the Amazon Personalize PutEvents API request format

• trackingId is not required in the request body but is instead derived from the event targets specified in the Personalization APIs configuration. This allows you to fan-out events to multiple Personalize event trackers, say, to different Personalize dataset groups that use the same/similar interactions dataset schema.
• eventList: events to track for the userId:
  • eventList[].properties: specifies interaction context fields and values (optional). If automatic context rules are configured, the Personalization APIs will automatically derive context from the request and build/blend the context values into the properties field value before sending to configured event targets.
• experimentConversions includes experiment conversions for the user (optional):
  • experimentConversions[].recommender: recommender path within the namespace for the experiment conversion (required).
  • experimentConversions[].feature: feature name for the experiment for the conversion (optional but recommended). If not specified, the first experiment for the recommender in the configuration will be used to log the conversion event. If you are running multiple experiments for the same recommender, you should specify the feature name when retrieving recommendations and logging conversion events.
  • experimentConversions[].metric: metric name to attribute the conversion event value to.
  • experimentConversions[].value: conversion event value that is used as the Evidently metric value (optional). Defaults to 1.0 if not specified.
• eventList and experimentConversions are both optional but at least one must be included in the request. Therefore, you can use both or either in the same request.

See the Amazon Personalize PutEvents API documentation for details on all other properties of the payload.