Replace `listing()` methods with consistent solution
Art4 opened this issue · comments
The listing() methods returns an array as name => id or id => name. These methods are inconsistent implemented and are based on a cache filled up by a previous call of list() what can be confusing.
We have to find a consistent solution for this problem.
Todo
-
CustomField::listNames() -
Group::listNames()#398 -
IssueCategory::listNamesByProject() -
IssueStatus::listNames() -
Project::listNames() -
Role::listNames() -
TimeEntryActivity::listNames() -
Tracker::listNames() -
User::listLogins() -
Version::listNamesByProject()
Proposal
I've looked into every Api class and would like to propose replacing all listing() methods with methods like listNames(): array, listNamesByProject(): array and listLogins(): array. The response should be always an array with the int ids as keys and the names as value. This methods will be the base for a future replacement or drop of the getIdByName() methods. The nomenclature will allow us to add further methods such as Project::listIdentifiers() or User::listEmails() in the future.
The $reverse argument was introduced because of name collisions and can be dropped. The result will always have the int IDs as array key, so collisions should be avoided.
The $params argument to filter the entries will no longer supported. Instead all entries should be loaded by using multiple requests with 'limit' => 100 if necessary. The result will be cached in the api class in a special property, separated from the properties using by the all() methods.
The $forceUpdate argument can be dropped as well, because "deleting the cache" could be realized by dropping and reinstantiate the api class.
All in all, it looks like this:
| mid-level API | listing() arguments | listing() returns | replacement |
|---|---|---|---|
| Attachment | - | - | - |
| CustomField | $forceUpdate, $params | ['name' => id] | listNames(): [id => 'name'] |
| Group | $forceUpdate | ['name' => id] | listNames(): [id => 'name'] |
| Issue | - | - | - |
| IssueCategory | $projectIdentifier, $forceUpdate | ['name' => id] | listNamesByProject($projectIdentifier): [id => 'name'] |
| IssuePriority | - | - | - |
| IssueRelation | - | - | - |
| IssueStatus | $forceUpdate | ['name' => id] | listNames(): [id => 'name'] |
| Membership | - | - | - |
| News | - | - | - |
| Project | $forceUpdate, $reverse, $params | [id => 'name'], ['name' => id] | listNames(): [id => 'name'] |
| Query | - | - | - |
| Role | $forceUpdate | ['name' => id] | listNames(): [id => 'name'] |
| Search | - | - | - |
| TimeEntry | - | - | - |
| TimeEntryActivity | $forceUpdate | ['name' => id] | listNames(): [id => 'name'] |
| Tracker | $forceUpdate | ['name' => id] | listNames(): [id => 'name'] |
| User | $forceUpdate, $params | ['login' => id] | listLogins(): [id => 'login'] |
| Version | $projectIdentifier, $forceUpdate, $reverse, $params | [id => 'name'], ['name' => id] | listNamesByProject($projectIdentifier): [id => 'name'] |
| Wiki | - | - | - |