Requirements for a V3(beta)

[GreatNovaDragon]

First of, i am taking reference to this message by @Naramsim here

Hi guys, if you like we can start working on a V3beta version! If you are volunteering we can start writing some code.

On my side, I can only help you with the deployment part, since I don't really have time to implement such complicated things now. We can start anew and use or drop Django, same goes for CSVs, we could switch to other formats. Reply if we can on you!

I'll copy this comment over at #966.

Originally posted by @Naramsim in #1037 (comment)

As much as i personally would love to start anew, there are some informations missing before one could actually do such,

What are the requirements to an v3 (Technical or Modelwise)? What should be carried over from v2? What explicitely not? Or does nothing matter and someone should just start?

[Naramsim]

Hi, so far the APIv2 had a great success and the only big problem for the user is understanding the difference between pokemon, pokemon-species, pokemon-forms.

I say we cannot modify the current properties nor delete them but only add them for the current API due to the huge consumption, as we have done so far.

That said other small problems were raised in the past. I'll write down a small list of thoughts

1. encounters return is different than other endpoints' #332
2. We use changelog tables. In my mind, I thought we might have an API that's generation-centric, such as:

/api/v3/generation-i/pokemon/bulbasaur
/api/v3/generation-iii/pokemon/bulbasaur
/api/v3/generation-i/item/old-rod
/api/v3/generation-iii/item/old-rod

But maybe this adds difficulties in understanding.
3. We are serving static files so the new one should also be able to be parsable and servable with a simple function or we'll incur again in terrific costs.
4. We could start from a predefined standard as OpenAPI and/or use an API generator.
5. We might just work on the GraphQL current API and promote it to V3. Especially if we could strip the pokeapi_v2_ prefix from all the fields. And maybe getting rid of pokemon-forms and pokemon-species and condense them into a single PG table that then can be retrieved with GQL.
6. GQL now has no costs, but it crashes when someone submits a heavy query. We should at least upgrade to 2cpu8ram machine that's about 50$ per month, but our current ad revenue is 30$/m and the donations are basically non-existing.
7. A big problem for us is finding people to update the data. It would be cool to automate it and maybe build the data from external sources without having to maintain CSV files.

To be honest the point 5 is really cool!

This are just some thoughts.

[GreatNovaDragon]

I'll add my own personal thoughts, with the

0. Some of my thoughts are also based upon the fact that in semantic versioning, a major version change is accompanied by Breaking API Changes.
1. I personally dont like the pokemon, pokemon-species, pokemon-forms table format, cause it doesnt combine with a relatively more modern understanding of what a "Pokemon" is.
2. the current csv files are not that easy to understand how to edit, unless you already have Database Knowledge.
3. that there is big doubling with the ID and the Name fields in the NamedRessources. The ID could aswell actually just be the name, in the named-ressources.

Additional understanding question: How/Where are the static files served? Is it just json-formatted files outputted somewhere?
4. If its just json-formatted files somewhere on github, couldn't we actually just forego any actual programming of an csv -> json conversion, and directly edit the json files, and a CI-Run to verify that the edit works.

[omniuni]

One thing I would, as a user, specifically request is NOT to drop non-GQL support.

GraphQL is powerful, but it's a huge pain to interface with if you aren't using a pretty heavyweight library to do most of it for you.

So far, the biggest complaints I have that I would like to see addressed:

• The ID and name for a resource should be included with any data point. This is mostly for items with a URL. Whether it's another API endpoint or the graphic URL, there should be separate fields that give the id (say, 1) and key (say, bulbasaur).
• The weirdness with encounters data should be addressed. In addition to the changes noted in the PR linked above, the encounter-method endpoints are somewhat broken, and show what I'm fairly certain should be a description under the name field. Also, several games, such as shining-diamond just don't show up at all, even though I'm fairly certain that there is indeed data for them under the base version, such as diamond.

[GreatNovaDragon]

Not really actively writing code for this, and rather preparing schema notes for it privately, but I would have had the id for bulbasaur not be 1 but bulbasaur, so what is currently listed as name in this iteration

The ID gives one the weird flavor as if it were the National Dex Number, but with Mega Venusaur the earliest, we would need to already diverge there. Would the id be 4? 0003M? M0003? That would be a notation that would need to be invented first. (In the current db, its 10033, which barely makes sense to me).
in my opinion it should be venusaur-mega.
string based IDs are not unheard of, given that some like to employ UUIDs for that.

One big issue that pops up in my mind is, that localized strings are kinda handled terribly, IMO. For each little localized string, you'd have to search up the language again and again. (At least in PokeAPI.Net its an often repeat Pokemon.Names.Where(n => n.Language == "de").FirstOrDefault(); just to possibly get an name in german.)
Inspired by like fandom wikis , one could have refer the url https://pokeapi.co/api/v3/pokemon/ditto to exclusively english data, and have https://pokeapi.co/api/v3/de/pokemon/ditto to the same data in, in this case, german. alternatively, one could also just use subdomains, like wikipedia for this alias https://de.pokeapi.co/api/v3/pokemon/ditto, or another alternative, https://dpokeapi.co/api/v3/pokemon/ditto/de
How'd that be handled in the background? Still a big question, i guess the actual database schema would still refer to an languages table or something, a thing that already just looks annoying in an simplified ERM

There's also the big question, where does each other want what data. Loaded Question, i know.
Example: Does one actually want an separate Berry endpoint, or have an optional Berry-Datapoint at the actual Item endpoint, that appears if something is a berry or not.

The Evolution Endpoint: The current Evolution Detail Type seems like a big mess. Gamefreak progressively adds evolution details that are only there for single pokemon, turn_upside_down is like the most infamous one when Inkay released, and the only one that is listed in the api. Actually Terrible in database design.
Should that actually exist, or should just have what is like an trigger field that is like "level, item, trade, special" (simplified), and the evolution-detail field is a string that is filled depending on the trigger. (Thats maybe more dynamic than what someone wants)

An issue i have with the current DB:
Do we actually need Pokemon Conquest Data? I dont even know why its here, why would someone want it there. What was veekun cooking there? from an biased viewpoint, i'd say Mystery Dungeon Data, and on an unbiased view Legends: Arceus Data is more asked for, especially since Legends: Arceus is mainline, but changed many a mechanic.