Invoking APIs‎ > ‎

PUT

You make updates using the PUT call, with a resource as the payload. In most cases, you will want to use the URI returned in the @metadata section to refer to a specific object.

  • Test your updates using the REST Lab.
  • Verify proper operation (SQL and logic) using the Log.

Batched Update

You can retrieve large amounts of data in a single retrieval request to reduce latency. Similarly, you can send in multiple rows on updates. You can update by sending the following resources:

  • A single resource.
  • Homogeneous resources.
  • Heterogenous resources.

Update by Sending a Single Resource

The most basic update is to send in a single resource. In database terms, this might represent multiple rows, such as an Order and its Lineitems. To do this, you specify the URL as the top-level resource. The top-level resource does not need to be the root object in the resource definition. For example, you might define a resource of Customers, Orders, and Lineitems. To update an order, you send the order and any updated Lineitems. For example, to update Order 1, the URL would be projURL/Customer.Orders/1. In many cases, the end user may update only one Lineitem of several.

Updates are incremental. You only need to send the altered data. It is not an error to send unaltered data (for example, the unchanged Lineitems). If you send unaltered data, the data is not updated.

Update by Sending Homogeneous Resources

You can update by sending in an array of resources, such as a list of Orders with their contained LineItems. This operates like updating by sending a single resource, except the URL would be projURL/Customer.Orders. Each of the contained rows must conform to the type denoted in the URL. They may include contained items (for example, Lineitems for Customer.Orders).

Update by Sending Heterogeneous Resources

For optimal client operation (though a less common REST idiom), you can update by sending the resource a set of unrelated rows for updates with no requirement that they be the same type or defined within the same root resource node. This supports the paradigm where an application might enable end users to retrieve multiple rows of multiple types, make extensive edits (including to multiple types), and send in the changes as a single request. For example, an end user might alter Order 1, change a Lineitem for Order 2, and add a Lineitem for Order 3.

You specify this as a PUT directed to the projURL. Each row is required to contain an @metadata section (used by the system to determine the type of row so it can find the appropriate logic). Further, these can be an assortment of inserts, updates, and deletes. You specify which by way of an @metadata verb property as follows:

{
"@metadata": {
"href": "http://rest.ablserver.com/v1/product/27",
"entity": "product",
"verb": "UPDATE",
"checksum": "9e0724221638aa5bcd35cff70826115ce"
},

For more information about projURL, see The API Project URL.

Incremental Update

You can retrieve large amounts of data in a single retrieval request to reduce latency. Send back the objects that have changed in the PUT.

Refresh Information

It is common that updates have computational side effects. This can be both on rows updated or related data. For example, paying an order would reduce the customers' balance. Good UI design entails these results are shown to the end user. In many cases, this sadly requires a subsequent "fetch for refresh". This is inefficient, and in some cases not possible when the refreshed data has a system-generated primary key.

API Creator sends back the update response that contains all the updated rows. These are coerced into the types designated in the updating resource.

For more information, see Transaction Summary.

Optimistic Locking

You must supply this value on update. This is typically virtually automatic, since it is returned to you on retrieval. In rare circumstances, you can supply the checksum: "override" to bypass this check.

Important! To prevent lost updates, do not bypass integrity checks by supplying the checksum: "override".

Relationships

Example: By Containment

This example uses the OneCustomer resource from LogicDemo, which contains a Customer, Order, Lineitems and Product (a parent sub-resource). You create an order using the following nodal URL:

http://.../myserver/rest/abl/demo/demo1/OneCustomer.Orders

The following response is expected:

{
  "customer_name":"Alpha and Sons",
  "Paid":false,
  "Lineitems": [
  {
    "product_number":1,
    "qty_ordered":3
  }
]
}

The Lineitem is not attached to the order, since this was implicit in the containment.

Example: By Foreign Key

Using the same example as By Containment, attach the Lineitem to the Product with a foreign key.

Example: By Sub Resource

Using the same example as By Containment, you can attach the Lineitem to the Product as shown in the following code snippet. Provide the foreign key a parent sub-resource:

{
  "customer_name":"Alpha and Sons",
  "Paid":false,
  "Lineitems": [
  {
    "product_number":1,
    "qty_ordered":3,
    "Product": {
      "@metadata": {
        "href": "http://localhost:8080/KahunaService/rest/abl/demo/demo1/OneCustomer.Orders.Lineitems.Product/1",
        "checksum": "6e71fde53ade7203d8dc2476c49af241"
       },
    "product_number": 1,
    "name": "Hammer",
    "price": 10
     }
  }
]
}