LOOKUP Metadata Action Tag

LOOKUP Metadata Action Tag
lac42
You can enable API users to POST data, where your schema uses keys that
CA Live API Creator
 automatically generates and that the sender cannot know, by using the 
LOOKUP
 metadata action tag.
In this article:
3
Background
Consider an API for partners to place orders. Imagine that the
Items
resource includes a foreign key to the
Product
table-based resource, where the key is a DBMS-generated key. The API user knows a product name but does not know the product number within
CA Live API Creator
.
You can provide an API that accepts product names without having to know product numbers (typically the foreign key) by defining your resources that expose the appropriate attributes and that support JSON definitions. The JSON definitions provide lookups by way of the 
LOOKUP
 metadata action tag to compute foreign keys, using natural keys, so API users do not need to provide them. 
Example: The Demo API Sample
The
Demo
 API sample includes the
OrderLookupParent
 table-based resource. You can insert an order by invoking a PUT request with the following JSON to the 
OrderLookupParent
 resource:
{
    "@metadata":  {"action":"INSERT"},
   "Customer": {
      
"@metadata": { "action":"LOOKUP",  "key":"Name"},
      "Name":"Alpha and Sons"
   },
   "Items":[
       {
          "Product":
          
{ "@metadata": {"action":"LOOKUP", "key":"ProductName"},
             "ProductName":"Hammer"
                },
        "Quantity": 1
       }
   ]
}
For the lookup to happen, within the JSON, the 
@m
etadata
 object must:
  • Include an 
    action
     attribute with a value of 
    LOOKUP
    .
  • Include a 
    key
     attribute with a value that must be a single attribute or an array of attribute names. The API uses the attribute to find the object in question. 
  • Contain the attributes that are referenced in the 
    key
     attribute.
Lookup Processing Where the Key Is Included Within the JSON
This JSON uses the 
LOOKUP
 metadata action at two points. The first 
LOOKUP
 metadata action is a lookup for a customer using the
Name
 key property. The second LOOKUP metadata action is where the
ProductName
 attribute is the effective key and is a lookup for an Item's 
product_number
. The
ProductName
 key dictates lookup processing and identifies the fields in the JSON segment (Product) used to lookup the product, as follows:
CA Live API Creator
:
  1. De-aliases 
    ProductName
     to
    name
    .
    The string can be an array of attribute names.
  2. Uses the fields to construct a SQL command to a query on product.
    The fields do not necessarily need to comprise a primary or unique key, though in practice they typically do.
  3. (If a row is returned) Assigns the foreign key (which may not necessarily be the
    key
    fields) to the containing resource level. In this case, the Item's 
    product_number
    is set.
To view a similar example illustrated, see the B2B API Sample.
Lookup Processing Where the Key Is Defined in the Resource
If you do not provide the 
@metadata
 key within the JSON,
CA Live API Creator
 uses the resource attribute that is selected as the effective key within the table-based resource (the 
Key
 checkbox for the resource attribute is selected). If it does not find the defined key for the resource, it uses the primary key for the underlying table.
For more information about how to select resource attributes as effective keys, see Define Table-Based Resource Types.
The following steps illustrate how you can modify the
OrderLookupParent
 resource to use the key that is defined within the resource:
  1. Modify the
    Product
    subresource by selecting the
    Key
    checkbox for the name column (alias as 
    ProductName
    ), and then save your changes.
  2. In the REST Lab, PUT the following JSON (without the key) to the 
    OrderLookupParent
     resource to insert an order:
    {
        "@metadata":  {"action":"INSERT"},
       "Customer": {
          
    "@metadata": { "action":"LOOKUP",  "key":"Name"},
          "Name":"Alpha and Sons"
       },
       "Items":[
           {
              "Product":
              
    { "@metadata": {"action":"LOOKUP"},
                 "ProductName":"Hammer"
                    },
            "Quantity": 1
           }
       ]
    }
Request Events to Create @metadata
You can pre-process, and alter, incoming requests using request events. You can insert the 
@metadata
 action tag without requiring it from the client.
For more information about how to provide entry points using request events, see Event Handlers.