The user preferences API is not implemented in osmapi and is not covered by #156, which is about user/details (and, per its comments, the messaging API and user blocks).
Preferences are arbitrary key/value pairs stored per user, intended for editors and tools to persist their own settings server-side.
Endpoints
From config/routes.rb:
resources :user_preferences, :except => [:new, :create, :edit], :param => :preference_key, :path => "user/preferences" do
collection do
put "" => "user_preferences#update_all", :as => ""
end
end
which gives:
| Method |
Path |
Purpose |
GET |
/api/0.6/user/preferences |
all preferences of the authenticated user |
GET |
/api/0.6/user/preferences/:key |
a single value (plain text response) |
PUT |
/api/0.6/user/preferences/:key |
set a single value (plain text request body) |
PUT |
/api/0.6/user/preferences |
replace all preferences with the posted document |
DELETE |
/api/0.6/user/preferences/:key |
delete a single preference |
The list response is a flat map:
<osm>
<preferences>
<preference k="somekey" v="somevalue"/>
</preferences>
</osm>
Things to decide
- The single-key endpoints are not XML.
GET .../preferences/:key returns the bare value as text/plain, and PUT .../preferences/:key takes the bare value as the request body. That is the first place in osmapi where a response is not parsed as XML and a request body is not built by xmlbuilder._xml_build, so http.OsmApiSession and the mixin need to handle a plain-text payload. Worth checking _put's return_value handling here.
PUT /user/preferences replaces everything, it does not merge — deleting any key not present in the document. The docstring must be explicit about that, it is an easy way for a caller to wipe another tool's settings.
- All of these require authentication (
before_action :authorize), so they are auth_api tests.
Suggested naming, following the existing convention:
api.user_preferences_get() # -> {"key": "value", ...}
api.user_preference_get(key) # -> "value"
api.user_preference_update(key, value)
api.user_preferences_update_all(prefs)
api.user_preference_delete(key)
The user preferences API is not implemented in osmapi and is not covered by #156, which is about
user/details(and, per its comments, the messaging API and user blocks).Preferences are arbitrary key/value pairs stored per user, intended for editors and tools to persist their own settings server-side.
Endpoints
From
config/routes.rb:which gives:
GET/api/0.6/user/preferencesGET/api/0.6/user/preferences/:keyPUT/api/0.6/user/preferences/:keyPUT/api/0.6/user/preferencesDELETE/api/0.6/user/preferences/:keyThe list response is a flat map:
Things to decide
GET .../preferences/:keyreturns the bare value astext/plain, andPUT .../preferences/:keytakes the bare value as the request body. That is the first place in osmapi where a response is not parsed as XML and a request body is not built byxmlbuilder._xml_build, sohttp.OsmApiSessionand the mixin need to handle a plain-text payload. Worth checking_put'sreturn_valuehandling here.PUT /user/preferencesreplaces everything, it does not merge — deleting any key not present in the document. The docstring must be explicit about that, it is an easy way for a caller to wipe another tool's settings.before_action :authorize), so they areauth_apitests.Suggested naming, following the existing convention: