Orion/Server API/Preference API

Reading preferences

Obtaining a single preference value

Overview

Obtain the value of a single preference

HTTP Method

GET

Example Request

GET /prefs/{:user_id}/{:pref_node}?key={:pref_name}
Orion-Version: 1.0

  

Example Response

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 17

{"Name":"Enkidu"}

Detailed Explanation

Returns a JSON object with a single member, whose name is the key and whose value is the current preference value. Returns a 404 response if no such preference is defined.

Obtaining a preference node

Overview

Obtain an entire preference node

HTTP Method

GET

Example Request

GET /prefs/{:user_id}/{:pref_node}
Orion-Version: 1.0

  

Example Response

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 56

{
"Name":"Enkidu",
"Address":"Uruk",
"Occupation":"Naturalist"
}

Detailed Explanation

Returns a JSON object with a member for each key, whose value is the current preference value for that key. Returns an empty node ({}) if no such preference node is defined.

Modifying preferences

Change a single preference

Overview

Change the value of a single preference key

HTTP Method

PUT

Example Request

PUT /prefs/{:user_id}/{:pref_node}
Orion-Version: 1.0
Content-Length: 21
Content-Type: "application/x-www-form-urlencoded"

key=Name&value=Enkidu  

Example Response

HTTP/1.1 204

Detailed Explanation

If the request body is empty or does not define a key, a 400 ("Bad Request") response is returned. If the request body does not define a value, then the given preference key will be removed

Change an entire preference node

Overview

Sets an entire node of preference values.

HTTP Method

PUT

Example Request

PUT /prefs/{:user_id}/{:pref_node}
Orion-Version: 1.0
Content-Length: 44
Content-Type: application/json

{
"Name":"Enkidu",
"Address":"Uruk",
"Occupation":"Adventurer"
}  

Example Response

HTTP/1.1 204

Detailed Explanation

Any existing preference values not specified in the request body are removed.

Delete a single preference

Overview

Remove a single preference value

HTTP Method

DELETE

Example Request

DELETE /prefs/{:user_id}/{:pref_node}?key=Name

  

Example Response

HTTP/1.1 204 OK

Detailed Explanation

Deletion has no effect if no such preference exists.

Delete an entire preference node

Overview

Remove a preference node

HTTP Method

DELETE

Example Request

DELETE /prefs/{:user_id}/{:pref_node}

  

Example Response

HTTP/1.1 204 OK

Detailed Explanation

Deletion has no effect if no such preference exists.