then change the current API to something like this:
GET users = returns info for typeahead if authenticated?
GET users/:username = returns user details
PUT users/:username = authenticates user, updates user details and returns user details if successful
POST users, users/:username = register a new user (with throttling to prevent random registration) returns user details if successful
DELETE users/:username = remove a user and their data. ie a user wants to exit the system, requires extra special info to run (don't implement now) returns true if successful
PUT users/:username/password = reset password returns user details if successful
OPTIONS users/ = accept CORS
GET corpora/:dbname = returns public corpus if not authenticated, corpus details if authenticated
PUT corpora/:dbname = updates corpus if authenticated
POST corpora/:dbname = create new corpus (dbname optional, instead can build and by server using title) returns corpus details if successful
DELETE corpora/:dbname = delete a corpus, remove all data, requires extra special info to run (don't implement now) returns true if successful
SEARCH corpora = search all corpora authenticated user has access to
SEARCH corpora/:dbname = search a corpus if authenticated
GET corpora/:dbname/users/:username/role/:role = returns a list of users on a corpus, sorted by role
PUT corpora/:dbname/users/:username/role/:role = update a user's role on a corpus, returns users roles on corpus if successful
POST corpora/:dbname/users/:username/role/:role = add a user to a role on a corpus, returns users roles on corpus if successful
DELETE corpora/:dbname/users/:username/role/:role = remove a user from a corpus or remove a users role from a corpus, returns true if successful
all APIs above for "corpora" above can be replaced by "fielddbs"
resource/:id/sort=-datemodified&limit=20
corpora/:dbname/data/recently_commented
corpora/:dbname/data/fields=utterance,translation
The right way to include pagination details today is using the Link header introduced by RFC 5988.
rate limiting to an API. RFC 6585 introduced a HTTP status code 429 Too Many Requests to accommodate this.
X-Rate-Limit-Limit - The number of allowed requests in the current period
X-Rate-Limit-Remaining - The number of remaining requests in the current period
X-Rate-Limit-Reset - The number of seconds left in the current period
the authentication credentials can be simplified to a randomly generated access token that is delivered in the user name field of HTTP Basic Auth. The great thing about this is that it's completely browser explorable - the browser will just popup a prompt asking for credentials if it receives a 401 Unauthorized status code from the server. OAuth 2 uses Bearer tokens & also depends on SSL for its underlying transport encryption.
cesine
commented
10 years ago 
Read these about a RESTful Web service API:
then change the current API to something like this:
OPTIONS corpora/ = accept CORS
*others corpora/:dbname/doc/:id, corpora/:dbname/datalists/:id, corpora/:dbname/sessions/:id, corpora/:dbname/conversations/:id, corpora/:dbname/utterances/:id, corpora/:dbname/utterances/:id?embed=textgrid corpora/:dbname/audio/:id, corpora/:dbname/video/:id, corpora/:dbname/image/:id, corpora/:id/dictionary/:id, corpora/:id/lexicon/:id, corpora/:id/morphemes/:id, elanguages/:id/dictionary/:id, ilanguages/:id/lexicon/:id
The right way to include pagination details today is using the Link header introduced by RFC 5988.
rate limiting to an API. RFC 6585 introduced a HTTP status code 429 Too Many Requests to accommodate this.
X-Rate-Limit-Limit - The number of allowed requests in the current period X-Rate-Limit-Remaining - The number of remaining requests in the current period X-Rate-Limit-Reset - The number of seconds left in the current period
the authentication credentials can be simplified to a randomly generated access token that is delivered in the user name field of HTTP Basic Auth. The great thing about this is that it's completely browser explorable - the browser will just popup a prompt asking for credentials if it receives a 401 Unauthorized status code from the server. OAuth 2 uses Bearer tokens & also depends on SSL for its underlying transport encryption.
http://qzaidi.github.io/2013/07/20/surprises/