Method for Working with Table Resources

When the full table of cached resource with one table is requested, GET parameters are supported:

• Pagination parameters:

• hh_order. It sets name of the column to order rows and sorting order, for exmaple, hh_order=name+asc.

• hh_skip. It sets the number of table rows that must be skipped on generating response.

• hh_limit. It sets the number of table rows that must be returned in response.

• Parameters for filtering by value. Parameters have names of the col_<column_name> type, for example, col_id=123.

• The table parameter for filtering multitable resources. It sets name for the table that will be used on requesting a cacheable multitable resource, for example, table=<table name>.

NOTE. Resources with several tables do not support filtering and pagination.

Request parameter conditions:

• Filtering by value is executed before processing pagination parameters.

• Filter by value can be applied only to mobile platform columns of the "text" and "bigint" types.

• Condition of filtering by value is an exact match of parameter value from request with column value of corresponding name.

• Columns of the "bigint" value type must use integer numeric values.

• It is available to apply several filters by value for different columns at the same time.

• Repeated use of parameters with equal names in one request is not allowed.

Example

The resource with one "fruits" resource table containing columns is available:

Column name	Type
_id	bigint
barcode	bigint
shelf_id	text
name	text
photo	bytea

Consider examples of requests with data filtering and pagination as a full table for resource with one table:

Requests	Description
curl -v "<IP address or DNS name of server>/api/v1/rpc/<fruits>/" -H "Authorization: Bearer <user token>"	Get full list of fruits.
curl -v "<IP address or DNS name of server>/api/v1/rpc/fruits/?hh_order=name+desc" -H "Authorization: Bearer <user token>"	Return records sorted descending and by name.
curl -v "<IP address or DNS name of server>/api/v1/rpc/fruits/?hh_order=name+asc&hh_skip=10&hh_limit=10" -H "Authorization: Bearer <user token>"	Sort records ascending and by name, return records from 11 to 20.
curl -v "<IP address or DNS name of server>/api/v1/rpc/fruits/?col_shelf_id=North128" -H "Authorization: Bearer <user token>"	Get fruits located on the North128 shelf.
curl -v "<IP address or DNS name of server>/api/v1/rpc/fruits/?col_shelf_id=North128&col_barcode=123456" -H "Authorization: Bearer <user token>"	Get fruits located on the North128 shelf and have the barcode 12345.
curl -v "<IP address or DNS name of server>/api/v1/rpc/fruits/?hh_order=name+asc&hh_skip=10&hh_limit=10&col_shelf_id=North128&col_barcode=123456" -H "Authorization: Bearer <user token>"	Find fruits located on the North128 shelf and have the barcode 12345. The sort them ascending and by name. The return record from 11 to 20.

If the resource that returns one table is worked with, filtering and pagination are available for these resources.

If the resource that returns several tables is worked with, these resources have constraints on filtering and pagination on the mobile platform side, and an error occurs when trying to use this function: Filtering and pagination can be used by mobile developer only for resources with one table.

If response is generated from cache on a mobile platform server, it contains the ETag unique identifier. If cache is not used, ETag is absent.

To automatically calculate delta using the ETag identifier:

1. Request resource data:

curl -v '<IP address or DNS server name>/api/v1/rpc/<resource name>/' -H 'Authorization: Bearer <user token>' --header 'Content-Type: application/json' -d '{"<input parameter name>": "<input parameter value>"}'

The example of response:

* Trying  0.0 . 0.0 ...
* TCP_NODELAY set
* Connected to  0  ( 127.0 . 0.1 ) port  8000  (# 0 )
> GET /api/v1/rpc/resource_name/ HTTP/ 1.1
> Host: 0 : 8000
> User-Agent: curl/ 7.58 . 0
> Accept: */*
> Authorization: bearer <user token>
>
...
< ETag: "<ETag identifier>"
< Expires: Fri,  30  Mar  2018  13 : 31 : 29  GMT
< Last-Modified: Fri,  30  Mar  2018  12 : 31 : 29  GMT
< Content-Version:  1
...

After executing the request, cache is refreshed on a mobile platform server.

2. Repeat the data request with specifying the ETag identifier:

curl -v '<IP address or DNS server name>/api/v1/rpc/<resource name>/' -H  'Authorization: Bearer <user token>' --header 'If-None-Match: "<ETag identifier>"' --header 'X-Delta: auto' --header 'Content-type: application/json' -d '{"<input parameter name>": "<input parameter value>"}'

The example of response with delta between actual version and version of obtained ETag:

* Trying  0.0 . 0.0 ...
* TCP_NODELAY set
* Connected to  0  ( 127.0 . 0.1 ) port  8000  (# 0 )
> GET /api/v1/json/json1/ HTTP/ 1.1
> Host: 0 : 8000
> User-Agent: curl/ 7.58 . 0
> Accept: */*
> Authorization: bearer <user token>
> If-None-Match: "<ETag identifier>"
> X-Delta: auto
>
...
< Content-Type: application/json; charset=utf- 8
< ETag:  "<ETag identifier>"
< Expires: Fri,  30  Mar  2018  13 : 34 : 33  GMT
< Last-Modified: Fri,  30  Mar  2018  12 : 34 : 33  GMT
< Content-Version: delta v1-v4
...
[{ "name" : "table_name1" , "insert_rows" : <table rows>, "delete_ids" : [ 3, 7 , 10 ]},
{ "name" : "table_name2" , "insert_rows" : <table rows>, "delete_ids" : [ 3 , 7, 10 ]}]

The response contains delta that returns the rows that must be inserted into the saved table, or row identifiers that must be deleted:

[
   {
     "name" :  "table_name1" ,
     "insert_rows" : <table rows>,
     "delete_ids" : [ 3 , 7 , 10 ]
   },
   {
     "name" :  "table_name2" ,
     "insert_rows" : <table rows>,
     "delete_ids" : [ 3 , 7 , 10 ]
   }
]

NOTE. If cache is not changed, values of returned parameters insert_rows and delete_ids are empty.

If caching is used, cache can be loaded on lost connection. Before executing request determine user token.

The request must use the X-Range header together with If-Range and Range, where N is a byte number, at which data transfer is aborted:

curl -v '<IP address or DNS server name>/api/v1/rpc/<resource name>/'  -H  'Authorization: Bearer '<user token> --header 'Content-Type: application/json' --header 'X-Range: bytes=<N>' --header 'If-Range:"<ETag identifier>"' --header 'Range: bytes=<N>' --header 'If-Match: "<ETag identifier>"' -d '{"<input parameter name>": "<input parameter value>"}'

The example of response from the N byte:

* Trying 0.0.0.0...
* TCP_NODELAY set
* Connected to <server name> (0.0.0.0) port 80 (#0)
> GET /api/v1/rpc/<resource name>/ HTTP/1.1
> Host: <server name>
> User-Agent: curl/7.61.1
> Accept: */*
> Authorization: Bearer <user token>
> Content-Type: application/json
> X-Range: bytes=<N>-
> If-Range: "<ETag identifier>"
> Range: bytes=<N>-
> If-Match: "<ETag identifier>"
>
< HTTP/1.1 206 Partial Content
< Server: nginx/1.9.11
< Date: <date>
< Content-Type: application/json; charset=utf-8
< Transfer-Encoding: chunked
< Connection: keep-alive
< ETag: "<ETag identifier>"
< Expires: <date>
< Last-Modified: <date>
< Content-Version: 12
< Vary: Accept, Cookie, Accept-Encoding
< Allow: GET, POST, HEAD, OPTIONS
< X-Frame-Options: SAMEORIGIN
< Content-Range: bytes <N>-/*