Protocols/WebAPI/Reference/Methods/Preference

From NINA Wiki
Jump to navigation Jump to search
WebAPI Protocol
Basic
Introduction
Clients
Whimsicals
Host Interaction
Flow
Authentication
• Client
• WebApp
Other Services
•
Foodgroups

This page is about WebAPI preference methods, in a series for the WebAPI reference manual.

setPreference

Set preferences

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

Input Parameters

Type Field Description
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 startSession call for authentication - k is not required
String a Use an NINA Authentication Token for authentication, from the getToken call
Integer ts Epoch timestamp - clientLogin required parameter
String sig_sha256 Signature - clientLogin required parameter.
Boolean Preferences [Required] The preference to set, the field name isn't Preferences, instead it is a value from the enumeration

Common Status Codes

Status Code Description
200 Success
401 Authorization required
460 Missing required parameter
462 Parameter error

Common Status Detail Codes

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 startSession

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

Sample JSON Output

{"response":{
    "statusCode":200,
    "statusText":"Ok",
    "requestId":"123",
    "data":{
    }
  }
}

Sample XML Output

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

getPreference

Get preferences

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

Input Parameters

Type Field Description
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 startSession call for authentication - k is not required
String a Use an NINA Authentication Token for authentication, from the getToken call
Integer ts Epoch timestamp - clientLogin required parameter
String sig_sha256 Signature - clientLogin required parameter.
Boolean Preferences Optional selector of which preferences to return, otherwise all are returned

Common Status Codes

Status Code Description
200 Success
401 Authorization required
460 Missing required parameter
462 Parameter error

Common Status Detail Codes

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 startSession

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

Sample JSON Output

{"response":{
    "statusCode":200,
    "statusText":"Ok",
    "requestId":"123",
    "data":{
    }
  }
}

Sample XML Output

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

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

Type Field Description
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 startSession call for authentication - k is not required
String a Use an NINA Authentication Token for authentication, from the 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
PdMode pdMode Set the overall permit/deny mode

Output Fields

Type Field Description
PDResults results Results array for all items

Common Status Codes

Status Code Description
200 Success
401 Authorization required
460 Missing required parameter
462 Parameter error

Common Status Detail Codes

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 startSession

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

Sample JSON Output

{"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"
        }
        ]
      }
    }
  }
}

Sample XML Output

<?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>

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

Type Field Description
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 startSession call for authentication - k is not required
String a Use an NINA Authentication Token for authentication, from the getToken call
Integer ts Epoch timestamp - clientLogin required parameter
String sig_sha256 Signature - clientLogin required parameter.

Output Fields

Type Field Description
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

Status Code Description
200 Success
401 Authorization required
460 Missing required parameter
462 Parameter error

Common Status Detail Codes

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 startSession

Sample JSON Output

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

Sample XML Output

<?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>
Retrieved from "https://wiki.nina.chat/index.php?title=Protocols/WebAPI/Reference/Methods/Preference&oldid=1974"