ImmuxDB http api changes

[poppindouble]

Currently we have totally 10 http APIs exposed in ImmuxDB, here are the APIs:

Get:

get_chain_name: http://{host}/{grouping}?chain
unconditional select: http://{host}/{grouping}?select
inspect: http://{host}/{grouping}/{id}?inspect
get_by_id: http://{host}/{grouping}/{id}

Put:

revert_by_id: http://{host}/{grouping}/{id}?revert={height}
revert_all_query: http://{host}/{grouping}/{id}?revert_all={height}
switch_chain: http://{host}/?chain={chain_name}
create_index: http://{host}/{grouping}?index={property_name}
set_batch_units: http://{host}/{grouping}/internal_api_target_id_identifier, body: {units}
set_unit: http://{host}/{grouping}/{id}, body: {unit}

Current APIs we have is a bit ad hoc, I went through the codebase, and here is the new APIs I want to introduced.

Get:

get chain: http://{host}/chain

unconditional select: http://{host}/{chain_name}/{grouping}/units

fetch unit by id: http://{host}/{chain_name}/{grouping}/units/{id}

fetch units by name property: http://{host}/{chain_name}/{grouping}/units?property_name={property_name}&unit_content_str={unit_content_str}

inspect unit: http://{host}/{chain_name}/{grouping}/units/{id}/journal

Put:

set chain: http://{host}/chain 
body: chain_name

add unit to grouping: http://{host}/{chain_name}/{grouping}/units/{id}
body: unit_content

set batch units: http://{host}/{chain_name}/{grouping}/units
body: units

revert single unit: http://{host}/{chain_name}/{grouping}/units/{id}/journal
body: height

revert all: http://{host}/{chain_name}/{grouping}/units/journal
body: height

create index: http://{host}/{chain_name}/{grouping}/indexes
body: property_name

I am thinking the body of put method is gonna be a json string, so when we received on the server side, we can use serde to parse it into a json. I am working on it now.

[poppindouble]

@blaesus let me know if it is ok for this set of api

[blaesus]

@poppindouble
I think the design is (1) inconsistent and (2) not following REST principles.

For example:
GET /{host}/ is the getting chain (name?), but GET /{host}/{grouping} is not about grouping per se, but getting units in the grouping, then PUT /{host}/{grouping} is not about updating these units either, but reverting them.

I don't even know how revert_all is differentiated from create_index, as they are both PUT /{host}/{grouping}/.

Suppose I say this:

PUT /grouping

1

Does this revert all units in grouping to height 1, or does it create an index under the property 1?

[poppindouble]

I agree, the design is pretty bad, it is not consistent with the meaning of url.

for revert_all and create_index, their url is the same, but the body of the url is different:

I am currently using json to pass between client and server.

for revert_all, the json body is

chain_height: height

for create_index, the json body is

property_name: property_name

I was using the fields in json to judge whether it is revert_all or create_index. but you are right, it is really inconsistent with what the url means

[blaesus]

Model

Basic: db/chain/grouping/unit/version
Names: {host_ip}/{chain_name}/{grouping_label}/{unit_id}/{height}

Methods

GET for retrieving information (and does not mutate state).
POST for updating information (which is not idempotent).
PUT for updating information (which is idempotent – it can be executing multiple times with the same outcome).

1. DB-level

Get name of current chain

GET {host_ip}/?current_chain

Switch chain

PUT {host_ip}/?current_chain
new_chain_name

2. Chain-level

(none)

3. Grouping-level

Create index of one property name

PUT {host_ip}/{chain_name}/{grouping_label}/?indices&by_kv&{property_name}={content}

4. Unit-level

Insert one unit by ID

POST {host_ip}/{chain_name}/{grouping_label}/{unit_id}
unit_content

Insert many units by ID

POST {host_ip}/{chain_name}/{grouping_label}
unit_id_1
unit_content_1
unit_id_2
unit_content_2
...

Select by ID

GET {host_ip}/{chain_name}/{grouping_label}/{unit_id}

Select unconditionally

GET {host_ip}/{chain_name}/{grouping_label}/_all

Select by one NameProperty

GET {host_ip}/{chain_name}/{grouping_label}/?by_kv&{property_name}={unit_content}

Select by multiple NamePropertys (not implemented)

GET {host_ip}/{chain_name}/{grouping_label}/?by_kv&{property_name_1}={unit_content_1}&{property_name_2}={unit_content_2}

Select by JSCode (not implemented)

GET {host_ip}/{chain_name}/{grouping_label}/?by_js_filter={js_code}

5. Version-level

Select at height by ID

GET {host_ip}/{chain_name}/{grouping_label}/{unit_id}/{height}

Revert one to height by ID

POST {host_ip}/{chain_name}/{grouping_label}/{unit_id}/?revert_to={target-height}

Revert many to height by IDs

POST {host_ip}/{chain_name}/{grouping_label}/_list/?revert_to={target_height}
id_1
id_2
id_3
...

Revert all to height

POST {host_ip}/{chain_name}/{grouping_label}/_all/?revert_to={target_height}

Inspect by ID

GET {host_ip}/{chain_name}/{grouping_label}/{unit_id}/_all

[poppindouble]

I am on it.

[poppindouble]

I have one question regarding to the design:

Create index of one property name
PUT
{host_ip}/{chain_name}/{grouping_label}/?indices&by_kv&{property_name}={content}

I am not sure what the content here means, I think to create an index, we just need {property_name}, right?

so I was thinking the api should be:

Create index of one property name
PUT
{host_ip}/{chain_name}/{grouping_label}/?indices&by_kv&property_name={property_name}

Also I don't think we have this function yet in our command system.
Select at height by ID
GET {host_ip}/{chain_name}/{grouping_label}/{unit_id}/{height}

correct me if I am wrong

[blaesus]

@poppindouble Correct, {content} is not necessary nor desirable.