Lookup Metadata Action

You can enable external/partner systems to post data, where your schema uses automatically-generated keys that cannot be known by the sender, using the Lookup metadata action tag.

Background

Consider providing an API for partners to place orders. Imagine that the Items include a foreign key to Product, where the key is a DBMS-generated key. External/partner systems know a product name but do not know the product number within API Creator.

You can provide an API that accepts product names and not product numbers by:

  • Defining resources that expose the appropriate attributes.
  • Supporting JSON definitions that provide lookups to compute foreign keys, using natural keys, so clients do not provide them. You do this by using the Lookup metadata action tag.
For this to happen, the metadata object must:
  • Include an action attribute with a value of LOOKUP.
  • Include the 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. This attribute can be the @metadata key, which is the key defined in the @metadata section, the defined key for the resource, or the primary key for the underlying tableThe API uses the @metadata key if provided. If it is not provided, it uses the defined key for the resource. If it does not find the defined key for the resource, it uses the primary key for the underlying table.
  • Contain the attributes referenced in the key attribute.

Example: The Demo API

The Demo API defines the Product resource. The following image shows this resource on the Create, Resources, Attributes page:

JSON and Lookup Processing

You can PUT the following JSON:

{  
   "@metadata":  {"action":"INSERT"},
   "Customer": {  
      "@metadata": { "action":"LOOKUP",  "key":"Name"},
      "Name":"Alpha and Sons"
   },
   "Items":[  
      {  
         "Product": 
          { "@metadata": {"action":"LOOKUP", "key":"ProductName"},
             "ProductName":"Hammer"
                },
        "Quantity": 1
       }
   ]
}

The following JSON uses the LOOKUP metadata action at two points. The second LOOKUP metadata action, in bold, is a lookup for an Item's product_numberThe key property dictates lookup processing and identifies the fields in the JSON segment (Product) used to lookup the product, as follows:

API Creator:

  1. De-aliases ProductName to name.
    Note: The string can be an array of attribute names.
  2. Uses the fields to construct a SQL command to a query on product.
    Note: 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 Business to Business Example.

Defined Key

Predefine attributes as part of lookup.

Request Events to Create @metadata

Building on this example, your external/partner system may push back when asked to insert the @metadata action tag. You can pre-process, and alter, the incoming request 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 Request Event Handlers.