HowTo: Defining an API object with a security scheme

Official Content
This documentation is valid for:

It is possible to define an API object with security scheme. To do so, follow the steps below:

  1. API object definition
  2. Defining the security scheme

1. API object definition

Consider the following two-level Transaction object configured as a Business Component:

Customer
{
    CustomerId*      (Autonumber property = Yes)
    CustomerName
    CustomerLastName
    CustomerPhone
    CustomerEmail
    CustomerLastAccountId
    Account
    {
       AccountId*
       AccountPassword
       AccountBalance
       AccountStatus    (Type:Boolean)
    }
}

The Transaction has the following rule defined:

Serial(AccountId,CustomerLastAccountId,1);

Suppose you want to see if a Customer has a certain active account and the Balance of that account. To do this, create a Procedure object called ShowCustomerInfo with the following sections:

Variables:

Account          (Type:Customer.Account)
AccountBalance   (Type:Attribute:AccountBalance)
AccountId        (Type:Attribute:AccountId)
AccountPassword  (Type:Attribute:AccountPassword)
AccountStatus    (Type:Attribute:AccountStatus)
Customer         (Type:Customer)
CustomerId       (Type:Attribute:CustomerId)

Rules:

Parm(in:&CustomerId, in:&AccountId, in:&AccountPassword, out:&AccountBalance, out:&AccountStatus);

Source:

&Customer.Load(&CustomerId)
&Account = &Customer.Account.GetByKey(&AccountId)
&AccountBalance = &Account.AccountBalance
&AccountStatus = &Account.AccountStatus

Create an API object called APICustomer and define the following:

Variables:

AccountBalance       (Type:Attribute:AccountBalance)
AccountId            (Type:Attribute:AccountId)
AccountPassword      (Type:Attribute:AccountPassword)
AccountStatus        (Type:Attribute:AccountStatus)
CustomerId           (Type:Attribute:CustomerId)

Service Source:

Customer{
      CustomerInfo(in:&CustomerId, in:&AccountId, in:&AccountPassword, out:&AccountBalance, out:&AccountStatus)
      => ShowCustomerInfo(&CustomerId, &AccountId, &AccountPassword, &AccountBalance, &AccountStatus);
    }

2. Defining the security scheme

To enable GAM, set the Enable Integrated Security property to True at version level. Next, in the API object, select the Authentication or Authorization value for the Integrated Security Level property. Then, perform a Rebuild All.

If you select the Authorization value, you must define the role and the permissions for the role. In addition, you have to associate it with each user. To this end, you can modify the Permission Prefix property to easily identify the permission when assigning it to a user. 

The permission that is generated in this case is APICustomer, and with this permission you can execute any method of the API object.

See Also

HowTo: Configuring the API object security scheme
HowTo: Access secure REST services defined via API Objects