A consumer needs to lookup a single user by their github name (jordanbyron). That consumer doesn't know the user's ID. There is a possibility to also search by email and twitter.
"/users.json?github=jordanbyron"
=> [{github: "jordanbyron", id: 1}]
When there are no results an empty array is returned
"/users.json?github=noexist"
=> []
When there are partial matches, multiple results can be displayed
"/users.json?github=jo"
=> [{github: "jordanbyron", id: 1}, {github: "joeuser", id: 1}]
- Is there a way to keep a RESTful interface but also retrieve just one record per request (Without knowing the user's ID)
- Should the filtering of records only return exact matches, or partial matches as well? Or have the ability to do one or the other?
"/users.json?search=jo"
=> [{github: "jordanbyron", id: 1}, {email: "userjoe", id: 1}, {twitter: "iamjoelman", id: 1}]
If there are no fields which match the search
params
"/users.json?search=zzzzzzzz"
=> []
When github
, twitter
, or email
params are passed only one result is returned
"/users.json?github=jordanbyron"
=> {github: "jordanbyron", id: 1}
When one of the above params are used and there are no matches, nil is returned
"/users.json?github=noexists"
=> nil
"/users.json?search=jo"
=> [{github: "jordanbyron", id: 1}, {email: "userjoe", id: 1}, {twitter: "iamjoelman", id: 1}]
If there are no fields which match the search
params
"/users.json?search=zzzzzzzz"
=> []
When github
, twitter
, or email
params are passed the result is still in an array
"/users.json?github=jordanbyron"
=> [{github: "jordanbyron", id: 1}]
When one of the above params are used and there are no matches, an empty array is returned
"/users.json?github=noexists"
=> []
module UniversityWeb::User
def self.find_by_github(github_account_name)
result = service("/users.json?github=#{github_account_name}") # Makes a request to the server's API
result.first # result == [ { github: "jordanbyron", id: 1 } ]
end
end
UniversityWeb::User.find_by_github("jordanbyron")
=> { github: "jordanbyron", id: 1 }
@samnang & @ericgj clearly I am torn here. I'd like to stay as close to the RESTful style as possible, but also make an API that is nice to use. Sure calling
first
on an array isn't that hard, but is that an interface that is pleasant to work with? I'm not sure. With the changes we made, it is very clear that when requesting records for a givenemail
,github
, ortwitter
name you are asking for one record, and therefore should expect a single record.So which is the best way? I'm still not sure. Working on both sides of the problem (API design and API consumption) I don't know if I can be 100% satisfied. The last possible thing I can think of is creating a nice client library that wraps the API and handles returning one or nil records when looking up a user via the three fields (email, github, or email). So the server will still return an array of users, but the library will return one. For example:
I think that solves all of the issues which were brought up but still has a nice end user experience. Thoughts?