Capture Tool APIs

From wiki.gpii
Jump to: navigation, search

Introduction

The capture tool wireframe from the UX team can be found here.

At the time of writing on Mar 29, 2018, this page only covers APIs that allow Capture Tool to communicate with GPII Cloud. It does not yet cover the technical design of Capture Tool itself.

Technical Design between Capture Tool and GPII Cloud

General Assumptions

  • The communication between Capture Tool and GPII Cloud always starts by Capture Tool reading in a key.
  • Capture Tool, a standalone application, is only installed on GPII enabled computers and communicates with GPII Cloud through the GPII local flow manager.
  • The difference between "preferences" and "settings"

1. Preferences are saved in preferences safes at GPII Cloud. They are keyed by solution registry entries. An example:

{
    "http://registry.gpii.net/common/matchMakerType": "ruleBased",
    "http://registry.gpii.net/common/fontSize": 24,
    "http://registry.gpii.net/common/foregroundColor": "white",
    "http://registry.gpii.net/common/backgroundColor": "black",
    "http://registry.gpii.net/common/fontFaceFontName": [
        "Comic Sans"
    ]
}

2. Settings are device or application specific configurations applied to user computers. An example:

{
    "org.gnome.desktop.a11y.magnifier": {
        "focus-tracking": "none",
        "caret-tracking": "proportional",
        "mouse-tracking": "proportional",
        "mag-factor": 2,
        "screen-position": "right-half",
        "show-cross-hairs": true
    }
}

Workflow

Capture Tool Workflow.png

APIs

Capture Tool Web Socket API (ws://localhost:8081/captureTool)

  • Description: In charge of the communication between Capture Tool and GPII Local Flow Manager
  • Module it resides: Local Flow Manager
  • Involved-in workflow steps: 1, 6, 7.1, 10.1, 7.2, 10.2, 7.3, 12.3, 13.3, 16.3

Get a Access Token via Resource Owner GPII Key Grant (POST /access_token) [GPII Cloud already supports]

  • Description: Return an access token that authorizes a GPII app installation to access information of a key. These information include: find out if a key is empty or has a default preferences set (GET to /gpiiKey); create new preferences sets (POST to /settings). Note that GPII Cloud already supports this endpoint.
  • Parameters: A key & a client credential
  • Module it resides: Cloud Based Flow Manager
  • Involved-in workflow steps: 2, 3

Get Key Status (GET /gpiiKey/:gpiiKey)

  • Description: Respond with whether a key is empty or has a default preferences set.
  • Parameters: Access token from Resource Owner GPII Key Grant & a GPII key
  • Module it resides: Cloud Based Flow Manager
  • Involved-in workflow steps: 4, 5

Create a Preferences Set (POST /:gpiiKey/settings)

  • Description: Create a new preferences set. If a prefs set name is given, the prefs set will be saved as a non-default preferences set. If a name is not given, the prefs set will be saved as the default preferences set.
  • Parameters: Access token from Resource Owner GPII Key Grant & a GPII key & Preferences & Preferences set name (optional)
  • Module it resides: Cloud Based Flow Manager
  • Involved-in workflow steps: 8.1, 9.1, 8.2, 9.2

Get a Access Token via Resource Owner Client Credential Grant (POST /access_token)

  • Description: Return an access token that authorizes a GPII app installation to retrieve and update the preferences set of a key (GET & POST to /settings).
  • Parameters: A cloud safe login and password & a client credential & a GPII key
  • Module it resides: Cloud Based Flow Manager
  • Involved-in workflow steps: 8.3, 9.3

Get the Preferences of a Key (GET /:gpiiKey/settings/:device)

  • Description: Return the preferences of a key. These preferences are specific to the device environment.
  • Parameters: Access token from Resource Owner Client Credential Grant & a GPII key & device info
  • Module it resides: Cloud Based Flow Manager
  • Involved-in workflow steps: 10.3, 11.3

Update Preferences Set (PUT /:gpiiKey/settings)

  • Description: Update a preferences set with user merged preferences. Before the update occurs on the cloud, the user merged preferences will be merged with the existing preferences so that the preferences that are not user device specific would be untouched.
  • Parameters: Access token from Resource Owner Client Credential Grant & a GPII key & Preferences
  • Module it resides: Cloud Based Flow Manager
  • Involved-in workflow steps: 14.3, 15.3

Comparison of Endpoints between Universal Master and Proposed

What's in the universal master Proposed
Retrieve Settings GET /:gpiiKey/settings/:device GET /:gpiiKey/settings/:device
Description Retrieve device specific settings. Not in use. Retrieve device specific settings. Only returns settings that belong to the prefsSetId associated with the incoming key.
Parameters key, device key, device, client credential, cloud safe login & password
Return Payload
{
    "org.gnome.desktop.a11y.magnifier": {
        "focus-tracking": "none",
        "caret-tracking": "proportional",
        "mouse-tracking": "proportional",
        "mag-factor": 2,
        "screen-position": "right-half",
        "show-cross-hairs": true
    }
}
Same as the response of the current GET /:gpiiKey/settings/:device in the master
GET /:gpiiKey/untrusted-settings/:device See above
Description Retrieve device specific settings. Used by Local Flow Manager for the key-in process. The workflow between LFM and CBFM for the key-in process can be found here.
Parameters key, device, client credential
Return Payload Includes: lifecycleInstructions, gpiiKey, solutionsRegistryEntries, matchMakerOutput, activeContextName (activePrefsSetId in new terminology), activeConfiguration (activeSettings in new terminology).

The detail of the return payload can be found here.

Update Preferences PUT /:gpiiKey/untrusted-settings PUT /:gpiiKey/settings
Description Update user preferences. Not in use. Update user preferences by receiving device specific settings. At GPII Cloud, 1. convert device specific settings to preferences; 2. merge converted device specific preferences with other preferences (How? The merge should not merge back user deleted preferences. This brings up the question: can users use Capture Tool to remove settings, or they can only select to either change or keep the existing settings).
Parameters key, client credential, preferences key, client credential, settings, cloud safe login & password
Input Payload Entire preferences. Example:
{
    "flat": {
        "name": "Carla",
        "contexts": {
            "gpii-default": {
                "name": "Default preferences",
                "preferences": {
                    "http://registry.gpii.net/applications/com.texthelp.readWriteGold": {
                        "ApplicationSettings.AppBar.Width.$t": 788,
                        "ApplicationSettings.AppBar.ShowText.$t": true,
                        "ApplicationSettings.AppBar.optToolbarShowText.$t": true,
                        "ApplicationSettings.AppBar.LargeIcons.$t": true,
                        "ApplicationSettings.AppBar.optToolbarLargeIcons.$t": true,
                        "ApplicationSettings.Speech.optSAPI5Speed.$t": 50,
                        "ApplicationSettings.Speech.optAutoUseScreenReading.$t": false
                    },
                    "http://registry.gpii.net/applications/org.gnome.desktop.a11y.magnifier": {
                        "show-cross-hairs": true,
                        "lens-mode": false,
                        "mag-factor": 2,
                        "mouse-tracking": "proportional",
                        "screen-position": "right-half",
                        "scroll-at-edges": true
                    }
                }
            }
        }
    }
}
Device specific settings. Example:
{
    "org.gnome.desktop.a11y.magnifier": {
        "focus-tracking": "none",
        "caret-tracking": "proportional",
        "mouse-tracking": "proportional",
        "mag-factor": 2,
        "screen-position": "right-half",
        "show-cross-hairs": true
    }
}
Return Payload success or fail success or fail
Create Preferences Not supported POST /:gpiiKey/settings
Description Create user preferences by receiving device specific settings. At GPII Cloud, 1. convert device specific settings to preferences;
Parameters key, client credential, settings
Input Payload Device specific settings. Example:
{
    "org.gnome.desktop.a11y.magnifier": {
        "focus-tracking": "none",
        "caret-tracking": "proportional",
        "mouse-tracking": "proportional",
        "mag-factor": 2,
        "screen-position": "right-half",
        "show-cross-hairs": true
    }
}
Return Payload success or fail

Questions

1. The terminology used by Capture Tool wireframe should be consistent with what's described in the document "Keys, Preference Sets, and Preference Safes": "keyToken" -> "key", "user id" -> "cloud safe name or email"

2. Synchronize the use of /untrusted-settings and /settings. GPII right now supports PUT methods to /untrusted-settings to update preferences, in which usage, the preferences sent from GPII clients are preferences that don't require any transformation at the cloud. This collides with the functionality that is supposed to be provided by /settings.

3. Have a better name for "untrusted settings".

4. How are the existing GET /:gpiiKey/untrusted-settings/:device and GET /:gpiiKey/settings/:device the same or different from the proposed GET /:gpiiKey/settings/:device ("Get the Preferences of a Key" above)? The existing untrusted-settings endpoint does not require a preferences safe login and password (only a key), whereas the new settings endpoint does require a preferences safe login and password. And the existing settings endpoint that has no OAuth 2 protections.

5. How is the existing PUT /:gpiiKey/untrusted-settings the same or different from the proposed PUT /:gpiiKey/settings ("Update Preferences Set" above)? The existing untrusted-settings endpoint does not require a preferences safe login and password (only a key), whereas the new settings endpoint does require a preferences safe login and password.

References