Docs‎ > ‎CA Live API Creator‎ > ‎Create‎ > ‎Resources‎ > ‎REST APIs‎ > ‎

Complex transactions

REST uses the HTTP verb (GET, POST, PUT, etc...) to tell the server what action to take. This is a problem if you need to do multiple things (e.g. an insert, and update and a delete) in a single transaction.

Therefore API Creator extends REST to allow for complex transactions. In a PUT and POST request, if objects contain certain extra attributes, they will be processed differently.

1 - POST requests

In a POST, if an object looks like the following:

....
"lineitems": [
  {
    "qty": 3,
    "price": 10.99,
    "product": {
      "@metadata": {
        "action": "LOOKUP",
        "key": "name"
      },
      "name": "Widget"
    }
  }
],
....

then that object (the product in this case) will be looked up rather than inserted. This is useful if you need to connect some of your new objects to existing objects, but you don't want to use primary keys.

For this to happen, the following conditions must be met:

  1. The metadata object must include an attribute named action, and its value must be LOOKUP
  2. The metadata object must include an attribute named key, and its value must be a single attribute or an array of attribute names, which will be used to find the object in question. 
    1. More precisely, there are 3 possible keys.  The primary key for the underlying table.  The defined keys for the Resource (specified in Designer).  And thirdly, the key defined in the @metadata section.  The @metadata key is used if provided.  If not, the resource defined key is used.  If neither is found, the primary key is used.
  3. The object must contain the attributes referenced in the key attribute just described

If the object in question is not found, or if more than one object is found, then the request will fail.

2 - PUT requests

In a PUT request, each object may specify what should be done with it. For instance:

[
  {
    "@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"
    }
  }
]

In this case, the first object (Customer) will be inserted, the second object (Product) will be updated, and the last object (Address) will be deleted.


metadata actions


There following actions that can be specified:
This is a combination of INSERT, UPDATE and LOOKUP.  The "key" is used to try to find a record as described in LOOKUP.  If a single record is found, this record is updated with provided values.  If a record is NOT found, the provided values are used to INSERT a new record.  Checksum is NOT required and is implicitly "override".

Use of Parent Sub-Resources can be used with these actions as well.