Suggestions for users API

[jiho]

In the returned object:

• order should be: id, name, email, organisation, country, reason, creation date, active
• rename:
  usercreationdate -> creation_date
usercreationreason -> usage_description
active -> is_active

/users
Title: Get All Users
Description -> "Return the list of all users. This endpoint is for application administrators only; for others, the list will be empty. Consider /users/search as an alternative."

/users/me
Rename -> user/me because we get only one user as a result.
Description: "Return the user currently authenticated."

/users/my_preferences/{project_id}
Title: Get/Set One Preference for Current User
GET: document key like in the PUT version
Description: Return/Set one preference, for the currently authenticated user in the designated project.
Would it be possible to know which keys are valid, from here?

users/search
Search for Users by Name
Rename by_name -> name (or keep the by_ for all similar searches in the api, but it may be a bit cumbersome)
Consider surrounding the query by % automatically, to avoid having to explicitly specify this. The search is made case-insensitive already, so we're not searching for an exact match of the user name anyway.

/users/{user_id}
Get a User by id
Rename -> /user/{user_id}, same reason

[jiho]

Consider id -> user_id in the output structure, to be consistent with how it is called in /users/{user_id} for example. But this is a larger convention: do we prefix the id everywhere or not; i.e. is the field id in table users called id or users_id in the db?

[grololo06]

Old debate over API naming: singular/plural : https://stackoverflow.com/questions/6845772/rest-uri-convention-singular-or-plural-name-of-resource-while-creating-it
Just for the joke I could do as well /maybe_user/{user_id}, because 0 entity returned is possible and you don't see it in the name :)
I propose to take the non-compatibility-breaking remarks from this issue then close it.