Invoking APIs‎ > ‎

POST

This page describes aspects of POST (insert).

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 in the REST Lab:

Create a Set of Rows

Create objects 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 the Logic Demo:
OneCustomer (table customer)
+ Orders (table purchaseorder)
   + Lineitems (table lineitem)

You can create an order with a line item with a single call.

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

Note: The resource Orders is contained in the resource OneCustomer. 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 one object in this example, but it could also be an array of objects. If you wanted to create multiple orders, you could send them in an array. Assuming all goes well, the response will look something like the following code snippet:

{
  "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
    },
...

For more information about the complete JSON response, see New Order Response.json.

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

"statusCode": 201,

For more information about standard HTTP status codes, see the w3.org site.

Client Refresh - txsummary

Client Refresh

The txsummary information is provided so that client code can show the effects of the transaction by refreshing the screen. 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 one 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://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 just created. This object has a primary key that API Creator generates. 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. The customer has been 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, 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 Custom 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 API Demo project using POST:

[
  {
    "name": "New Cust 1",
    "balance": 0,
    "credit_limit": 900
  },
  {
    "name": "New Cust 2",
    "balance": 0,
    "credit_limit": 5000
  }
]