Protocols/WebAPI/Reference/Methods/Misc

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 misc methods, in a series for the WebAPI reference manual.

getVanityInfo

Retrieve the vanity information for a user.

URL: GET http://api.oscar.nina.bz/aim/getVanityInfo

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
Integer imsSent Number of IMs the user has sent during the collection interval
Integer imsReceived Number of IMs the user has received during the collection interval
Integer awayMsgs Number of away messages set during the collection interval
Integer onlineTime Minutes online
Integer collectionInterval Minutes since the first time data was collected

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":{
      "imsSent":10,
      "imsReceived":20,
      "awayMsgs":30,
      "onlineTime":30,
      "collectionInterval":300
    }
  }
}

Sample XML Output

<?xml version="1.0" encoding="UTF-8"?>
<response>
  <statusCode>200</statusCode>
  <statusText>Ok</statusText>
  <requestId>123</requestId>
  <data>
    <imsSent>10</imsSent>
    <imsReceived>20</imsReceived>
    <awayMsgs>30</awayMsgs>
    <onlineTime>30</onlineTime>
    <collectionInterval>300</collectionInterval>
  </data>
</response>

getAIMFight

Get the AIM Fight score and rank for multiple aimIds

URL: GET http://api.oscar.nina.bz/aim/getAIMFight

Input Parameters

Type Field Description
Format f [Required] The format of the data returned
String c JSONP callback
String r Request id
String k [Required] either an AIM Web Key or AIM Presence Key from http://dev.nina.bz/aim
String t Target aimIds, multiple t parameters are allowed

Output Fields

Type Field Description
Array of AIMFightUser users AIM Fight User information

Common Status Codes

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

Sample JSON Output

{"response":{
    "statusCode":200,
    "statusText":"Ok",
    "requestId":"123",
    "data":{
      "users":[
      {
        "aimId":"chattingchuck",
        "score":10000000,
        "rank":1
      }
      ]
    }
  }
}

Sample XML Output

<?xml version="1.0" encoding="UTF-8"?>
<response>
  <statusCode>200</statusCode>
  <statusText>Ok</statusText>
  <requestId>123</requestId>
  <data>
    <users>
    <user>
      <aimId>chattingchuck</aimId>
      <score>10000000</score>
      <rank>1</rank>
    </user>
    </users>
  </data>
</response>

addTempBuddy

Add a temporary buddy for presence updates

URL: GET http://api.oscar.nina.bz/aim/addTempBuddy

Input Parameters

Type Field Description
Format f [Required] The format of the data returned
String c JSONP callback
String r Request id
String aimsid [Required] Use an AIM Session Id from the startSession call for authentication
String t [Required] buddy name, multiple t= parameters are allowed

Common Status Codes

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

Example: http://api.oscar.nina.bz/aim/addTempBuddy?f=json&c=callback&aimsid=AIMSID&t=msft@relegence.com

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>

removeTempBuddy

Remove a temporary buddy for presence updates

URL: GET http://api.oscar.nina.bz/aim/removeTempBuddy

Input Parameters

Type Field Description
Format f [Required] The format of the data returned
String c JSONP callback
String r Request id
String aimsid [Required] Use an AIM Session Id from the startSession call for authentication
String t [Required] Buddy name, multiple t= parameters are allowed

Common Status Codes

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

Example: http://api.oscar.nina.bz/aim/removeTempBuddy?f=json&c=callback&aimsid=AIMSID&t=msft@relegence.com

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>

getHostBuddyInfo

Get host buddy info. Only valid format supported is html.

URL: GET http://api.oscar.nina.bz/aim/getHostBuddyInfo

Input Parameters

Type Field Description
String f [Required] Only f=html is supported
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 t Target to query buddy info for
String language the language and locale in "<lang>-<locale>" format. The lang is the 2 letter language code for I18N (default: en) and the locale is the 2 letter Locale code for I18N (default: us).

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

Sample XML Output

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

aimStartPage

This method will redirect the caller to the correct AIM Start Page for given language. If WIM is being used from a web page then calling this api directly is enough. If WIM is being used from a clientLogin session or from the OSCAR protocol then a wrapping Single Signon call must be used. See here for an example of using Single Sign On.

URL: GET http://api.oscar.aol.com/aim/getStartPage

Input Parameters

Type Field Description
Format f [Required] The format of the data returned
String c JSONP callback
String r Request id
String language the required language and locale of the error/status messages. This is always in "<lang>-<locale>" format. The lang is the 2 letter language code for I18N (default: en) and the locale is the 2 letter Locale code for I18N (default: us). If not passed in, the language will be extracted from HTTP header (Accept-Language) and if that is not available will default to "en-us".
String k [Required] the AIM Web Key from http://dev.aol.com/aim - use the same key for all calls

Common Status Codes

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

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>

aimExpressionsPage

This method will redirect the caller to the correct AIM Expressions page for given language. If WIM is being used from a web page then calling this api directly is enough. If WIM is being used from a clientLogin session or from the OSCAR protocol then a wrapping Single Signon call must be used. See here for an example of using Single Signon.

URL: GET http://api.oscar.aol.com/aim/getExpressionsPage

Input Parameters

Type Field Description
Format f [Required] The format of the data returned
String c JSONP callback
String r Request id
String language the required language and locale of the error/status messages. This is always in "<lang>-<locale>" format. The lang is the 2 letter language code for I18N (default: en) and the locale is the 2 letter Locale code for I18N (default: us). If not passed in, the language will be extracted from HTTP header (Accept-Language) and if that is not available will default to "en-us".
String k [Required] the AIM Web Key from http://dev.aol.com/aim - use the same key for all calls

Common Status Codes

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

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