Table of Contents

Introduction

Web API v3.1 is a superset of version 3.0 of the web API. It adds two new properties to the begin_app_session return value and adds two new methods in support of component licensing.

begin_app_session

In addition to the v3.0 values, the following properties are added to a successful result:

{
    ...
    "components" : [
        {
            "name" : <string>,
            "license_model" : <session|token|consumable token|none>,
            "tokens_required" : <number>,
            "free_trial" : <boolean>,
            "free_trial_expiration" : <string>,
            "original_tokens_required" : <number>
        },
        ...
    ],
    "component_entitlements" : [
        {
            "components" : <string_array>,
            "tokens_entitled" : <number>,
            "tokens_in_use" : <number>,
            "tokens_in_use_by_session" : <number>,
            "sessions_entitled" : <number>,
            "sessions_in_use" : <number>,
            "in_use_by_session" : <boolean>
        },
        ...
    ],
    ...
}

check_out_components

Attempts to check out a set of components. Components are checked out to a specified session, which must have been started by a previous begin_app_session call, and must be currently active.

Endpoint

/api/v3.1/auth/check_out_components

Data

{
  "session_key" : <string>,
  "components" : <string|string_array>
}

Value on success

{
    "status" : 0,
    "time" : <string>,
    "components" : [
        {
            "name" : <string>,
            "license_model" : <session|token|consumable token|none>,
            "tokens_required" : <number>,
            "free_trial" : <boolean>,
            "free_trial_expiration" : <string>,
            "original_tokens_required" : <number>
        },
        ...
    ],
    "component_entitlements" : [
        {
            "components" : <string_array>,
            "tokens_entitled" : <number>,
            "tokens_in_use" : <number>,
            "tokens_in_use_by_session" : <number>,
            "sessions_entitled" : <number>,
            "sessions_in_use" : <number>,
            "in_use_by_session" : <boolean>
        },
        ...
    ]
}

Value on failure

{
  "success" : false,
  "time" : <string>,
  "error" : <string>
}

components_status

Gets the status of component checkouts for the current license and the current session. Allows clients to provide UI indicating whether components are checked out and whether enough entitlements are available to perform a checkout.

Endpoint

/api/v3.1/auth/components_status

Data

{
    "session_key" : <string>
}

Value on success

{
    "components" : [
        {
            "name" : <string>,
            "license_model" : <session|token|consumable token|none>,
            "tokens_required" : <number>,
            "free_trial" : <boolean>,
            "free_trial_expiration" : <string>,
            "original_tokens_required" : <number>
        },
        ...
    ],
    "component_entitlements" : [
        {
            "components" : <string_array>,
            "tokens_entitled" : <number>,
            "tokens_in_use" : <number>,
            "tokens_in_use_by_session" : <number>,
            "sessions_entitled" : <number>,
            "sessions_in_use" : <number>,
            "in_use_by_session" : <boolean>
        },
        ...
    ]
}

Value on failure

HTTP error code 400 Bad Request or similar.