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 }

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.