RIGHT SO there are several use cases here; essentially we want to make the entire website navigable via API.
which means you should be able to REQUEST:
- lookup a single Pokémon
- retrieve a single Pokémon unambiguously -- by identifier or id
- search across all manner of properties
and RETRIEVE:
- any property
- in any language
- in any version
By the way a "locus" is a Primary Thing (i.e. something that has a dedicated page on veekun) and a "property" is a... property. yeah.
A simple API response might look like this:
GET /api/pokemon/eevee
# these are "default" properties
{
"identifier": "eevee",
"generation": 1,
"types": [
"normal",
],
# ...
}
Conceptually, there are three ways to make requests.
- Directly with an identifier (and required locus category). This may:
- Find exactly one locus.
- Find nothing.
- Lookup (with optional language and locus category). This may:
- Find any number of loci by exact match, due to repeated names across languages or categories.
- Find multiple loci by fuzzy match.
- Find nothing.
- Search. This may:
- Find any number of loci.
- Find nothing.
- Require more information. But more on that later.
These are bags of properties, as seen in the example, though there are a few other considerations.
- Responses can contain any collection of properties.
- If a property happens to be another locus (e.g. a Pokémon's types), that locus can also be fetched at the same time.
- Responses can be limited by language, to determine which strings of e.g. flavor text are returned.
- Responses can be limited by version, to determine e.g. which movesets are returned.
As seen above, /api/pokemon/eevee and similar URLs will produce JSON containing a reasonable "default" set of properties.
identifier is a simple property: it's a scalar, a string. You can't even substring-match against it, because we treat it as an indivisible atom.
Some stuff about properties:
- Properties can be loci themselves—for example, a type is itself a locus.