API UX: internal IDs shouldn't leak

[noerw]

Working with the gitea API in tea, I noticed some shortcomings:

• Labels are referenced by ID when attaching to issues / pulls. Users don't know this ID, and don't need to know; the label name is the user facing ID. Also, there is no way to look up a label ID by label name.
• Similar problem exists with issue milestones: To assign a milestone, I need to know the internal ID, which is not how users identify milestones.

I propose to resolve these name <-> ID mappings internally and not leak this internal data model detail. Changes would be breaking, but IMO they're worth it.
This increases both usability as well as performance, as no more extra roundtrip to resolve IDs would be needed.

[lunny]

milestone should have an index like Issues/PRs

[lafriks]

Problem is that currently labels are not required to have unique name so this will not work if they have same name. Also how would you know if that is organization or repository label as they also can have same name.

[CirnoT]

milestone should have an index like Issues/PRs

Impossible, because organization labels are shared.

[CirnoT]

Problem is that currently labels are not required to have unique name so this will not work if they have same name

That should definitely be enforced.

Also how would you know if that is organization or repository label as they also can have same name.

Sets should be merged internally, in case of duplicates repo label takes precedence over organization label

[a1012112796]

Labels are referenced by ID when attaching to issues / pulls. Users don't know this ID, and don't need to know; the label name is the user facing ID. Also, there is no way to look up a label ID by label name.

In curent design, user should get it by GET /repos/{owner}/{repo}/labels which will include label id response.