A list is a text file that you can upload for use with your APIs to easily have a random item (line) returned. You can also use the list function for inline lists if you want to quickly have a random item returned to you. We'll first take a look at the primary usage.
Let's use the Pokemon Game Clone that I am working on as an example and use case for the list.
When you upload a list, you'll be given a reference id. This unique identifier is what you'll use to specify the list you want to use in your API. Only your account has access to the contents of this list.
api.pokemon = list('sx9kqznu');
{
"pokemon": "Vulpix"
}
By default, the list function will choose a random item from the list. You can however specify a line number as the 2nd parameter if you'd like. For my Pokemon Generator, it'd be nice to have a separate id variable generated and then I could use that value to choose the proper line number/pokemon from the list.
api.id = random.numeric(1, 151);
api.pokemon = list('sx9kqznu', api.id);
{
"id": 112,
"pokemon": "Rhydon"
}
As hinted at from before, you can also send an array directly to the list function. The 2nd parameter is also available if you use the list this way, but keep in mind that the index is zero-based for arrays. Let's give the generated pokemon a gender now. It'd be overkill to upload a text file only containing "male" and "female", so let's send in an array!
api.id = random.numeric(1, 151);
api.gender = list(['male', 'female']);
api.pokemon = list('sx9kqznu', api.id);
{
"id": 115,
"gender": "female",
"pokemon": "Kangaskhan"
}