Protocols/WebAPI/Reference

From NINA Wiki
Revision as of 01:55, 26 March 2020 by AD (talk | contribs) (Typical Anonymous Application Flow)
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to navigation Jump to search
WebAPI Protocol
Basic
Introduction
Clients
Whimsicals
Host Interaction
Flow
Authentication
Client
WebApp
Other Services
Foodgroups

The Web AIM API lets developers incorporate core AIM functionality into any web page, including the ability to sign on, send and receive IMs, and obtain a user's Buddy List. By using the Web AIM API to build their applications, developers can take advantage of AIM's power and large user base, while having the freedom to extend AIM's functionality in innovative new ways. The APIs support both the building of real-time, interactive widgets and one-time queries. Developers can use as much or as little of the platform as they like.

You will need a key to use the Web AIM APIs, which can be obtained from Web AIM Key Registration. If you are interested in using or modifying already-built widgets, visit AIM Whimsicals.

Typical Authenticated Application Flow

The application should not ask for the loginId and password directly. Instead, the application must show pages, usually in an IFRAME, generated by AOL to collect the authentication information. Usually an application will have a button that starts the authentication process, but it can also do parts of it on page load. What follows is the typical flow of an application that needs user authentication.

  • getToken - A token is required for many of the Web AIM APIs - the first call to getToken will almost always return an error and a redirectURL
  • Show the redirectURL to the user, usually using an IFRAME, and watch for the URL fragment to contain #AUTHDONE
  • getToken - The second call to getToken will return a success with a valid token
  • When using one of the APIs that supports the a= parameter, stop here, and use the token.a value
  • Some APIs require a session; use startSession to create a session and retrieve an aimsId
  • startSession - The first call to startSession MAY return a 450 error with redirectURL if the user is required to grant the page consent to access the user's data - Sessions are only needed when real time presence updates or interactive IMs are required
  • If consent was required, show the redirectURL to the user, usually in an IFRAME, and watch for the URL fragment to contain #CONSENTDONE
  • startSession - If required, call startSession again
  • Now any of the APIs that support the aimsId= parameter can be used
  • Sessions require periodic calls of the fetchEvents URL for outstanding items
  • endSession - Mark the user offline and clean up server state

Typical Anonymous Application Flow

When building a web AIM API application like WIMZI, that needs to establish an anonymous session, the following application flow should be used. An anonymous session can only interact with the user that created the key.

  • startSession - Call startSession with the annoymous= parameter and a WIMZI key
  • Use the returned widgetTitle returned from startSession in the UI
  • The creatorDisplayName will automatically be returned in the first BuddyList event as the only buddy
  • Sessions require periodic calls of the fetchEvents URL for outstanding items
  • Use the returned creatorDisplayName to address IMs
  • setState - the friendly= option can be used to set a friendly name for the anonymous visitor
  • endSession - Mark the anonymous user offline and clean up server state

The sections below contain a complete reference to the enumerations, types, and methods of Web AIM API.

Enumerations Types Methods