Protocols/WebAPI/Reference/Methods/Expressions

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

getExpression

Returns the expression information - the personalized icons, sounds, and background images - for an AIM user. This routine supports two extra format parameters, both of which require the type= parameter to be set:

  • native - Return the binary data directly. For example with buddy icons can be used to embedded the image using a img tag. The type parameter is required.
  • redirect - Similiar to native, except use a redirect to fetch the binary data. This will eventually allow the browser to cache better. The type parameter is required.

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

Input Parameters

Type Field Description
Format f [Required] The format of the data returned
String c JSONP callback
String r Request id
String t [Required] Target aimId
Expression Type type The type of expression to return, if missing all expressions are returned. Required for the native and redirect format
String defaultId If the user doesn't have an expression, use this one instead
String personality personality name
Boolean noCustom [Default 0] - if true a custom item isn't returned, instead the defaultId is returned if available

Output Fields

Type Field Description
Array of Expression expressions In JSON or Simple XML mode description of the expressions

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":{
      "expressions":[
      {
        "type":"buddyIcon",
        "id":"050201020304",
        "url":"http://api.oscar.aol.com/get"
      }
      ]
    }
  }
}

Sample XML Output

<?xml version="1.0" encoding="UTF-8"?>
<response>
  <statusCode>200</statusCode>
  <statusText>Ok</statusText>
  <requestId>123</requestId>
  <data>
    <expressions>
    <expression>
      <type>buddyIcon</type>
      <id>050201020304</id>
      <url>http://api.oscar.nina.bz/get</url>
    </expression>
    </expressions>
  </data>
</response>

getPersonalities

Returns the personalities information - a container for the personalized icons, sounds, and background images - for an AIM user.

URL: GET http://api.oscar.nina.bz/expressions/getPersonalities

Input Parameters

Type Field Description
Format f [Required] The format of the data returned
String c JSONP callback
String r Request id
String t [Required] Target aimId
Boolean withExpressions [Default 0] - if true all the expressions are returned for each personality

Output Fields

Type Field Description
Array of Personality personalities In JSON or Simple XML mode description of the personalities

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":{
      "personalities":[
      {
        "name":"myPersonality",
        "expressions":[
        {
          "type":"buddyIcon",
          "id":"050201020304",
          "url":"http://api.oscar.aol.com/get"
        }
        ]
      }
      ]
    }
  }
}

Sample XML Output

<?xml version="1.0" encoding="UTF-8"?>
<response>
  <statusCode>200</statusCode>
  <statusText>Ok</statusText>
  <requestId>123</requestId>
  <data>
    <personalities>
    <personality>
      <name>myPersonality</name>
      <expressions>
      <expression>
        <type>buddyIcon</type>
        <id>050201020304</id>
        <url>http://api.oscar.aol.com/get</url>
      </expression>
      </expressions>
    </personality>
    </personalities>
  </data>
</response>

getAsset

Get the binary asset, you really probably don't want to use this call since this is ID based and not user based

URL: GET http://api.oscar.nina.bz/expressions/getAsset

Input Parameters

Type Field Description
String c JSONP callback
String r Request id
String f [Required] native
String t Target aimId
Expression Type type [Required] The type of expression to return
String id [Required] The bart id
String defaultId If expression doesn't exist, use this one instead

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>

setExpression

Set the expression information - the personalized icons, sounds, and background images - for an AIM user.

URL: GET http://api.oscar.nina.bz/expressions/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.
Expression Type type [Required] The type of expression to set
String id [Required] The id of expression to set
String typeAndId [Required] The type and ID in the form of type:id. Multiple may be present. Ex: typeAndId=buddyIcon:0050201020304
String personality The name of the specific personality set

Common Status Codes

Status Code Description
200 Success
401 Authorization required
460 Missing required parameter
462 Parameter error, such as bad type or id

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/expressions/set?f=json&k=MYKEY&c=callback&aimsid=AIMSID&type=buddyIcon&id=00050201020304

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>

uploadExpression

Upload a custom expression

URL: POST http://api.oscar.nina.bz/expressions/upload

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.
Expression Type type [Required] The type of expression being uploaded

Output Fields

Type Field Description
String id The id of the expression uploaded, can be used with setExpression after stripping the leading 4 hex digits.

Common Status Codes

Status Code Description
200 Success
401 Authorization required
460 Missing required parameter
462 Parameter error, such as bad type or id

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

Sample XML Output

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