Many endpoints on the Faithful API, particularly for textures, addons, and users are polymorphic. That is to say, their return type depends on the type of data being provided.
For instance, the /v2/textures/nameOrId endpoint has between three and five different possible return shapes depending on how you count:
/v2/textures/307 matches a texture ID and returns a single texture object representing dirt (Texture)/v2/textures/dirt does a name search through the db and returns an array of objects matching the name (Texture[])/v2/textures/307,720 does two ID lookups and returns an array of results (same shape as searching a single name) (Texture[])/v2/textures/307,dirt returns an array where the first element is a single object and the second element is itself an array of results ([Texture, Texture[]])/v2/textures/dirt,stone returns a nested array where both elements are arrays of results (Texture[][] or [Texture[], Texture[]] depending on how you look at it).
Not only does this make the possible return types for the endpoint an absolute nightmare to write API types for, but it also means that users of the API need to expect any of these return types depending on what the user passes in. More troublingly, they also have to make sure that users can't break validation through using special characters—I recently had to fix an issue in complibot where adding a comma in a texture name would cause the shape of the results to completely change since it would start a bulk search.
Additionally, if any of these input types ever overlap it can cause many problems (for instance there are Java Edition GUI textures that are named 1.png, 2.png, etc but are impossible to search since it always gets read as a texture ID). If Mojang were to add a texture with a comma in the name (however unlikely), the endpoint would literally completely working normally.
(The user endpoints have almost exactly the same problem since you can look up multiple users either by id or name using the same endpoint).
Instead of using one endpoint to handle pretty much all searching, I think it would make things much more easy logistically to split these endpoints into several groups (the user collection follows the same principle):
/v2/textures/by-id/307: Texture/v2/textures/by-name/307: Texture[]/v2/textures/by-id-bulk/307,720: Texture[]/v2/textures/by-name-bulk/dirt,stone: Texture[][]
(feel free to bikeshed on the names I came up with them in like 30 seconds)
All of these would have well-defined return types, and it wouldn't be possible to mix different result types (so doing 307,dirt wouldn't create weird partial data structures where each element could be one of three types).
While this would technically be a major breaking change, it would still be entirely backwards compatible with the existing system and hence could be added on top of the existing endpoints without affecting any existing projects.
Many endpoints on the Faithful API, particularly for textures, addons, and users are polymorphic. That is to say, their return type depends on the type of data being provided.
For instance, the
/v2/textures/nameOrIdendpoint has between three and five different possible return shapes depending on how you count:/v2/textures/307matches a texture ID and returns a single texture object representing dirt (Texture)/v2/textures/dirtdoes a name search through the db and returns an array of objects matching the name (Texture[])/v2/textures/307,720does two ID lookups and returns an array of results (same shape as searching a single name) (Texture[])/v2/textures/307,dirtreturns an array where the first element is a single object and the second element is itself an array of results ([Texture, Texture[]])/v2/textures/dirt,stonereturns a nested array where both elements are arrays of results (Texture[][]or[Texture[], Texture[]]depending on how you look at it).Not only does this make the possible return types for the endpoint an absolute nightmare to write API types for, but it also means that users of the API need to expect any of these return types depending on what the user passes in. More troublingly, they also have to make sure that users can't break validation through using special characters—I recently had to fix an issue in complibot where adding a comma in a texture name would cause the shape of the results to completely change since it would start a bulk search.
Additionally, if any of these input types ever overlap it can cause many problems (for instance there are Java Edition GUI textures that are named 1.png, 2.png, etc but are impossible to search since it always gets read as a texture ID). If Mojang were to add a texture with a comma in the name (however unlikely), the endpoint would literally completely working normally.
(The user endpoints have almost exactly the same problem since you can look up multiple users either by id or name using the same endpoint).
Instead of using one endpoint to handle pretty much all searching, I think it would make things much more easy logistically to split these endpoints into several groups (the user collection follows the same principle):
/v2/textures/by-id/307:Texture/v2/textures/by-name/307:Texture[]/v2/textures/by-id-bulk/307,720:Texture[]/v2/textures/by-name-bulk/dirt,stone:Texture[][](feel free to bikeshed on the names I came up with them in like 30 seconds)
All of these would have well-defined return types, and it wouldn't be possible to mix different result types (so doing
307,dirtwouldn't create weird partial data structures where each element could be one of three types).While this would technically be a major breaking change, it would still be entirely backwards compatible with the existing system and hence could be added on top of the existing endpoints without affecting any existing projects.