Discussion and design ideas for University Web's User API

users.md

le API design

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}]

QUESTIONS

1. Is there a way to keep a RESTful interface but also retrieve just one record per request (Without knowing the user's ID)
2. Should the filtering of records only return exact matches, or partial matches as well? Or have the ability to do one or the other?

V1 API from comments

"/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

V2 API & wrapper from comments

API

"/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"
=> []

Wrapper

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 }

@jordanbyron that's true. What about /user?github=jordanbyron for single lookup and /users_search?q=jordan? Or do you really want to just keep /user? for both paths? In the end it's okay to always return an Array, but it seems a little odd that we change the result type with the wrapper, versus having a wrapper that looks more like this:

module UniversityWeb::User
  def self.find(params = {})
    query_params = params.map{|(k,v)| "#{k.to_s}=#{URI.encode(v.to_s)}.join("&")
    result = service("/users.json?#{query_params}")
    result
  end
end

@semmons99 first off, thanks for showing me (inadvertently) how to do the fancy github syntax highlighting :)

I'm no so hung up on the wrapper returning a different result type, especially since we are creating special helper methods that start with find_by. As an end user I would absolutely expect that to return one object or nil, but maybe that's because I do a ton of rails work.

@jordanbyron

As an end user I would absolutely expect that to return one object or nil, but maybe that's because I do a ton of rails work.

That's where I'm at too. As an end user I'd expect looking for one person would be an object or nil whether I use the wrapper method or the REST api.

Isn't the fancy github syntax highlighting awesome? No more having to do extra indenting from what I copy out of my text editor, and I get syntax highlighting. I believe they're using RedCarpet for markdown support. We should pull it into university-web.

whether I use the wrapper method or the REST api

I guess that is where our opinions differ. I would rather have a fully RESTful API where /users will always return an array of users, and the only way to get one user object is through /users/:id, or by indexing into the array from /users.

I believe they're using RedCarpet for markdown support. We should pull it into university-web.

Hum, I'll have to take a look at that. It should be painless to replace rdiscount. We just have to see how it produces the fancy syntax highlighting stuff.

I believe they're using RedCarpet for markdown support. We should pull it into university-web.

@semmons99, first of all thank you for sharing this.

It's a good feature to add into university-web, it helps the reader easy to read. And I hope later if we have something like code review in university-web, then it will be awesome.