Alexa Skill Developers Reference-Based Catalog Management API - alexa-skills-kit

Question

This doc says "With the Reference-Based Catalog Management API, you can create a custom slot type that references an external data source to get the slot type values. This API allows you to create and maintain a catalog of slot type values independent of your Alexa skill."
However as you dig into it, it doesn't provide some needed details on how to actually setup the catalog on an endpoint like s3.
While this resource was provided as an answer in this similar question, it actually refers to content catalogs (like music playlists), not the Reference-Based Catalog Management API, so I assume that was in error and it is not applicable.
So, for the Reference-Based Catalog Management API: The docs say it needs to be in JSON format, and offers ingredients.json as an example. However I used this directly, and it fails (see below). Also, it does not describe what the format should be to include synonyms. Please describe this.
I can successfully create the catalog with '/v1/skills/api/custom/interactionModel/catalogs/' and get a catalogId in return. However, creating the catalog version via '/skills/api/custom/interactionModel/catalogs/{catalogId}/versions' fails. I get "Website Temporarily Unavailable" when I issue the POST.
Here's the request body structure that I'm including with that post:
data: {
"source": {
"type": "URL",
"url": "https://s3.amazonaws.com/..../ingredients.json"
},
"description": "test S3 bucket"
}
Also, does the S3 endpoint have to be made public? I tried it both ways, didn't seem to matter. If it does have to be public though, how did you handle security?
Thanks for the help.

Answer 1

While the API call fails, I did get this to work using the CLI approach.
ask api create-model-catalog-version -c {catalogID} -f {filename}
The file should be JSON with the following structure:
{
"type": "URL",
"url": "[your catalog url]"
}
It remains an open question how to get the API approach to work, so any answers appreciated. Maybe it is a bug, because I specify the exact same 'source' definition in the data structure of the API call as I do in the JSON file used by the CLI command.
Here's what I learned as I got it to work with the CLI:
Yes, the S3 endpoint must be made public in order for the create-model-catalog-version job to succeed. This strikes me as a problem, would like to see the ability to wrap some security around these endpoints.
Here is the format of the JSON that you will want to use, including the use of synonyms which is not described in the official Amazon example. Note that you don't have to include an ID as shown in that example.
{
"values": [
{
"name": {
"value": "hair salon",
"synonyms": [
"hairdresser",
"beauty parlor"
]
}
},
{
"name": {
"value": "hospital",
"synonyms": [
"emergency room",
"clinic"
]
}
},
]
}