Application API: Define features

Application API: Define features

Call UBX application APIs to add features to UBX applications.

POST /v1/application/{applicationID}/feature

Define features for a UBX application.

About this API

UBX features are associated with a specific UBX application. Event types are associated with a specific feature. In this way, features become containers for different combinations of events that can be associated with different endpoints.

The name and description that you assign as part of this API call are for internal use only. Neither appears in the UBX user interface.

The call response includes a system-defined feature ID that you use in other application API calls.

Before you begin

Create or select the application that you will associate with the feature. You must know the unique application ID that identifies the application.

Request

You must specify the account-level authentication key that IBM provided for your UBX account.

The base URL is the URL that IBM assigned to your account during the initial account provisioning process.

The applicationID is the value that UBX generated when you created the application with the call to POST v1/application.

The following example illustrates a request (using curl) to create a feature and associate it with a UBX application:

curl -v 
-X POST 
-H "Authorization: Bearer <application-level authentication key>" 
-H "Content-Type: application/json" 
-d ’{“name” : “<feature name>”,"description" : "<feature description>" },

https://<base URL>/v1/application/<applicationID>/feature

The following table describes the complete JSON payload for the call.

Request JSON
{
"name" : "<feature name>",
"description" : "<feature description>"
}
Property Use Data type Valid value Description
name Required string Any name Name of the feature. Internal use only.
description Required string Any description Enter a brief description. Internal use only.

Response

UBX public APIs return standard HTTP 1.1 response codes.

A successful call response includes a JSON payload that matches the payload of the request but also includes a new, system-generated property: "id" : "{external feature id}.

For example, the returned JSON includes the new external feature ID, as illustrated here.

Response JSON
{
"id" : <external feature id>
"name" : "<feature name>",
"description" : "<feature description>"
}

UBX uses the value of this new property to identify the feature that the API call creates. Record the value for "id" because you must specify it in other application API calls.

PUT /v1/application/{applicationID}/feature/{featureID}

Update a feature that is associated with a UBX application.

About this API

Call this API to make changes to the feature definition. For example, you can update the description of the feature as you make changes to the set of events that are associated with the feature.

Request

You must specify the account-level authentication key that IBM provided for your UBX account.

The applicationID is the value that UBX generated when you created the application with the call to POST v1/application.

The featureID is the system-generated value that was defined by calling POST v1/application/{applicationID}/feature.

The structure of the JSON payload for the PUT call is identical to the payload structure for the POST call. Update the values that you want to change. You cannot change the featureID.

The following example illustrates a request (using curl) to update a feature that is associated with a UBX application:

curl -v 
-X PUT 
-H "Authorization: Bearer <application-level authentication key>" 
-H "Content-Type: application/json" 
-d ’{"id" : <external feature id>",“name” : “<new feature name>”,
"description" : "<new feature description>" }
https://<base URL>/v1/application/<applicationID>/feature/<featureID>

Response

UBX public APIs return standard HTTP 1.1 response codes.

A successful call response includes a JSON payload that contains the updated values. The value
for "id" does not change.

GET /v1/application/{applicationid}/feature/{externalfeatureID}

Request information about a feature that is associated with a UBX application.

About this API

Call this API to get details for a specific feature that is associated with a UBX application. The feature provides the means to associate event types with the UBX applications and through the application to make the event types available to UBX endpoints that are based on the application.

Request

You must specify the account-level authentication key that IBM provided for your UBX account.

The application ID is the value that UBX generated when you created the application with the call to POST v1/application. The externalfeatureID is the value that you defined when you generated the feature by calling POST v1/application/<applicationID>/feature.

The base URL is the URL that IBM assigned to your account during the initial account provisioning process. Make the call with an empty request body.

The following example illustrates a request (using curl) to retrieve details for a feature that was created for the specified application:

curl -v 
-X GET 
-H "Authorization: Bearer <account-level authentication key>" 
-H "Content-Type: application/json" 
https://<base URL>/v1/application/<applicationID>/feature/<featureID>

Response

UBX public APIs return standard HTTP 1.1 response codes.

A successful response includes a JSON payload that describes the specified feature.

Response JSON
{
   "applicationID":<application ID>,
   "featureID":<feature ID>,
   "externalFeatureID":"<external feature ID>",
   "name":"<feature name>",
   "description":"<description>",
   "status":<feature status>
}
Property Use Data type Valid value Description
applicationID string application ID Identifies the application for which the feature is created. Cannot be changed.
featureID string feature ID Identifies the feature. Cannot be changed.
name string text Name of the feature.
description string text Description of the feature
status integer

active = 1

inactive = 0

Indicates if the feature is active or inactive.

DELETE /v1/application/{applicationid}/feature/{featureid}

Remove a feature from a UBX application.

About this API

Call this API to remove the feature that is specified by the featureID that you include in the request URL.

Request

You must specify the account-level authentication key that IBM provided for your UBX account as the authorization bearer.

The application ID is the value that UBX generated when you created the application with the call to POST v1/application.

The base URL is the URL that IBM assigned to your account during the initial account provisioning process. Make the call with an empty request body.

The following example illustrates a request (using curl) to remove the specified UBX application:

curl -v 
-X DELETE 
-H "Authorization: Bearer <account-level authentication key>" 
-H "Content-Type: application/json" 
https://<base URL>/v1/application/<applicationID>/feature/<feature ID>

Response

UBX public APIs return standard HTTP 1.1 response codes.

Join The Discussion

Your email address will not be published. Required fields are marked *