Protocols/WebAPI/Reference/Methods/Session: Difference between revisions

From NINA Wiki
Jump to navigation Jump to search
No edit summary
No edit summary
Line 1: Line 1:
{{Protocols/WebAPI}}
{{Protocols/WebAPI}}


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


== startSession ==
== startSession ==

Revision as of 04:10, 26 March 2020

WebAPI Protocol
Basic
Introduction
Clients
Whimsicals
Host Interaction
Flow
Authentication
• Client
• WebApp
Other Services
•
Foodgroups

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

startSession

Start a Web AIM session. Since the AIM server needs to deliver asynchronous events, such as receiving IMs or buddy updates, a session is required for some of the APIs. However most of the APIs do not require a session, so there is no need to create one. After starting a session the AIM Session Id (aimsid) can be used instead of an NINA Authentication Token for most of the APIs. An NINA Authentication Token is required to start a session, which can be obtained with either getToken or clientLogin.

If end user interaction is required, a redirect URL is provide that needs to be shown to the end user in a DHTML control (such as an iframe). This redirection is to request the user's permission to access their Buddy List.

If an iframe is used, the calling code can detect when the end user has completed the interaction by looking for the #CONSENTDONE URL fragment, which the iframe will add to the parent document. The startSession call must be repeated at this point. If the end user does not give permission, the iframe will add the URL fragment #CONSENTCANCEL.

When using a token created with clientLogin the startSession call must be signed. An example of how to calculate sig_sha256 can be found at ClientLogin Example. URL signing requires the computers clock to be accurate or the use of hostTime returned by clientLogin, parameters must be in alphabetical order, and percent-encoding uses upper case characters.

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

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] the AIM Web Key from http://dev.nina.bz/aim - use the same key for all calls
String a [Required] Use an NINA Authentication Token for authentication, from the getToken call
Event Type events [Required] Comma separated list of events to subscribe to, fetchEvents will only return these events. The buddylist event triggers if the user will show up online to other folks or not.
Boolean encodeData Base 64 encode the data in imdata events
Capability assertCaps Comma separated list of capabilities to assert to other users and to receive from other users
Capability interestCaps Comma separated list of capabilities to ONLY receive from other users
Boolean anonymous Start an anonymous session
Boolean invisible Start an invisible session
String friendly For anonymous sessions, this is an optional friendly name to display
String language The language and locale to use 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 default to "en-us".
String clientName Client name - clientLogin parameter
Integer clientVersion Client version - clientLogin parameter
Integer ts Epoch timestamp - clientLogin required parameter
String sig_sha256 Signature - clientLogin required parameter.
Boolean mobile Whether this is a mobile session.
Integer sessionTimeout Time in seconds before terminating idle web session.
Presence State view How we should appear to other users, offline and mobile are not valid in this case

Output Fields

Type Field Description
String fetchBaseURL Base URL to do fetches with, see fetchEvents method below
String aimsid The aimsid to use in other calls
Presence myInfo Presence object about logged in user
String creatorDisplayName For anonymous sessions, this is the display name to use for the widget creator
String widgetTitle For anonymous sessions, this is the widget title to use
String greetingMsg For anonymous sessions, this is the greeting msg to use
String offlineMsg For anonymous sessions, this is the offline msg to use
String cssURI For anonymous sessions, this is the css uri path

Common Status Codes

Status Code Description
200 Success
401 Authorization required
408 Timeout of the backend servers
450 Consent required, use the redirectURL and append a k=KEY to it
460 Missing required parameter
462 Parameter error
607 Rate limit signing on, wait a few minutes before trying again

= Common Status Detail Codes

Status Detail Code Description
1004 Referer used to create token doesn't match referer of call

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

Sample JSON Output

{"response":{
    "statusCode":200,
    "statusText":"Ok",
    "requestId":"123",
    "data":{
      "fetchBaseURL":"http://10.10.10.10/aim/fetchEvents?seq=10",
      "aimsid":"opaquedata",
      "myInfo":{
        "aimId":"chattingchuck",
        "displayId":"ChattingChuck",
        "friendly":"Chuck my Buddy",
        "state":"away",
        "onlineTime":100,
        "awayTime":10,
        "statusTime":100,
        "awayMsg":"I'm busy right now chatting.",
        "profileMsg":"My name is Chuck, and I live on AIM.",
        "statusMsg":"Look at me!",
        "buddyIcon":"",
        "presenceIcon":"http://o.aolcdn.com/aim/img/away.gif",
        "capabilities":[
        "200A0000A28911D3A52D001083341CFA"
        ],
        "location":{
          "desc":"AOL Office",
          "street":"SULLY RD",
          "city":"STERLING",
          "country":"US",
          "state":"VA",
          "postcode":"20166",
          "accuracy":"100",
          "lat":"38.986750",
          "lon":"-77.430500",
          "accu_string":"Block1"
        },
        "ipCountry":"",
        "smsSegment":{
          "single":,
          "initial":,
          "trailing":
        },
        "userType":"aim"
      },
      "creatorDisplayName":"",
      "widgetTitle":"",
      "greetingMsg":"",
      "offlineMsg":"",
      "cssURI":""
    }
  }
}

Sample XML Output

<?xml version="1.0" encoding="UTF-8"?>
<response>
  <statusCode>200</statusCode>
  <statusText>Ok</statusText>
  <requestId>123</requestId>
  <data>
    <fetchBaseURL>http://10.10.10.10/aim/fetchEvents?seq=10</fetchBaseURL>
    <aimsid>opaquedata</aimsid>
    <myInfo>
      <aimId>chattingchuck</aimId>
      <displayId>ChattingChuck</displayId>
      <friendly>Chuck my Buddy</friendly>
      <state>away</state>
      <onlineTime>100</onlineTime>
      <awayTime>10</awayTime>
      <statusTime>100</statusTime>
      <awayMsg>I'm busy right now chatting.</awayMsg>
      <profileMsg>My name is Chuck, and I live on AIM.</profileMsg>
      <statusMsg>Look at me!</statusMsg>
      <buddyIcon></buddyIcon>
      <presenceIcon>http://o.aolcdn.com/aim/img/away.gif</presenceIcon>
      <capabilities>
      <capability>200A0000A28911D3A52D001083341CFA</capability>
      </capabilities>
      <location>
        <desc>AOL Office</desc>
        <street>SULLY RD</street>
        <city>STERLING</city>
        <country>US</country>
        <state>VA</state>
        <postcode>20166</postcode>
        <accuracy>100</accuracy>
        <lat>38.986750</lat>
        <lon>-77.430500</lon>
        <accu_string>Block1</accu_string>
      </location>
      <ipCountry></ipCountry>
      <smsSegment>
        <single></single>
        <initial></initial>
        <trailing></trailing>
      </smsSegment>
      <userType>aim</userType>
    </myInfo>
    <creatorDisplayName></creatorDisplayName>
    <widgetTitle></widgetTitle>
    <greetingMsg></greetingMsg>
    <offlineMsg></offlineMsg>
    <cssURI></cssURI>
  </data>
</response>

fetchEvents

Fetch outstanding events for an aimsid, waiting up to timeout milliseconds before returning. This URL is never formed on its own - instead, the URL is created by taking the fetchBaseURL returned by startSession or the last fetchEvents call, appending the required format parameter, and then optionally appending a requestId or callback parameters.

Appending the aimsid is not necessary; the API automatically adds it to the fetchBaseURL as the first parameter. The client should wait at least timeToNextFetch milliseconds between calls and make sure to use the new fetchBaseURL returned for the next call. Using an old fetchBaseURL will cause previous events to be repeated. A session will be timed out if there isn't an active fetchEvents for more then 30 seconds.

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
Integer timeout [Default 1 hour] Timeout in milliseconds that the server will wait before returning. Minimum 500ms, maximum 1 hour. On timeout the server will still respond, there will be no events however. For a web application this must be set.
Boolean peek If true, then this fetch will not update the most recent seqNum returned

Output Fields

Type Field Description
Integer timeToNextFetch Milliseconds to wait before doing the next event fetch
String fetchBaseURL Base URL to do next fetch with
Array of Event events Events that occured between the last fetch and now, can be empty on timeout

Common Status Codes

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

Sample JSON Output

{"response":{
    "statusCode":200,
    "statusText":"Ok",
    "requestId":"123",
    "data":{
      "timeToNextFetch":500,
      "fetchBaseURL":"http://10.10.10.10/aim/fetchEvents?seq=11",
      "events":[{
        "type":"sessionEnded",
        "eventData":"",
        "seqNum":
      }]
    }
  }
}

Sample XML Output

<?xml version="1.0" encoding="UTF-8"?>
<response>
  <statusCode>200</statusCode>
  <statusText>Ok</statusText>
  <requestId>123</requestId>
  <data>
    <timeToNextFetch>500</timeToNextFetch>
    <fetchBaseURL>http://10.10.10.10/aim/fetchEvents?seq=11</fetchBaseURL>
    <events>
    <event>
      <type>sessionEnded</type>
      <eventData></eventData>
      <seqNum></seqNum>
    </event>
    </events>
  </data>
</response>

deleteEvents

To delete multiple events

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

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
Integer eventNumber [Required] event numbers to delete. Multiple allowed.

Output Fields

Type Field Description
Array of EventStatus results Events response status

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/deleteEvents?f=json&aimsid=AIMSID&eventNumber=1&eventNumber=2

Sample JSON Output

{"response":{
    "statusCode":200,
    "statusText":"Ok",
    "requestId":"123",
    "data":{
      "results":[
      {
        "event":7,
        "code":0
      }
      ]
    }
  }
}

Sample XML Output

<?xml version="1.0" encoding="UTF-8"?>
<response>
  <statusCode>200</statusCode>
  <statusText>Ok</statusText>
  <requestId>123</requestId>
  <data>
    <results>
    <eventStatus>
      <event>7</event>
      <code>0</code>
    </eventStatus>
    </results>
  </data>
</response>

endSession

To be used when the user logs out or navigates away from the application, endSession ends an Web AIM session and set this session offline. A sessionEnded event will be generated after the last event is retrieved, so the client knows when to stop fetching events. If there isn't a active fetchEvents for more then 30 seconds, the backend will auto end the session.

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

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

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/endSession?f=json&k=MYKEY&c=callback&aimsid=AIMSID

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>

startOSCARSession

Start a OSCAR AIM session. This API requires that the token came from a previous [[Protocols/WebAPI/Auth/Client|clientLogin] call and that the URL is signed. For a complete example on using startOSCARSession see the OSCAR Protocol Signon Example. URL signing requires the computers clock to be accurate or the use of hostTime returned by clientLogin, parameters must be in alphabetical order, and percent-encoding uses upper case characters.

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

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] the AIM Web Key from http://dev.nina.bz/aim - use the same key for all calls
String a [Required] Use an NINA Authentication Token for authentication, from the getToken call
Boolean useTLS Request the connection to BOSS use TLS
String clientName Client name - clientLogin parameter
Integer clientVersion Client version - clientLogin parameter
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".
Integer ts [Required] Epoch timestamp - clientLogin required parameter
String sig_sha256 [Required] Signature - clientLogin required parameter.

Output Fields

Type Field Description
String host Host to connect to
String port Port to connect to
String cookie Binary cookie to present to BOSS
String tlsCertName If TLS is being used then this is the cert name to verify for the boss connection

Common Status Codes

Status Code Description
200 Success
401 Authorization required
408 Timeout of the backend servers
460 Missing required parameter
462 Parameter error
607 Rate limit signing on, wait a few minutes before trying again

Common Status Detail Codes

Status Detail Code Description
1004 Referer used to create token doesn't match referer of call

Sample JSON Output

{"response":{
    "statusCode":200,
    "statusText":"Ok",
    "requestId":"123",
    "data":{
      "host":"10.1.2.3",
      "port":"5190",
      "cookie":"base64ed data",
      "tlsCertName":"bos.oscar.nina.bz"
    }
  }
}

Sample XML Output

<?xml version="1.0" encoding="UTF-8"?>
<response>
  <statusCode>200</statusCode>
  <statusText>Ok</statusText>
  <requestId>123</requestId>
  <data>
    <host>10.1.2.3</host>
    <port>5190</port>
    <cookie>base64ed data</cookie>
    <tlsCertName>bos.oscar.nina.bz</tlsCertName>
  </data>
</response>
Retrieved from "https://wiki.nina.chat/index.php?title=Protocols/WebAPI/Reference/Methods/Session&oldid=1961"