POST

POST
lac42
This article describes aspects of POST (insert).
In this article:
 
 
2
 
 
Create a Simple Row
In the simplest case, you can POST a request for a resource, supplying JSON such as the following customer example.
URL:
 
http://localhost:8080/APIServer/rest/abl/demo/v1/customer
JSON Request:
 
{
"name": "New Customer",
"balance": 0,
"credit_limit": 9000
}
The following image shows this call and the expected response in the REST Lab:
  Screen Shot 2018-06-07 at 4.08.14 PM.png  
Create a Set of Rows
You can create objects by making a POST call with a resource as the payload. This can be a top-level resource or a contained resource. For example, you have a resource defined as defined in the Demo API sample:
OneCustomer (table customer)
+ Orders (table purchaseorder)
+ Lineitems (table lineitem)
You can create an order with a line item with a single call. The POST response message is only one communications trip, which minimizes latency.
Prerequisites:
 
  • You are using a resource that contains all the levels used in the submitted JSON.
  • You have specified the required attributes.
Make a POST call to the following URI using the following body:
http://server.acme.com/rest/abl/demo/v1/OneCustomer.Orders
The 
Orders
 resource is contained in the 
OneCustomer
 resource. A dot notation specifies that.
Body:
 
{
"notes": "Please rush this order",
"customer_name": "Bravo Hardware",
"salesrep_id": 1,
"Lineitems": [
{
"product_number": 1,
"qty_ordered": 1
},
{
"product_number": 2,
"qty_ordered": 2
}
]
}
The foreign key is specified between the new order and its parent customer, but we did not specify the foreign key between the new line item and the new order. This is implied by the containment of the line item in the order.
The body consists of a single object in this example, but it could also be an array of objects. If you want to create multiple orders, you can send them in an array.
Response:
 
 
The following response is expected:
{
"statusCode": 201,
"txsummary": [
{
"@metadata": {
"href": "http://server.acme.com/rest/abl/demo/v1/OneCustomer.Orders.Lineitems/1000",
"resource": "OneCustomer.Orders.Lineitems",
"verb": "INSERT",
"checksum": "A:70946727e40b521f"
},
"lineitem_id": 1000,
"product_number": 1,
"order_number": 1000,
"qty_ordered": 1,
"product_price": 10,
"amount": 10
},
...
The complete JSON response is available from the  file.
The following response is the standard HTTP status code:
"statusCode": 201,
The 
201
 status code indicates that the insert was successful.
You can retrieve the status code from the HTTP response, but it is also here for convenience.
For more information about standard HTTP status codes, see the w3.org site.
Client Refresh - txsummary
Client Refresh
The 
txsummary
 part of the response is provides so that the client code can show the effects of the transaction. This part of the response contains all the objects that have been affected by the transaction.
 In this example, the end user needs to see Lineitem's total amount, the order's amount, and the customer balance. There are four objects, in no particular order:
...
{
"@metadata": {
"href": "http://server.acme.com/rest/abl/demo/v1/OneCustomer.Orders/1000",
"resource": "OneCustomer.Orders",
"verb": "INSERT",
"checksum": "A:8f2e88f8e7c83645"
},
"order_number": 1000,
"amount_total": 60,
"paid": false,
"item_count": 2,
"notes": "Please rush this order",
"customer_name": "Bravo Hardware",
"salesrep_id": 1
},
{
"@metadata": {
"href": "http://server.acme.com/rest/abl/demo/v1/OneCustomer/Bravo%20Hardware",
"resource": "OneCustomer",
"verb": "UPDATE",
"checksum": "A:e8189288a7a20d23"
},
"name": "Bravo Hardware",
"balance": 120,
"credit_limit": 5000
},
...
The first object is the new order that 
CA Live API Creator
 created. 
CA Live API Creator
 generates the primary key for this object. The object has an 
amount_total
, calculated by the business logic, reflecting the line item in the order.
The second object is the customer who owns the new order.  
CA Live API Creator
has updated the customer as a result of the business logic executing in the transaction. In this case, the customer's balance increased by the amount of the new order. 
CA Live API Creator
 returns this change using the 
LargeCustomers
 resource because the example uses the 
LargeCustomers.Orders
 table, and therefore it seemed logical to use the closest fitting resource: LargeCustomers.
The third object is the new line item. Like the order, this object also has a primary key. The foreign key to its containing order is set. The business logic fills in the 
Price
 and 
Amount
.
For more information about the foreign key, see Automatic Key Generation.
Latency: Incremental Update, Single Message Refresh
Latency is a significant performance factor in any distributed application. The previous approach minimizes latency:
  • Only changes are sent to the server. 
    In the previous example, imagine the screen is first populated with a customer and several orders. Adding a new order does 
    not
     require the client to send the entire customer/order object to the server - only the changed data is required. RESTful requests support for Nested Documents avoids the need to POST separate requests for each table (Customers, Orders, Items)
  • Single-message refresh. 
    It is clearly a user interface requirement to show the effects of the transaction, the updated data values. These are sent back from the Post message. The client has no need to issue a second "refresh" query to obtain the latest values.
Nested Document Updates - Custom Requests
The previous multi-table request examples are based on having defined a resource. Default resources built on base tables do not support multi-document update requests.
Issue an Insert (POST) using the REST Lab
You can process batches of JSON. For example, you can insert this JSON in the 
Demo
 API using POST:
[
{
"name": "New Cust 1",
"balance": 0,
"credit_limit": 900
},
{
"name": "New Cust 2",
"balance": 0,
"credit_limit": 5000
}
]
For more information about how to issue a POST using the REST Lab, see Test your API Using the REST Lab