REST APIs

Enabling REST in Ampool

To enable the REST support Ampool servers need to be started w/ following additional properties

--J=-Dgemfire.start-dev-rest-api=true
--J=-Dgemfire.http-service-port=REST_PORT
--J=-Dgemfire.http-service-bind-address=localhost

Where:

  • REST_PORT is the port for the REST service, default is 8080.
  • http-service-bind-address is a the hostname to which http/rest service to be bound.

See Deploy/MASH (CLI) for more details in starting Ampool Server.

e.g.

start server --name=SERVER_NAME  --server-port=SERVER_PORT --J=-Dgemfire.start-dev-rest-api=true --J=-Dgemfire.http-service-port=REST_PORT -–J=-Dgemfire.http-service-bind-address=localhost

On enabling REST Swagger UI will be started at

http://localhost:8080/ampool-api/swagger-ui.html

Swagger UI provides a browser-based test client that allows you to visualize and try out Ampool REST APIs.

Using REST for Operations on an Existing Table

Let's say an Ordered and Immutable table was created using the mash command line tool:

mash> create table --name=MyTable1 --type=ORDERED_VERSIONED --columns=Name,Gender --ncopies=2 --versions=4

mash> create table --name=FTable1 --type=IMMUTABLE --columns=ID

The Ordered memory table can be described as:

mash>describe mtable --name=MyTable1
.................................................................................................
Name            : MyTable1
Data Policy     : partition
Hosting Members : server1

Non-Default Attributes Shared By Hosting Members

      Type        |          Name           | Value
----------------- | ----------------------- | ---------------------------------------------------
Table             | size                    | 4
                  | data-policy             | PARTITION
Eviction          | eviction-action         | overflow-to-disk
                  | eviction-algorithm      | lru-heap-percentage
Partition         | redundant-copies        | 2
                  | partition-resolver      | io.ampool.monarch.table.functions.MTableRangePartitionResolver
MTable Attributes | Column 0                | Name
                  | Column 1                | Gender
                  | Max Versions            | 4
                  | Persistence Enabled     | false
                  | Redundant Configuration | 2
                  | Table Type              | ORDERED_VERSIONED
                  | TotalNumOfSplits        | 113

The Immutable memory table can be described as:

mash>describe mtable --name=FTable1
............................................................
Name            : FTable1
Data Policy     : persistent partition
Hosting Members : Server1

Non-Default Attributes Shared By Hosting Members  

      Type       |           Name            | Value
---------------- | ------------------------- | -------------------------
Table            | data-policy               | PERSISTENT_PARTITION
                 | disk-store-name           | AMPOOL_DEFAULT_DISK_STORE
                 | size                      | 0
                 | entry-time-to-live.action | DESTROY
Eviction         | eviction-action           | overflow-to-tier
                 | eviction-algorithm        | lru-heap-percentage
Partition        | redundant-copies          | 1
                 | partition-resolver        | MPartitionResolver
Table Attributes | table-type                | IMMUTABLE
                 | block-size                | 1000
                 | number-of-blocks          | 0
                 | persistence-enabled       | true
                 | disk-write-policy         | ASYNCHRONOUS
Table Schema     | ID                        | BINARY
                 | __INSERTION_TIMESTAMP__   | LONG
Tier Attributes  | tier1-store               | DefaultLocalORCStore
                 | tier1-partition-interval  | 10 minutes
                 | tier1-time-to-expire      | -

REST Operations

Following table describes all the REST end-points and associated actions that can be performed on an Table:

HTTP Method Request URL Action Example Immutable Table Supported Ordered/Unordered Table Supported
PUT /ampool-api/v1/table/{table name}/{key1} Put a single key, value in Table /ampool-api/v1/table/MyTable1/4 No Yes
PUT /ampool-api/v1/table/{table name}/{key1},{key2},..{keyn} Put multiple keys,values in Table /ampool-api/v1/table/MyTable1/5%2C6 No Yes
HEAD /ampool-api/v1/table/{table name} Get total number of entries in Table /ampool-api/v1/table/MyTable1 No Yes
GET /ampool-api/v1/table/{table name}/{key1} Read data for a single key /ampool-api/v1/table/MyTable1/1 No Yes
GET /ampool-api/v1/table/{table name}/{key1},{key2},..{keyn} Read data for a multiple keys /ampool-api/v1/table/MyTable1/1%2C2%2C3 No Yes
POST /ampool-api/v1/table/{table name}/{scan} Scan all entries in a table /ampool-api/v1/table/MyTable1/{scan} Yes Yes
POST /ampool-api/v1/table/{table name}/{scan}?startkey={start key}&stopkey={stop key} Scan all entries in a table within range /ampool-api/v1/table/MyTable1/{scan}?startkey=1&stopkey=5 Yes Yes
POST /ampool-api/v1/table/{table name}/{scan}?filterType={filterType}&compareOp={compareOp}&columnName={columnName} Filter all entries in a table with the mentioned column name /ampool-api/v1/table/MyTable1/{scan}?filterType=SINGLE_COLUMN_NAME_FILTER&compareOp=EQUAL&columnName=INSERTION_TIMESTAMP Yes Yes
POST /ampool-api/v1/table/{table name}/{scan}?filterType={filterType}&compareOp={compareOp}&columnName={columnName}&columnValue={columnValue} Filter all entries in a table where the column name and column value match /ampool-api/v1/table/MyTable1/{scan}?filterType=SINGLE_COLUMN_VALUE_FILTER&compareOp=EQUAL&columnName=NAME&columnValue=Name1 Yes Yes
POST /ampool-api/v1/table/{table name}/filterlist?operator={operator} Execute multiple filters on a table.The filterlist should be passed as JSON body /ampool-api/v1/table/MyTable1/filterlist?operator=MUST_PASS_ALL Yes Yes
DELETE /ampool-api/v1/table/{table name}/{key} Delete data for a particular key from Table /ampool-api/v1/table/MyTable1/4 No Yes
DELETE /ampool-api/v1/table/{table name}/{key1},{key2},..{keyn} Delete data for multiple keys from Table /ampool-api/v1/table/MyTable1/1%2C2%2C3 No Yes
DELETE /ampool-api/v1/table/{table name} Delete entire Table /ampool-api/v1/table/MyTable1 Yes Yes
GET /ampool-api/v1/table/servers Fetch list of all REST enabled servers /ampool-api/v1/table/servers Yes Yes
PUT /ampool-api/v1/table/{table name}/append Append data in Immutable tables.Data to be appended is passed as json body /ampool-api/v1/table/MyTable1/append Yes No

Sample JSON to pass in case of one record put:

{
  "Name": "Avinash",
  "Gender": "Male"
}

Sample JSON array to be passed if multiple records are to be put:

[
 {
  "Name": "Manish",
  "Gender": "Male"
 },
 {
  "Name": "Deepak",
  "Gender": "Male"
 }
]

Sample JSON to pass in case of executing filterlist on a table:

[
 {
  "filterType": "SINGLE_COLUMN_NAME_FILTER",
  "compareOp": "EQUAL",
  "columnName": "DEPT",
  "columnValue": "Value1"
 },
 {
  "filterType": "SINGLE_COLUMN_VALUE_FILTER",
  "compareOp": "LESS",
  "columnName": "DOJ",
  "columnValue": "Value2"
 }
]

Note

In all of the above request urls, MyTable1 is an example table created through mash.