Add doc content on ID types, IID (internal) vs. global
Problem to solve
Follow up from conversation around epic links API doc references to a 'global ID'. https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/9188#note_136823085
Further details
Good source on the example of requirements/work items: &9203 (comment 1167982332)
id
is the database identifier for that row in the table. There won't be any other work items with that ID on a single GitLab installation.iid
is the identifier within a scope (like a project or group). Project A can have requirementREQ-1
and Project B can have requirementREQ-1
. Internally they're just1
so theREQ
bit is for display and to differentiate these requirement IIDs from issue IIDs.external_id
is a field on theissues
DB table (andepics
). I think it's used for import but I think the suggestion is to re-use it here. We could use it as a legacy identifier for anyone using theREQ-x
requirement IIDs.gid
refers to global ID, which is how we refer to an object by type in GraphQL👉 https://docs.gitlab.com/ee/development/api_graphql_styleguide.html#global-ids
- example:
gid://gitlab/Issue/123
- It's mainly used for APIs and not typed by humans - it contains ID and type for unambiguous DB lookup
- It's got the
ID
notIID
, so it can't be imported/exported between installations
Proposal
Pick a location for this new information and add it to the docs.