Invoking APIs‎ > ‎

Complex Transaction Processing

REST uses the HTTP verb (such as GET, POST, PUT) to tell the server what action to take. This verb applies to each row in the request. Some transactions, however, require a mix of different types of verbs. You can specify greater granularity by providing metadata action tags that designate the verb to take on each row. This can provide substantial value in choreographing the persistence actions taken in processing a request. In addition, you can create and/or link related data using Live API Creator services. 

Note: These services apply to how to process the rows in the request. Reactive logic then applies to each of these row.

Metadata Actions

You can link child rows to parent rows, without the requirement for the client to supply autonum identifiers (which they may not know) by inserting @metadata action tags. You can use parent sub-resources with these actions.

You can specify the following action tags:

  • DELETE

For example, delete using name field for unique key:

{"@metadata" : {"action":"DELETE", "checksum":"override", "key":"name"},
"name":"David 2",
"some_val":202}

For more information about using the DELETE metadata action tag, see DELETE.

  • LOOKUP
For more information about the LOOKUP metadata action tag, see Lookup Metadata Action.
  • INSERT
For more information:
  • UPDATE
  • MERGE_INSERT
For more information about the MERGE_INSERT metadata action tag, see Merge Insert Metadata Action.

For more information:

Mix and Match

You can use different metadata action tags in the same request. In the following code snippet, the Customer object is inserted (using the Insert metadata action tag), the Product object is updated (using the UPDATE metadata action tag), and the Address object is deleted (using the Delete metadata action tag):

[
  {
    "@metadata": {
      "entity": "Customer",
      "action": "INSERT"
    },
    "name": "Acme Inc",
    "credit_limit": 5000
  },
  {
    "@metadata": {
      "href": "https://foo.my.espressologic.com/rest/foo/bar/v1/Product/123",
      "checksum": "123456789ABCDEF",
      "action": "UPDATE"
    },
    "unit_price": 0.99
  },
  {
    "@metadata": {
      "href": "https://foo.my.espressologic.com/rest/foo/bar/v1/Address/456",
      "checksum": "123456789ABCDEF",
      "action": "DELETE"
    }
  }
]

Metadata Key

It is a common pattern to find or update rows from external sources, where the system key is not known. This is often because the actual key may be a database-generated number, unknown to external systems or businesses.

For example, the B2B test posts an order for Products. Products are identified by a ProductID. Since external systems cannot know such names, we can use the LOOKUP metadata action tag, like this:

{ "CustomerNumber":"VINET", "Items":[ { "Product":{ "@metadata":{ "action":"LOOKUP", "key":"ProductName" }, "ProductName":"Pavlova" }, "Quantity":1 },

The key is used to find a Product row by ProductName, extract its ProductID, and store this in the Items row being inserted. The LOOKUP verb automates all of this.

While the fields comprising the key typically comprise a unique key, this is not strictly required. The only requirement is that the find returns exactly one row.

In addition to the LOOKUP metadata action tag, the key is available in the MERGE_INSERT metadata action tag.

For more information about the MERGE_INSERT metadata action tag, see Merge Insert Metadata Action.