Manage Non-Persistent Attributes

Manage Non-Persistent Attributes
lac32
You can extend your data model to include attributes that are not in the schema. Non-persistent attributes (NPAs) are pseudo-columns (attributes) that you can add to your API without affecting the database schema. They are useful when you cannot alter the database schemas. For example, another application that does not change the value is using the NPA. They are also useful when you want to minimize data-maintenance tasks. For example, you want to further speed development.
Use NPAs for:
  • Retrieval logic.
     For example, you store a first and last name but create an API that returns the full name.
  • Update logic.
     Use derivations to compute values and roll-up sum/count aggregates, as shown in the Business to Business (B2B) sample.
You can use NPAs in resources and rules, such as derivation and validation rules, and you can view them in Data Explorer. Like regular columns, the NPAs you use in resources can return values, and you can use the NPAs you use in derivation rules in other rules.
NPAs can incur substantial performance overhead as compared to columns that are stored in your database.
For more information about performance, see the "NPA Best Practices" section.
You can tune API Server using NPAs, analogous to SQL optimizer hints. 
CA Live API Creator
 can compute rules as SQL expressions if the rules follow certain restrictions. It computes rules that compute the value of NPAs faster than other rules.
 In this article:
Add and Use Non-Persistent Attributes
Complete the following process to add and use an NPA:
The B2B sample uses NPAs to provide a discount to customers who eat healthy.
For more information about the B2B sample, see Business to Business Example.
Verify the Prerequisites
Before you can add an NPA, ensure that you have:
  • Defined tables or views.
  • Verified your data source.
Add the Non-Persistent Attribute to your Data Source
  1. With your API open, in the Create section, click
    Data Sources
    .
    A list of the data sources for your API display.
  2. From the list of data sources, select the data source to which you want to add the NPA.
  3. Click the 
    Non-persistent attributes
     tab.
    A list of your NPAs for the selected data source display.
  4. Above the NPA list, click
    Add
    .
    An NPA is added to your data source.
  5. Define the NPA, and then save your changes.
    As an example, the following image shows the 
    fullName
    NPA that has been added to the Derby - Northwind data source (in the B2B Northwind API):
    Screen Shot 2016-03-16 at 2.53.19 PM.png
The NPA is added to your data source.
Create the Derivation Rule
Create the derivation rule for the NPA value.
For more information about the list of derivation rule types you can create, see Rule Types.
As an example, the following image shows the rules for the
Healthy Food Discount
topic in the B2B Northwind API:
Screen Shot 2016-03-16 at 2.56.13 PM.png
Select the NPA your Resource Returns
For more information about how to select the attributes that your resource returns, see Customize your API.
  1. With your API open, in the Create section, click
    Resources
    .
    A list of resources display.
  2. Click the
    Attributes
    tab.
    As an example, the following image illustrates selecting the 
    fullName
     and the
    Region
    NPA as the attribute that the 
    SalesRep
    resource returns (in the B2B Northwind API):
    Screen Shot 2016-03-16 at 2.57.50 PM.png
  3. Complete the following fields, and then save your changes:
    Columns
    Clear the checkbox for the base entity columns you do not want the resource to return.
    Default:
     Selected.
    Attribute name
    Select which attributes your resource returns (subject to security) and override the default name. Each resource attribute is identified with an (alias) name, and includes a 
    column_name
     and 
    format
    .
    Optional: 
    Yes
    If you do not select the response attributes, this resource returns all attributes in table.
The attributes that you want your resource to return are selected and saved.
NPA Best Practices
As with conventional systems, you must make design decisions about whether to persist derived data. Historically, it has been a trade-off:
  • Performance.
     Non-persisted data can perform orders-of-magnitude slower. This most often occurs with aggregates, when there are many children per parent, or when aggregations chain. For example, it can be expensive to compute a balance by adding up all the items for all the orders of a customer, or to compute a department budget by recursively summing all the sub departments.
  • Data consistency.
     All applications must update the derivations properly to avoid consistency errors.
The challenge has been that it is not always clear how data distributions will turn out. Recoding all the accessing logic to switch strategies can be expensive. These are often discovered near the end of development when full test data volumes are loaded, and can result in significant rework and delays.
While the dilemma remains,
CA Live API Creator
 can eliminate the cost of rework. If you add or remove NPAs, API Server adjusts your logic accordingly. For example, 
CA Live API Creator
maintains aggregates using adjustment logic.
Consider the following when establishing best practices for your API:
  • If you are using existing system and you cannot change the schema, use NPAs.
  • If you can change the schema to define persistent attributes, define the attributes as NPAs. This eliminates the SQL required to synchronize your data with your rules. If you have tested your logic and then you discover performance issues, delete the NPAs and alter the schema to define the persisted columns.
    API Creator re-optimizes your logic.
    Logic processing interacts with the values that are stored in the database. If you persist attributes, you must synchronize your data with logic.
This flexibility is analogous to using relational databases, where you can add and remove indexes without recoding. API Server optimizes your update logic.
For more information about how 
CA Live API Creator
maintains aggregates using adjustment logic, see Performance.