Web API sketch

gistfile1.txt

HTTP request headers indicate API version and representation format:
  Accept: application/vnd.koha.liblime.com+json; version=0.01
  Accept: application/vnd.koha.liblime.com+xml; version=0.01

Defaults to JSON and most recent API version.


POST /catsearch?query=asdf   #Generates catalog search result set and returns HTTP 201 with Location set to search ID

GET /catsearch/12345   #Returns the result set, defaults e.g. start=0, count=20
GET /catsearch/12345?count=50
GET /catsearch/12345?start=100&snippets=true   #Include HTML snippets in result set
POST /catsearch/12345?sort=title+desc   #change sort order of result set

GET /title/87654
GET /title/87654/snippet  #HTML fragment for search result rendering
GET /title/87654/reserves  #List of pending reserves on title
GET /title/87654/items  #List of items associated with title
GET /title/87654/full  #Include title's reserves, items, etc.
POST /title/87654/reserves?patron=84820&item=94943&pickup=BRANCH1  #Place an new item-level reserve

GET /item/94943
GET /item/94943/issues
POST /item/94943/issues?patron=84820&branch=BRANCH1   #Issue the item to a patron
POST /item/94943/issues?branch=BRANCH1   #Item returned at branch1

GET /branch   #Get a list of all branches
GET /branch/BRANCH1   #Get info specific to BRANCH1

GET /patron/84820
GET /patron/84820/reserves
GET /patron/84820/issues
GET /patron/84820/fines
POST /patron/84820/fines/432?amount=1.00   #Pay $1.00 toward fine 432

Not clear how to arrange authentication and authorization
? POST /session?username=qwerty&password=zxcvb   #request a session

Other decisions to be made:
* How to differentiate between a public view of, e.g., an item's data and a privileged view? The privileged view could have information about which patron currently has the item checked out. This isn't suitable for public distribution. At the same time, it's not very RESTful to change the representation based on who is looking at a particular ID. One approach would be to have "/item/12345" (or "/staff/item/12345") and "/opac/item/12345", but offering two IDs for what is ultimately the same underlying resource smells to me. I guess I'm leaning toward changing the representation based on the permissions granted to the requester, but only because I dislike that approach somewhat less.