GitLab Issues API - Misleading Docs/Nomenclature or Wrong ID being passed?

Description

At the time of writing this, documented in the API docs the Issue API routes usually follow the structure /projects/:id/issues/:issue_iid

However when executing commands such as:

curl --request GET --header "PRIVATE-TOKEN: $GITLAB_TOKEN" "https://gitlab.example.com/api/v3/projects/20/issues/3598"

I receive output of the issue:

{"id":3598,"iid":3364 ...

I would expect an issue where iid==3598

While this is happens to be consistent with the example in the documentation, the docs never specifically say "internal id" is always "id" or a similar caveat (and if they did I missed it. also gross), it still caught me off guard and I don't think it's right. Having the parameter named :issue_iid and using it filter on id is slightly misleading especially when there is an iid field on the object as well.

I have been utilizing the iid (as in, the issue number) in my API scripts, and communications. It is a more friendly number to devs and qa alike since we can append it to a url for viewing. It was working... however a terrible byproduct of me assuming and our team growing -- the id and iid started diverging enough for us to notice a bug in our automation scripts :)

Proposals?

• Change the docs?
• fix the mistake, if there is one
• Heavy suggestion from desk-chair warrior: Nuke the iid nomenclature. id vs iid is too heavy on the eyes and head in my opinion. id==issue_number perhaps? edit: conversely global_id = id
• "Keep coding that login page, kid!" /close

Sorry for the lacking issue detail... End of monday rush! If you need me to elaborate on anything please do not hesitate to ping me.

Cheers!