Exact search using gitlab API

Searching for an exact match is not available for API. This functionality supports getting a "list" of users that match a particular search term.

If you need an exact match, a workaround would be to iterate over the returned list of users and search for an exact match in it.

Some of the scripts i use require exact username or mail to initiate mail communication. Could you please help to achieve it.?

ZD: https://gitlab.zendesk.com/agent/tickets/79696

added customer in GitLab FOSS label

added feature proposal in GitLab FOSS label

cc// @victorwu

/cc @markglenfletcher @rymai

changed milestone to %Next 2-3 months in gitlab-foss

added Discussion in GitLab FOSS label

@david008 You could use the Users API (https://docs.gitlab.com/ee/api/users.html#single-user) if it would support getting a user by their username, not only their ID...

Would that fulfill your request?

I think the change would be quite simple to support that:

diff --git a/lib/api/users.rb b/lib/api/users.rb
index 1825c90a23..d5aea9a5c0 100644
--- a/lib/api/users.rb
+++ b/lib/api/users.rb
@@ -85,7 +85,7 @@ module API
         requires :id, type: Integer, desc: 'The ID of the user'
       end
       get ":id" do
-        user = User.find_by(id: params[:id])
+        user = find_user(params[:id])
         not_found!('User') unless user && can?(current_user, :read_user, user)
 
         opts = current_user&.admin? ? { with: Entities::UserWithAdmin } : {}

My script searches using mail ID. Please see the result below. It gives so many users as output.

[root@host ~]# curl -s -k GET --header 'PRIVATE-TOKEN: ' https://gitlab.host.ext.com/api/v3/users?search=ning.fan@xxx.com [{"name":"Fan Ning","username":"nifan","id":11032,"state":"active","avatar_url":null,"web_url":"https://gitlab.host.ext.com/nifan","created_at":"2017-08-04T18:01:33.226Z","is_admin":false,"bio":null,"location":null,"skype":"","linkedin":"","twitter":"","website_url":"","organization":null,"last_sign_in_at":null,"confirmed_at":"2017-08-04T18:01:33.227Z","email":"ning.fan@xxx.com","color_scheme_id":1,"projects_limit":1000,"current_sign_in_at":null,"identities":[],"can_create_group":true,"can_create_project":true,"two_factor_enabled":false,"external":false},{"name":"Fan Luning","username":"lunfan","id":9905,"state":"active","avatar_url":null,"web_url":"https://gitlab.host.ext.com/lunfan","created_at":"2017-06-08T03:07:08.821Z","is_admin":false,"bio":null,"location":null,"skype":"","linkedin":"","twitter":"","website_url":"","organization":null,"last_sign_in_at":"2017-06-08T03:07:08.961Z","confirmed_at":"2017-06-08T03:07:08.822Z","email":"luning.fan@xxx.com","color_scheme_id":1,"projects_limit":1000,"current_sign_in_at":"2017-06-30T09:31:23.930Z","identities":[{"provider":"ldapmain","extern_uid":"uid=lunfan,ou=People,ou=ULTIMA,o=EEDIR"}],"can_create_group":true,"can_create_project":true,"two_factor_enabled":false,"external":false}][

@david008 Ok, I think exact match on the email could also be added, but we could start by adding the possibility to request the API for a given username (as stated above) very easily.

I am using gitlab CE installed with help of rpm. So i dont know much about the code changes which has to be made in backend. Could you please elaborate more on this so that i can ask my senior to check on this.

So i dont know much about the code changes which has to be made in backend.

@david008 Don't worry we will handle the code change, I just wanted to know if fetching a user by username would work for you?

Unfortunately Search by username also results multiple output.

[root@host ~]# curl -s -k GET --header 'PRIVATE-TOKEN: ' 'https://gitlab.host.ext.com/api/v3/users?search=ifan' [{"name":"Fan Ning","username":"nifan","id":11032,"state":"active","avatar_url":null,"web_url":"https://gitlab.host.ext.com/nifan","created_at":"2017-08-04T18:01:33.226Z","is_admin":false,"bio":null,"location":null,"skype":"","linkedin":"","twitter":"","website_url":"","organization":null,"last_sign_in_at":null,"confirmed_at":"2017-08-04T18:01:33.227Z","email":"ning.fan@xxx.com","color_scheme_id":1,"projects_limit":1000,"current_sign_in_at":null,"identities":[],"can_create_group":true,"can_create_project":true,"two_factor_enabled":false,"external":false}, {"name":"Fang Yi Xin","username":"yifang","id":9055,"state":"active","avatar_url":null,"web_url":"https://gitlab.host.ext.com/yifang","created_at":"2017-04-25T12:00:31.925Z","is_admin":false,"bio":null,"location":null,"skype":"","linkedin":"","twitter":"","website_url":"","organization":null,"last_sign_in_at":null,"confirmed_at":"2017-04-25T12:00:31.926Z","email":"yi_xin.fang@xxx.com","color_scheme_id":1,"projects_limit":1000,"current_sign_in_at":null,"identities":[],"can_create_group":true,"can_create_project":true,"two_factor_enabled":false,"external":false}, {"name":"Hao Lifang","username":"lifahao","id":6297,"state":"active","avatar_url":null,"web_url":"https://gitlab.host.ext.com/lifahao","created_at":"2016-12-16T05:09:14.664Z","is_admin":false,"bio":null,"location":null,"skype":"","linkedin":"","twitter":"","website_url":"","organization":null,"last_sign_in_at":"2016-12-16T05:09:14.767Z","confirmed_at":"2016-12-16T05:09:14.622Z","email":"lifang.hao@xxx.com","color_scheme_id":1,"projects_limit":1000,"current_sign_in_at":"2016-12-16T05:09:14.767Z","identities":[{"provider":"ldapmain","extern_uid":"uid=lifahao,ou=People,ou=ULTIMA,o=EEDIR"}],"can_create_group":true,"can_create_project":true,"two_factor_enabled":false,"external":false}, {"name":"Epifanov Nikolay","username":"r49742","id":5171,"state":"active","avatar_url":null,"web_url":"https://gitlab.host.ext.com/r49742","created_at":"2016-10-21T13:15:58.715Z","is_admin":false,"bio":null,"location":null,"skype":"","linkedin":"","twitter":"","website_url":"","organization":null,"last_sign_in_at":"2016-10-21T13:15:58.834Z","confirmed_at":"2016-10-21T13:15:58.673Z","email":"nikolay.epifanov@xxx.com","color_scheme_id":1,"projects_limit":1000,"current_sign_in_at":"2016-10-21T13:16:32.753Z","identities":[{"provider":"ldapmain","extern_uid":"uid=r49742,ou=People,ou=ULTIMA,o=EEDIR"}],"can_create_group":true,"can_create_project":true,"two_factor_enabled":false,"external":false}, {"name":"Fang Shuai","username":"shuaifan","id":4709,"state":"active","avatar_url":null,"web_url":"https://gitlab.host.ext.com/shuaifan","created_at":"2016-09-25T02:17:58.970Z","is_admin":false,"bio":null,"location":null,"skype":"","linkedin":"","twitter":"","website_url":"","organization":null,"last_sign_in_at":"2016-09-25T02:17:59.125Z","confirmed_at":"2016-09-25T02:17:58.923Z","email":"shuai.1.fang@xxx.com","color_scheme_id":1,"projects_limit":1000,"current_sign_in_at":"2016-09-25T02:17:59.125Z","identities":[{"provider":"ldapmain","extern_uid":"uid=shuaifan,ou=People,ou=ULTIMA,o=EEDIR"}],"can_create_group":true,"can_create_project":true,"two_factor_enabled":false,"external":false}, {"name":"Liu Huifang","username":"huifaliu","id":3473,"state":"active","avatar_url":null,"web_url":"https://gitlab.host.ext.com/huifaliu","created_at":"2016-07-20T02:42:50.458Z","is_admin":false,"bio":null,"location":null,"skype":"","linkedin":"","twitter":"","website_url":"","organization":null,"last_sign_in_at":"2017-07-14T05:31:30.524Z","confirmed_at":"2016-07-20T02:42:50.423Z","email":"huifang.liu@xxx.com","color_scheme_id":1,"projects_limit":1000,"current_sign_in_at":"2017-09-06T07:51:45.981Z","identities":[{"provider":"ldapmain","extern_uid":"uid=huifaliu,ou=People,ou=ULTIMA,o=EEDIR"}],"can_create_group":true,"can_create_project":true,"two_factor_enabled":false,"external":false}] [root@host ~]#

Search by exact username :- [root@host ~]# curl -s -k GET --header 'PRIVATE-TOKEN: ' 'https://gitlab.host.ext.com/api/v3/users/nifan' {"error":"404 Not Found"}[root@host ~]#

Search by ID :- [root@host ~]# curl -s -k GET --header 'PRIVATE-TOKEN: ' 'https://gitlab.host.ext.com/api/v3/users/11032' {"name":"Fan Ning","username":"nifan","id":11032,"state":"active","avatar_url":null,"web_url":"https://gitlab.host.ext.com/nifan","created_at":"2017-08-04T18:01:33.226Z","is_admin":false,"bio":null,"location":null,"skype":"","linkedin":"","twitter":"","website_url":"","organization":null,"last_sign_in_at":null,"confirmed_at":"2017-08-04T18:01:33.227Z","email":"ning.fan@xxx.com","color_scheme_id":1,"projects_limit":1000,"current_sign_in_at":null,"identities":[],"can_create_group":true,"can_create_project":true,"two_factor_enabled":false,"external":false}[root@host ~]#

Search by exact username :- [root@host ~]# curl -s -k GET --header 'PRIVATE-TOKEN: ' 'https://gitlab.host.ext.com/api/v3/users/nifan' {"error":"404 Not Found"}[root@host ~]#

@david008 This is what I was thinking of in https://gitlab.com/gitlab-org/gitlab-ce/issues/34703#note_40479201. As you can see the endpoint doesn't support fetching by username, only by ID, but the change to support that is quite simple so I just wanted to ensure that this would fulfill your need. Basically when fetching https://gitlab.host.ext.com/api/v4/users/nifan, you'd get the result you currently get for https://gitlab.host.ext.com/api/v4/users/11032.

Note: The change would only be available in the V4 API!

@rymai : I would like to know whether V4 API will provide exact result or it will be provide results like above while doing search.

curl -s -k GET --header 'PRIVATE-TOKEN: ' 'https://gitlab.host.ext.com/api/v3/users?search=ifan'

results 4 or more username and details.

I would like to know whether V4 API will provide exact result

@david008 Yes. If we implement this change, https://gitlab.host.ext.com/api/v4/users/nifan would return only one result (or none if the username doesn't exist, of course).

Just to confirm. What if there are two users named 'ifan' and 'nifan'. what will be the search result for "https://gitlab.host.ext.com/api/v4/users/ifan" ?

What if there are two users named 'ifan' and 'nifan'. what will be the search result for "https://gitlab.host.ext.com/api/v4/users/ifan" ?

@david008 It will return the details of the ifan user since the user exists. There is no "fuzzy" search involved in the /users/:id endpoint, only exact match.

@david008 Actually, it seems that this is already possible to get a single user metadata. This is currently documented under https://docs.gitlab.com/ee/api/users.html#for-admins but the documentation is outdated since this doesn't require to be an admin, the endpoint is publicly accessible, e.g. https://gitlab.com/api/v4/users.json?username=rymai

https://gitlab.com/gitlab-org/gitlab-ce/issues/38095 has been created to update the documentation to reflect that.

Note that if you make the request with an admin token, the results will include more fields.

Thanks.. :) This will really help me in modifying my script.

But here also i doubt some issues. If an username does not exist it is not throwing any errors. Why is it like that.?

[root@host ~]# curl -s -k GET --header 'PRIVATE-TOKEN: ' 'https://gitlab.host.ext.com/api/v3/users?username=kunjumo' ** [] ** [root@host ~]#

If an username does not exist it is not throwing any errors. Why is it like that.?

@david008 Because the endpoint returns a list of users, and the username param acts as a "filter" so if no users match this filter, you get an empty array []. You can use that to know if your request matches a user or not.

moved from gitlab-foss#34703 (moved)