AD: Created page with "{{Protocols/WebAPI}} This page is about WebAPI preference methods, in a series for the WebAPI Protocols/WebAPI/Reference|reference ma..."

2020-03-26T08:28:55Z

Created page with "{{Protocols/WebAPI}} This page is about WebAPI preference methods, in a series for the WebAPI Protocols/WebAPI/Reference|reference ma..."

New page

{{Protocols/WebAPI}}

This page is about WebAPI preference [[Protocols/WebAPI/Reference/Methods|methods]], in a series for the WebAPI [[Protocols/WebAPI/Reference|reference manual]].

== setPreference ==

Set preferences

URL: GET http://api.oscar.nina.bz/preference/set

=== Input Parameters ===

{| class="wikitable"
! Type
! Field
! Description
|-
| [[Protocols/WebAPI/Reference/Enumeration#Format|Format]]
| f
| '' [Required]'' The format of the data returned
|-
| String
| c
| JSONP callback
|-
| String
| r
| Request id
|-
| String
| k
| the AIM Web Key from http://dev.nina.bz/aim - use the same key for all calls
|-
| String
| aimsid
| Use an AIM Session Id from the [[Protocols/WebAPI/Reference/Methods/Session#startSession|startSession]] call for authentication - k is not required
|-
| String
| a
| Use an NINA Authentication Token for authentication, from the [[Protocols/WebAPI/Auth/WebApp/getToken|getToken]] call
|-
| Integer
| ts
| Epoch timestamp - clientLogin required parameter
|-
| String
| sig_sha256
| Signature - clientLogin required parameter.
|-
| Boolean
| [[Protocols/WebAPI/Reference/Enumeration#Preferences|Preferences]]
| '' [Required]'' The preference to set, the field name isn't Preferences, instead it is a value from the enumeration
|}

=== Common Status Codes ===

{| class="wikitable"
! Status Code
! Description
|-
| 200
| Success
|-
| 401
| Authorization required
|-
| 460
| Missing required parameter
|-
| 462
| Parameter error
|}

=== Common Status Detail Codes ===

{| class="wikitable"
! Status Detail Code
! Description
|-
| 1004
| Referer used to create token doesn't match referer of call
|-
| 1014
| Signature is bad, see the signature notes of [[Protocols/WebAPI/Reference/Methods/Session#startSession|startSession]]
|}

'''Example:''' http://api.oscar.nina.bz/preference/set?f=json&k=KEY&c=callback&a=AOLAUTHTOKEN&displayLogin=1&showBuddyFeed=0

=== Sample JSON Output ===

<pre>
{"response":{
"statusCode":200,
"statusText":"Ok",
"requestId":"123",
"data":{
}
}
}
</pre>

=== Sample XML Output ===

<pre>
<?xml version="1.0" encoding="UTF-8"?>
<response>
<statusCode>200</statusCode>
<statusText>Ok</statusText>
<requestId>123</requestId>
<data>
</data>
</response>
</pre>

== getPreference ==

Get preferences

URL: GET http://api.oscar.nina.bz/preference/get

=== Input Parameters ===

{| class="wikitable"
! Type
! Field
! Description
|-
| [[Protocols/WebAPI/Reference/Enumeration#Format|Format]]
| f
| '' [Required]'' The format of the data returned
|-
| String
| c
| JSONP callback
|-
| String
| r
| Request id
|-
| String
| k
| the AIM Web Key from http://dev.nina.bz/aim - use the same key for all calls
|-
| String
| aimsid
| Use an AIM Session Id from the [[Protocols/WebAPI/Reference/Methods/Session#startSession|startSession]] call for authentication - k is not required
|-
| String
| a
| Use an NINA Authentication Token for authentication, from the [[Protocols/WebAPI/Auth/WebApp/getToken|getToken]] call
|-
| Integer
| ts
| Epoch timestamp - clientLogin required parameter
|-
| String
| sig_sha256
| Signature - clientLogin required parameter.
|-
| Boolean
| [[Protocols/WebAPI/Reference/Enumeration#Preferences|Preferences]]
| Optional selector of which preferences to return, otherwise all are returned
|}

=== Common Status Codes ===

{| class="wikitable"
! Status Code
! Description
|-
| 200
| Success
|-
| 401
| Authorization required
|-
| 460
| Missing required parameter
|-
| 462
| Parameter error
|}

=== Common Status Detail Codes ===

{| class="wikitable"
! Status Detail Code
! Description
|-
| 1004
| Referer used to create token doesn't match referer of call
|-
| 1014
| Signature is bad, see the signature notes of [[Protocols/WebAPI/Reference/Methods/Session#startSession|startSession]]
|}

'''Example:''' http://api.oscar.nina.bz/preference/get?f=json&k=KEY&c=callback&a=AOLAUTHTOKEN

=== Sample JSON Output ===

<pre>
{"response":{
"statusCode":200,
"statusText":"Ok",
"requestId":"123",
"data":{
}
}
}
</pre>

=== Sample XML Output ===

<pre>
<?xml version="1.0" encoding="UTF-8"?>
<response>
<statusCode>200</statusCode>
<statusText>Ok</statusText>
<requestId>123</requestId>
<data>
</data>
</response>
</pre>

== setPermitDeny ==

Change the permit/deny settings. The backend system enforces the permit/deny settings, this API is used to update those settings.

URL: GET https://api.oscar.nina.bz/preference/setPermitDeny

=== Input Parameters ===

{| class="wikitable"
! Type
! Field
! Description
|-
| [[Protocols/WebAPI/Reference/Enumeration#Format|Format]]
| f
| '' [Required]'' The format of the data returned
|-
| String
| c
| JSONP callback
|-
| String
| r
| Request id
|-
| String
| k
| the AIM Web Key from http://dev.nina.bz/aim - use the same key for all calls
|-
| String
| aimsid
| Use an AIM Session Id from the [[Protocols/WebAPI/Reference/Methods/Session#startSession|startSession]] call for authentication - k is not required
|-
| String
| a
| Use an NINA Authentication Token for authentication, from the [[Protocols/WebAPI/Auth/WebApp/getToken|getToken]] call
|-
| Integer
| ts
| Epoch timestamp - clientLogin required parameter
|-
| String
| sig_sha256
| Signature - clientLogin required parameter.
|-
| String
| pdAllow
| Allow specified aimId
|-
| String
| pdBlock
| Block specified aimId
|-
| String
| pdIgnore
| Ignore IMs from specified aimId
|-
| String
| pdAllowRemove
| Remove specified aimId from allow list
|-
| String
| pdBlockRemove
| Remove specified aimId from block list
|-
| String
| pdIgnoreRemove
| Remove specified aimId from ignore list
|-
| [[Protocols/WebAPI/Reference/Enumeration#PdMode|PdMode]]
| pdMode
| Set the overall permit/deny mode
|}

=== Output Fields ===

{| class="wikitable"
! Type
! Field
! Description
|-
| [[Protocols/WebAPI/Reference/Types#PDResults|PDResults]]
| results
| Results array for all items
|}

=== Common Status Codes ===

{| class="wikitable"
! Status Code
! Description
|-
| 200
| Success
|-
| 401
| Authorization required
|-
| 460
| Missing required parameter
|-
| 462
| Parameter error
|}

=== Common Status Detail Codes ===

{| class="wikitable"
! Status Detail Code
! Description
|-
| 1004
| Referer used to create token doesn't match referer of call
|-
| 1014
| Signature is bad, see the signature notes of [[Protocols/WebAPI/Reference/Methods/Session#startSession|startSession]]
|}

'''Example:''' https://api.oscar.nina.bz/preference/setPermitDeny?k=MYKEY&f=xml&pdAllow=ChattingChuck&pdDeny=fred

=== Sample JSON Output ===

<pre>
{"response":{
"statusCode":200,
"statusText":"Ok",
"requestId":"123",
"data":{
"results":{
"pdModeResult":0-Success,
"allowResults":[
{
"aimid":"foo",
"statusCode":"0"
}
],
"blockResults":[
{
"aimid":"foo",
"statusCode":"0"
}
],
"IgnoreResults":[
{
"aimid":"foo",
"statusCode":"0"
}
],
"allowRemoveResults":[
{
"aimid":"foo",
"statusCode":"0"
}
],
"blockRemoveResults":[
{
"aimid":"foo",
"statusCode":"0"
}
],
"IgnoreRemoveResults":[
{
"aimid":"foo",
"statusCode":"0"
}
]
}
}
}
}
</pre>

=== Sample XML Output ===

<pre>
<?xml version="1.0" encoding="UTF-8"?>
<response>
<statusCode>200</statusCode>
<statusText>Ok</statusText>

<requestId>123</requestId>
<data>
<results>
<pdModeResult>0-Success</pdModeResult>
<allowResults>

<allowResult>
<aimid>foo</aimid>
<statusCode>0</statusCode>
</allowResult>
</allowResults>

<blockResults>
<blockResult>
<aimid>foo</aimid>
<statusCode>0</statusCode>
</blockResult>

</blockResults>
<IgnoreResults>
<IgnoreResult>
<aimid>foo</aimid>
<statusCode>0</statusCode>

</IgnoreResult>
</IgnoreResults>
<allowRemoveResults>
<allowRemoveResults>
<aimid>foo</aimid>

<statusCode>0</statusCode>
</allowRemoveResults>
</allowRemoveResults>
<blockRemoveResults>
<blockRemoveResults>

<aimid>foo</aimid>
<statusCode>0</statusCode>
</blockRemoveResults>
</blockRemoveResults>
<IgnoreRemoveResults>

<ignoreRemoveResult>
<aimid>foo</aimid>
<statusCode>0</statusCode>
</ignoreRemoveResult>
</IgnoreRemoveResults>

</results>
</data>
</response>
</pre>

== getPermitDeny ==

Get the current permit/deny settings. The backend system enforces the permit/deny settings so this API really is only useful for building UIs that allow the user to change the settings.

URL: GET https://api.oscar.nina.bz/preference/getPermitDeny

=== Input Parameters ===

{| class="wikitable"
! Type
! Field
! Description
|-
| [[Protocols/WebAPI/Reference/Enumeration#Format|Format]]
| f
| '' [Required]'' The format of the data returned
|-
| String
| c
| JSONP callback
|-
| String
| r
| Request id
|-
| String
| k
| the AIM Web Key from http://dev.nina.bz/aim - use the same key for all calls
|-
| String
| aimsid
| Use an AIM Session Id from the [[Protocols/WebAPI/Reference/Methods/Session#startSession|startSession]] call for authentication - k is not required
|-
| String
| a
| Use an NINA Authentication Token for authentication, from the [[Protocols/WebAPI/Auth/WebApp/getToken|getToken]] call
|-
| Integer
| ts
| Epoch timestamp - clientLogin required parameter
|-
| String
| sig_sha256
| Signature - clientLogin required parameter.
|}

=== Output Fields ===

{| class="wikitable"
! Type
! Field
! Description
|-
| [[Protocols/WebAPI/Reference/Enumeration#PdMode|PdMode]]
| pdMode
| Permit/Deny mode
|-
| ''Array of'' String
| allows
| aimIds allowed
|-
| ''Array of'' String
| blocks
| aimIds blocked
|-
| ''Array of'' String
| ignores
| aimIds ignored
|}

=== Common Status Codes ===

{| class="wikitable"
! Status Code
! Description
|-
| 200
| Success
|-
| 401
| Authorization required
|-
| 460
| Missing required parameter
|-
| 462
| Parameter error
|}

=== Common Status Detail Codes ===

{| class="wikitable"
! Status Detail Code
! Description
|-
| 1004
| Referer used to create token doesn't match referer of call
|-
| 1014
| Signature is bad, see the signature notes of [[Protocols/WebAPI/Reference/Methods/Session#startSession|startSession]]
|}

=== Sample JSON Output ===

<pre>
{"response":{
"statusCode":200,
"statusText":"Ok",
"requestId":"123",
"data":{
"pdMode":"permitOnList",
"allows":[
"ChattingChuck"
],
"blocks":[
"fred"
],
"ignores":[
"john"
]
}
}
}
</pre>

=== Sample XML Output ===

<pre>
<?xml version="1.0" encoding="UTF-8"?>
<response>
<statusCode>200</statusCode>
<statusText>Ok</statusText>
<requestId>123</requestId>
<data>
<pdMode>permitOnList</pdMode>
<allows>
<allow>ChattingChuck</allow>
</allows>
<blocks>
<block>fred</block>
</blocks>
<ignores>
<ignore>john</ignore>
</ignores>
</data>
</response>
</pre>

[[Category:Stub]]
[[Category:AOL]]
[[Category:AIM]]
[[Category:Protocols/WebAPI]]
[[Category:Protocols/WebAPI/Reference]]
[[Category:Work_In_Progress]]

Protocols/WebAPI/Reference/Methods/Preference - Revision history

AD: Created page with "{{Protocols/WebAPI}} This page is about WebAPI preference methods, in a series for the WebAPI Protocols/WebAPI/Reference|reference ma..."