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 https://github.com/PokeAPI/pokeapi/issues/1037#issuecomment-1973742468

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. https://github.com/PokeAPI/pokeapi/issues/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 repeatPokemon.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.

[GreatNovaDragon]

I get why FlavorTexts/Proses are localized, but do we actually want the same for Effect Texts? Related: Why does the ShortEffect Text even exist?

[Naramsim]

I agree with the ID being the name of the pokemon! And getting rid of the conquest data.

[EKO-GITHUB]

@GreatNovaDragon the long effect / short effect texts make sense for some categories such as moves / abilities. The long effect can get extremely long without any overview of what the move actually does, so a short effect can be useful. For example the substitute move I've rewritten, the long effect goes on for about 4 times the amount shown:

I didn't like the data provided by PokéAPI so I've rewritten all of them along with a custom parser.

[GreatNovaDragon]

I am currently writing some code for some reduced personalized usecases in a repo mirrored to GreatNovaDragon/pokeapi-nova i probably could later expand that into full API that displays most of the PokeAPI Data.

Will still take a while

[GreatNovaDragon]

Several things like Moves, Abilities, Pokemon have an Generation field, which should be replaced with VersionGroup. Like, platinum version-group already introduced an alternate Pokemon Form in Girantina Origin Forme, so i dont know why that already wasnt in veekun/pokedex, maybe they thought it was a oneoff?

[EKO-GITHUB]

Several things like Moves, Abilities, Pokemon have an Generation field, which should be replaced with VersionGroup. Like, platinum version-group already introduced an alternate Pokemon Form in Girantina Origin Forme, so i dont know why that already wasnt in veekun/pokedex, maybe they thought it was a oneoff?

As far as I'm aware Veekun stopped just before SWSH. Did they already include USUM data? USUM introduced a bunch of Gen 7 moves that were released after SM, so just listing Gen 7 for is not completely correct as SM does not include those moves. There are also moves that exist in the USUM data but not in the SM game data, so a Pokémon knowing those moves can not be imported into that version group. (for example Mind Blown) There are also Gen 6 moves introduced with ORAS that are not present in the XY game data so importing those will not work (e.g. Origin Pulse) The most correct way would be to list the specific version group that move was introduced in but that requires a bit of research

[GreatNovaDragon]

In GreatNovaDragon/PokeAPI-Nova (far from finished), I have set the "IntroducedIn" field as a Version group.

Given that for #1020 I am already doing my own research, finding out in which version group something released in is the smallest issue.

[phalt]

Just chimining in to say I'm very busy with some pretty awful things happening in my life at the moment (my youngest son just passed away). So I don't really have time to comment or contribute other than saying: I give my grace (whatever that is worth) for you all to build this. I trust ya 😄

[EKO-GITHUB]

I'm very sorry to hear that @phalt no parent should ever go through that.