Docs‎ > ‎REST APIs‎ > ‎

Post

This page describes aspects of POST (insert).
 

Creating a Simple Row

In the simplest case, you can POST a request for a resource, supplying JSON such as the customer example below.

URL
http://houston.d.espressologic.com/rest/abl/demo/v1/customer

JSON Request
{
    "name": "Newly Posted",
    "credit_limit": 900
}




 

Creating a set of rows

Objects are created using the POST call, with a resource as the payload. This can be a top-level resource, or a contained resource. For instance, let's assume that you have a resource defined as defined in LogicDemo:

OneCustomer (table customer)
+ Orders (table purchaseorder)
   + Lineitems (table lineitem)

Let's say we want to create an order with a line item, all with a single call. We would make a POST call to http://houston.d.espressologic.com/rest/abl/demo/v1/OneCustomer.Orders with the following 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
 }
]
}


A few things to note here:
  • Notice the URI: we're using a resource (Orders) contained in another resource (OneCustomer), so we use a dot notation to specify that.

  • Also, you must use a Resource that contains all the levels used in the submitted JSON.  You could not, for example, submit the example below to the base table resource.

  • We only need to specify the required attributes. Non-required attributes do not have to be specified (although they can be). In this example, the primary keys for both objects are generated, so we can't possibly know them in advance.

  • We specified the foreign key 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 one object in this example, but it could also be an array of objects. If we'd wanted to create multiple orders, we could have sent them in an array.
Assuming all goes well, the response will look something like (full json here):

{
  "statusCode": 201,
  "txsummary": [
    {
      "@metadata": {
        "href": "http://houston.d.espressologic.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
    },
...


Let's look at that response in detail:

"statusCode": 201,

The status code is the standard HTTP status code. You could retrieve it from the HTTP response, but it's also here for convenience. Code 201 means that the insert was successful.


Client Refresh - txsummary

Client Refresh

The txsummary information is provided so that client code can refresh the screen to show the effects of the transaction.

In this example, the End User needs to see Lineitem's total amount, the order's amount, and the customer balance.

Since this is the Post response message, there is only 1 communications trip, so latency is minimized.

The txsummary part of the response contains all the objects that have been affected by the transaction. In this example, there are four objects, in no particular order:

 ...
   {
      "@metadata": {
        "href": "http://houston.d.espressologic.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://houston.d.espressologic.com/rest/abl/demo/v1/OneCustomer/Bravo%20Hardware",
        "resource": "OneCustomer",
        "verb": "UPDATE",
        "checksum": "A:e8189288a7a20d23"
      },
      "name": "Bravo Hardware",
      "balance": 120,
      "credit_limit": 5000
    },
    {
      "@metadata": {
        "href": "http://houston.d.espressologic.com/rest/abl/demo/v1/OneCustomer.Orders.Lineitems/1001",
        "resource": "OneCustomer.Orders.Lineitems",
        "verb": "INSERT",
        "checksum": "A:36cf8a467175fea6"
      },
      "lineitem_id": 1001,
      "product_number": 2,
      "order_number": 1000,
      "qty_ordered": 2,
      "product_price": 25,
      "amount": 50
    },
...


The first object is the new order just created. It now has a primary key, which was generated by the database. It also 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. We did not specify that this customer should be updated: it was updated as a result of the business logic executing in the transaction. In this case, the customer's balance has increased by the amount of the new order. This change is returned to us using the LargeCustomers resource because we were using the LargeCustomers.Orders, and therefore it seemed logical to use the closest fitting resource: LargeCustomers.

The third object is the new line item. Like the order, it also has been given a primary key, and the foreign key to its containing order was automatically set as described under Primary Key Generation. Note that the Price and Amount were also filled in by the business logic.

Latency: incremental update, single message refresh

Latency is a significant performance factor in any distributed application.   The approach above minimizes latency:
  • only changes are sent to the server
In the example above, 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.  And, 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.  As described above, 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

Note the multi-table request examples above were based on having defined a Custom Resource.  Default resources built on Base Tables do not support multi-document update requests.