RESTful API Engine fully embraced the HTTP features that were invented to make the Internet faster.

ETag

A web resource may have an optional ETag header also known as an entity tag. Its value must be a unique identifier for the resource content. The engine sets the ETag header to the hash value of the current version of the resource. Web browsers associate the entity tag with the URL of the fetched resource automatically.

If-None-Match

Browsers specify the entity tag in the If-None-Match header when a web application makes the next attempt to get the previously fetched resource. The engine produces the response data, calculates its hash value, and compares the new ETag with the If-None-Match value in the request header. If both values match, then there is no need to transfer the resource content to the client. The engine will set the response status to 304 Not Modified and keep the response body empty. Browsers understand this status code as the instruction to use the previously fetched content.

The ETag and If-None-Match headers provide a simple mechanism to reduce the volume of the client/server traffic. This is especially important when BLOB resources are fetched by the client app repeatedly. Large photos, video, and sound clips are downloaded to the client only once if there are no changes. The subsequent requests to the same resource will result in “304” responses from the server as long as its content has not changed.

The network trace shows two GET requests fetching the list of products. The first request with the "200" status has fetched the resource data. The second request with the "304" status has fetched an empty body and had to re-use the cached data of the previous response instead.

The performance gains are achieved through the reduced response size. The engine will still produce the resource content on the server and calculate its hash values in response to each network request from the client.

If-Match

CRUD operations may find another use for the entity tags. The entity tag specified in the If-Match header of the request will let the RESTful API Engine to detect the midair collisions. The engine will figure the current ETag of the resource when PUT, POST, PATCH, or DELETE are specified as the HTTP method of the request. If the values of ETag and If-Match are not equal, then the error with the 412 Precondition Failed status is returned. Simply put, the error means that another user has changed the resource after it was fetched by the client app.

The value of the ETag header is automatically copied to the etag property of the _links.self hypermedia control in the resource fetched with the $app.restful method.

Client apps can include the etag property in the method argument when changing data or invoking custom actions. If the original resource content with the modified fields is specified in the body property of the $app.restful method argument, then set the etag to true for conflict detection. Otherwise set the etag value to the _links.self.etag property of the previously fetched resource.

Here is an example of the code that will demonstrate the midair collision.

JavaScript

1234567891011121314151617181920212223242526272829303132333435window.addEventListener('load', e => {
    document.querySelector("h1").addEventListener("click", e => {
        // fetch the arbitrary product resource
        $app.restful({
            url: '/v2/products/17'
        }).then(product => {
            // change the unitPrice
            product.unitPrice = product.unitPrice + 0.1;
            // **** "Edit" Attempt #1 *****
            // Send the modified body to the URL specified in
            // the "edit" hypermedia control to PATCH the resource.
            $app.restful({
                url: product._links.edit,
                body: product,
                etag: true
            }).then(changedProduct => {
                // alert the user to the new UnitPrice
                alert(
                    'The new price of "' + changedProduct.productName +
                    '" is ' + changedProduct.unitPrice);
                // The second attempt to patch the product resource will fail 
                // since the etag in "product._links.self.etag" does not match
                // the ETag of the changed product resource on the server.
                product.unitPrice = product.unitPrice + 0.1;
                // **** "Edit" Attempt #2 *****
                $app.restful({
                    url: product._links.edit,
                    body: product,
                    etag: true
                })
                    .catch(restfulException);
            });
        });
    });
});

Add the code to the bottom of the closure in the spa4.js file of the SPA4 client app. The code will run when users click the h1 element showing the name of the app at the top of the page.

The following sequence of events will take place:

User clicks the header of the app.
The product with the primary key specified in the url parameter of the $app.restful method argument is fetched from the /v2/products/17 resource (see the sample response data).
The unitPrice property of the product variable is increased by $0.01. The variable is pointing to the object fetched in the previous step.
The first attempt to edit the resource is performed. The result of the edit is the new state of the resource in the changedProduct argument. The alert will show the name of the changed product and its unitPrice.
The unitPrice property of the same product variable is increased again by the same amount.
The second attempt to edit the resource is performed with the body property in argument still pointing to the product variable. The $app.restful method will use the “old” entity tag extracted from the variable as the value of the If-Match header. The request fails since the ETag of the resource on the server does not match.

The "GET" request fetches the resource from the server. The first "PATCH" request changes the resource field successfully. The second "PATCH" request fails with the "412 Precondition Failed" status due to the midair conflict.

The screenshot shows the alert displayed after the first attempt to edit the product.

The error message will be reported when the alert is closed since the second attempt to edit the product has failed. The engine will recommend specifying the different entity tag in the If-Match header.

The *ETag* of the resource specified in the *If-Match* header of the PATCH request allows detecting the data editing conflicts.

Both attempts to edit the product will succeed if the etag property is removed from the $app.restful argument of the second attempt.

ETag is the version number of the resource. Entity tag makes it possible to detect conflicts when specified in the If-Match header.

A better approach is to use the resource that was fetched during the first attempt to edit the product. Replace references to the product variable with the changedProduct and keep etag property for robust conflict detection.

JavaScript

1234567891011121314151617181920212223242526// fetch the arbitrary product resource
$app.restful({
    url: '/v2/products/17'
}).then(product => {
    // change the unitPrice
    product.unitPrice = product.unitPrice + 0.1;
    // **** "Edit" Attempt #1 *****
    $app.restful({
        url: product._links.edit,
        body: product,
        etag: true
    }).then(changedProduct => {
        // alert the user to the new UnitPrice
        alert(
            'The new price of "' + changedProduct.productName +
            '" is ' + changedProduct.unitPrice);
        changedProduct.unitPrice = changedProduct.unitPrice + 0.1;
        // **** "Edit" Attempt #2 *****
        $app.restful({
            "url": changedProduct._links.edit,
            "body": changedProduct,
            "etag": true
        })
            .catch(restfulException);
    });
});

If the body property is not referencing the original resource fetched with the $app.restful method, then set the etag property explicitly. This is the example of the ad-hoc body parameter with the reference to the etag value.

JavaScript

123456789101112131415161718192021222324252627// fetch the arbitrary product resource
$app.restful({
    url: '/v2/products/17'
}).then(product => {
    // change the unitPrice
    product.unitPrice = product.unitPrice + 0.1;
    // **** "Edit" Attempt #1 *****
    $app.restful({
        url: product._links.edit,
        body: product,
        etag: true
    }).then(changedProduct => {
        // alert the user to the new UnitPrice
        alert(
            'The new price of "' + changedProduct.productName +
            '" is ' + changedProduct.unitPrice);
        // **** "Edit" Attempt #2 *****
        $app.restful({
            "url": changedProduct._links.edit,
            "body": {
                unitPrice: changedProduct.unitPrice + 0.1
            },
            "etag": changedProduct._links.self.etag
        })
            .catch(restfulException);
    });
});

Conflict detection requires a certain amount of work on the server. Do not specify the etag parameter when invoking the $app.restful method if the simultaneous editing of the resources in the client apps is not expected.

Cache-Control

The combination of the ETag and If-None-Match headers allows avoiding the redundant transfer of the resource data to the client. The elimination of the GET requests to the previously fetched resources will provide an enormous performance boost both to the client app and the backend application.

Universal Data Caching

The framework in the foundation of the applications created with Code On Time implements the universal data caching. The simple rules provided by developers can instruct the app to keep some of the fetched data in the application cache for the specified duration. The cached data is shared by the entire user base. This eliminates the database interactions and significantly reduces the response time of the backend application.

This is the example of the universal caching rules directing the Data Aquarium framework to keep the responses from the Suppliers and Categories controllers in the cache for 1 minute. The rules are defined in ~/app/touch-settings.json configuration file.

JSON

12345678910{
  "server": {
    "cache": {
      "rules": {
        "suppliers|categories": {
          "duration": 1
        }
      }
    }
}

By default, only the private caching of the RESTful resources is allowed on the client. Entity tags coupled with the 304 Not Modified status code instruct the clients to reuse the previously fetched data.

The built-in RESTful API Engine piggybacks on the same rules to cache the responses associated with the specific URLs in the application cache on the server. Furthermore it instructs the clients to keep the responses in their own cache for the same duration by including the max-age parameter in the Cache-Control header.

The engine navigates the segments of the requested URL and figures the data controller that will be producing the response. If there are caching rules, then the engine will try to locate the response in the cache. If the previous response is not available, then the physical execution of the request will take place with the subsequent placement to the server cache. In either case the max-age parameter is specified in the Cache-Control header.

The caching of the RESTful resource greatly reduces the response time of the fist fetch by the client. The max-age parameter eliminates the further requests completely for the specified duration.

The single page application SPA4 with CRUD fetches the lookup resources of categories and suppliers when the Edit Product form is displayed.

The items of the *Supplier Company Name* and *CategoryName* lookups are fetched from the RESTful Application with GET requests. The physical data transfer happens one time only for each lookup for each subsequent opening of the *Edit Product* form.

The network log shows the requests executed by the client after the following sequence of user actions: