[API][v3] Inconsistencies with the use of type, type_id, and id

I noticed some inconsistencies with the use and reference of the ID for type(s).

In places where the data is returned, the key is simply `id`
In `.types/{type_id}` (and children) it is referenced as `type_id`, but the response body uses only `id`
In `/users/{user_id}/collected_items`, the key is `type`, but requesting a `type_id`

Normally I wouldn't have a strong opinion how to approach homogenizing this, and in reality there is way too much dependent on this in the backend... but in this instance I would suggest standardizing on `type_id`.

At the very least, please update the `/users` tree to use `type_id` as `type` is a reserved name in Python, and I can't use it as a variable. This causes some problems with the transparent nature of passing inputs as `kwargs` to the api from collector methods.

It's easy to workaround, so not a big deal. Just throwing it on the radar.

Thanks!!

Hello,

I'm not very enthusiast about adding "_id" or "_code" to all query string parameters.

Would you rather search with "/types?q=test&issuer=france&category=coins&page=1" or "/types?q=test&issuer_code=france&category_code=coins&page_number=1"? I personally prefer the first option, and I dont' believe it's an issue that "issuer" in the query string parameter is only a code, whereas it is an object in the response. You naturally expect only codes and IDs in the query string.
In my opinion, the same applies for the query string parameter "type" in "/users/{user_id}/collected_items": naming "type_id" looks unnecessary.

It's true that the path parameters (e.g. "{type_id}" in "/types/{type_id}/issues") have the unnecessary suffix "_id" and they are not consistent with the query string parameters, which don't have the suffix. This is only a documentation matter, I'm happy to change to "{user}", "{type}", etc. If it helps understanding.

I'd be happy to get other opinions or links to best practices.

For me the biggest thing is being careful of using reserved names that are common in languages, so a parameter of 'type' is really tricky to use.

For example in python, when defining a method with an input param of 'type' (to match auto generated fields from API Spec), Python throws a WARN because 'type' is a reserved name and *should not* be used as a variable.

I think a lot of this really plays into inconsistencies with how similarly named variables or parameters are being used. Generally speaking I am of the opinion that slightly more intuitive parameter names are always better (type_id or typeId, is better than type) because it infers the desire for an ID of TYPE, rather than begging the question: What about the type... ID, Label, Name, Yes/No?

Obviously when you are familiar with the context of how it is being used it's a no-brainier.. obviously type refers to the ID of the type.

I wouldn't ask you to overhaul or change this globally because it would likely be a massive effort for very little gain.

My specific ask was to change that param name (type => type_id) on this one path (/users/{user_id}/collected_items) to enable better dynamic ingestion of API Spec and better adherence to best practices of major languages.

I will also say that there is ZERO urgency around this. Nothing is broken that can't be worked around easily... I just saw this and wanted to call it out for visibility, incase you were planning major backend overhauls and wanted to have a list of inconsistencies that could be corrected.

This is a case that "Won't Fix" would be acceptable and appropriate.