Updates are done using the PUT call, with a resource as the payload. In most cases, you'll want to use the URI returned in the @metadata section to refer to a specific object.
You can use the RESTLab
to test your updates, and the Log
to verify proper operation (SQL and logic).
You may retrieve large amounts of data in a single retrieval request to reduce latency. Similarly, you can send in multiple rows on updates. The sub-sections below discuss various alternatives
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.
Specify the URL as the top-level Resource. It 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 need only send the Order and any updated Lineitems. So, to update Order 1, the URL would then be
In many cases, the End User may update only 1 Lineitem of several. Updates are incremental: you only need to send the altered data. It is not an error to send unaltered data (e.g., the unchanged Lineitems); these will not be updated.
You can also send in an array of Resources, such as a list of Orders with their contained LineItems. This operates just as above, except the URL would be
Each of the contained rows must conform to the type denoted in the URL. They may include contained items (e.g, Lineitems for Customer.Orders).
A final option is provided for optimal client operation (though a less common REST idiom) - you can send it a set of unrelated rows for updates with no requirement that they be the same type, or even 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. So, for example, an End User might alter Order 1, change a Lineitem for Order 2, and add a Lineitem for Order 3.
This is specified 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 via an @metadata verb property as follows:
You may retrieve large amounts of data in a single retrieval request to reduce latency. It is not necessary to send back the entire set of objects in a PUT. You can send only the objects that have changed.
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 therefore 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 Summary Information.
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. Be very cautious - this bypasses integrity checks that are critical in preventing lost update.
In this example, we have used the OneCustomer resource from LogicDemo, which contains a Customer, Order, Lineitems and Product (a parent Sub Resource). Using this nodal URL:
we can create an Order like this:
"customer_name":"Alpha and Sons",
Observe that we did not need to attach the Lineitem to the Order, since this was implicit in the containment.
By Foreign Key
In the same example, we attach the Lineitem to the Product with a foreign key.
By Sub Resource
Alternatively, you can attach the Lineitem to the Product as shown below. Note we did not specify the Foreign Key, but instead provided a parent Sub Resource.
"customer_name":"Alpha and Sons",