API v1 is not stable

[kvaps]

There are too many differences in v1 api, depends on execution method:

example for now I have three totally different outputs:

how it was
linstor 0.9.1; GIT-hash: 4622a21869e3342c65d91a897326b10da2c9803d:

# linstor -m --output-version v1 resource list -r one-vm-140-disk-2
[{"resource_states":[{"vlm_states":[{"disk_state":"UpToDate","vlm_nr":0}],"in_use":false,"rsc_name":"one-vm-140-disk-2","node_name":"m1c6"},{"vlm_states":[{"disk_state":"UpToDate","vlm_nr":0}],"in_use":false,"rsc_name":"one-vm-140-disk-2","node_name":"m1c4"}],"resources":[{"vlms":[{"layer_data":[{"layer_type":1,"drbd":{"meta_disk":"","device_path":"/dev/drbd1076","backing_device":"/dev/data/one-vm-140-disk-2_00000","allocated_size":1048840,"drbd_vlm_dfn":{"rsc_name_suffix":"one-vm-140-disk-2","vlm_nr":0,"minor":1076},"usable_size":1048576,"disk_state":""}},{"layer_type":3,"storage":{"device_path":"/dev/data/one-vm-140-disk-2_00000","vlm_nr":0,"provider_kind":3,"allocated_size":1052672,"usable_size":1052672,"lvm_thin":{},"disk_state":"[]"}}],"stor_pool_dfn_uuid":"27ba4c4a-267a-4734-ad2a-adabdd52251c","device_path":"/dev/drbd1076","vlm_nr":0,"stor_pool_name":"thindata","stor_pool_uuid":"b2d14861-dad6-440f-ba1c-2e380f7e81ea","stor_pool_props":[{"value":"data","key":"PrefNic"},{"value":"data","key":"StorDriver/LvmVg"},{"value":"thindata","key":"StorDriver/ThinPool"}],"vlm_uuid":"036e92f5-acfd-4edd-8d1d-f652a19154f2","vlm_dfn_uuid":"0ab6e37e-6a2b-4c79-b276-4fd83e870cee","usable_size":1048576,"provider_kind":3}],"node_uuid":"9095a451-42c0-4f26-b836-e9827704d5bc","uuid":"52642f25-d813-42c1-86df-cdce8e718680","node_name":"m1c4","layer_object":{"layer_type":1,"rsc_name_suffix":"","drbd":{"peers_slots":7,"drbd_rsc_dfn":{"peers_slots":7,"al_stripes":1,"down":false,"rsc_name_suffix":"one-vm-140-disk-2","secret":"Uunh6VZ3tUQJmcZy/DNa","transport_type":"IP","al_size":32,"port":7076},"al_stripes":1,"drbd_vlms":[{"meta_disk":"","device_path":"/dev/drbd1076","backing_device":"/dev/data/one-vm-140-disk-2_00000","allocated_size":1048840,"drbd_vlm_dfn":{"rsc_name_suffix":"one-vm-140-disk-2","vlm_nr":0,"minor":1076},"usable_size":1048576,"disk_state":""}],"node_id":1,"flags":0,"al_size":32},"id":308,"children":[{"layer_type":3,"rsc_name_suffix":"","storage":{"storage_vlms":[{"device_path":"/dev/data/one-vm-140-disk-2_00000","vlm_nr":0,"provider_kind":3,"allocated_size":1052672,"usable_size":1052672,"lvm_thin":{},"disk_state":"[]"}]},"id":309}]},"props":[{"value":"thindata","key":"AutoSelectedStorPoolName"},{"value":"thindata","key":"StorPoolName"}],"rsc_dfn_uuid":"b4ed5ad4-bd12-403c-bbcc-8cac42eabcf7","name":"one-vm-140-disk-2"},{"vlms":[{"layer_data":[{"layer_type":1,"drbd":{"meta_disk":"","device_path":"/dev/drbd1076","backing_device":"/dev/data/one-vm-140-disk-2_00000","allocated_size":1048840,"drbd_vlm_dfn":{"rsc_name_suffix":"one-vm-140-disk-2","vlm_nr":0,"minor":1076},"usable_size":1048576,"disk_state":""}},{"layer_type":3,"storage":{"device_path":"/dev/data/one-vm-140-disk-2_00000","vlm_nr":0,"provider_kind":3,"allocated_size":1052672,"usable_size":1052672,"lvm_thin":{},"disk_state":"[]"}}],"stor_pool_dfn_uuid":"27ba4c4a-267a-4734-ad2a-adabdd52251c","device_path":"/dev/drbd1076","vlm_nr":0,"stor_pool_name":"thindata","stor_pool_uuid":"06e96d14-6080-4c7d-b8d5-b379ea2fc7a4","stor_pool_props":[{"value":"data","key":"PrefNic"},{"value":"data","key":"StorDriver/LvmVg"},{"value":"thindata","key":"StorDriver/ThinPool"}],"vlm_uuid":"5a257264-5551-44a0-80f9-329152661aca","vlm_dfn_uuid":"0ab6e37e-6a2b-4c79-b276-4fd83e870cee","usable_size":1048576,"provider_kind":3}],"node_uuid":"1d8a837a-c6cd-4a41-8fba-bc5339824294","uuid":"44b28c91-fcd9-4621-814e-a919f3cd8a0b","node_name":"m1c6","layer_object":{"layer_type":1,"rsc_name_suffix":"","drbd":{"peers_slots":7,"drbd_rsc_dfn":{"peers_slots":7,"al_stripes":1,"down":false,"rsc_name_suffix":"one-vm-140-disk-2","secret":"Uunh6VZ3tUQJmcZy/DNa","transport_type":"IP","al_size":32,"port":7076},"al_stripes":1,"drbd_vlms":[{"meta_disk":"","device_path":"/dev/drbd1076","backing_device":"/dev/data/one-vm-140-disk-2_00000","allocated_size":1048840,"drbd_vlm_dfn":{"rsc_name_suffix":"one-vm-140-disk-2","vlm_nr":0,"minor":1076},"usable_size":1048576,"disk_state":""}],"node_id":0,"flags":0,"al_size":32},"id":298,"children":[{"layer_type":3,"rsc_name_suffix":"","storage":{"storage_vlms":[{"device_path":"/dev/data/one-vm-140-disk-2_00000","vlm_nr":0,"provider_kind":3,"allocated_size":1052672,"usable_size":1052672,"lvm_thin":{},"disk_state":"[]"}]},"id":299}]},"props":[{"value":"thindata","key":"AutoSelectedStorPoolName"},{"value":"thindata","key":"StorPoolName"}],"rsc_dfn_uuid":"b4ed5ad4-bd12-403c-bbcc-8cac42eabcf7","name":"one-vm-140-disk-2"}]}]

how it is now after upgrade
linstor 0.9.4; GIT-hash: ba74db93a88b9daa7f4ccbc2a5dc8fadd81f2da8

# linstor -m --output-version v1 resource list -r one-vm-140-disk-2
[[{"layer_object":{"drbd":{"drbd_resource_definition":{"al_stripes":1,"resource_name_suffix":"one-vm-140-disk-2","al_stripe_size_kib":32,"down":false,"secret":"Uunh6VZ3tUQJmcZy/DNa","transport_type":"IP","peer_slots":7,"port":7076},"al_stripes":1,"node_id":1,"drbd_volumes":[{"drbd_volume_definition":{"minor_number":1076,"resource_name_suffix":"one-vm-140-disk-2","volume_number":0},"device_path":"/dev/drbd1076","allocated_size_kib":1048840,"backing_device":"/dev/data/one-vm-140-disk-2_00000","usable_size_kib":1048576}],"al_size":32,"peer_slots":7},"type":"DRBD","children":[{"storage":{"storage_volumes":[{"usable_size_kib":1052672,"device_path":"/dev/data/one-vm-140-disk-2_00000","allocated_size_kib":1052672,"disk_state":"[]","volume_number":0}]},"type":"STORAGE"}]},"name":"one-vm-140-disk-2","node_name":"m1c4","state":{"in_use":false},"volumes":[{"device_path":"/dev/drbd1076","allocated_size_kib":52,"provider_kind":"LVM_THIN","layer_data_list":[{"data":{"drbd_volume_definition":{"minor_number":1076,"resource_name_suffix":"one-vm-140-disk-2","volume_number":0},"device_path":"/dev/drbd1076","allocated_size_kib":1048840,"backing_device":"/dev/data/one-vm-140-disk-2_00000","usable_size_kib":1048576},"type":"DRBD"},{"data":{"usable_size_kib":1052672,"device_path":"/dev/data/one-vm-140-disk-2_00000","allocated_size_kib":1052672,"disk_state":"[]","volume_number":0},"type":"STORAGE"}],"volume_number":0,"state":{"disk_state":"UpToDate"},"storage_pool_name":"thindata","uuid":"036e92f5-acfd-4edd-8d1d-f652a19154f2"}],"props":{"StorPoolName":"thindata","AutoSelectedStorPoolName":"thindata"},"uuid":"52642f25-d813-42c1-86df-cdce8e718680"},{"layer_object":{"drbd":{"drbd_resource_definition":{"al_stripes":1,"resource_name_suffix":"one-vm-140-disk-2","al_stripe_size_kib":32,"down":false,"secret":"Uunh6VZ3tUQJmcZy/DNa","transport_type":"IP","peer_slots":7,"port":7076},"al_stripes":1,"node_id":0,"drbd_volumes":[{"drbd_volume_definition":{"minor_number":1076,"resource_name_suffix":"one-vm-140-disk-2","volume_number":0},"device_path":"/dev/drbd1076","allocated_size_kib":1048840,"backing_device":"/dev/data/one-vm-140-disk-2_00000","usable_size_kib":1048576}],"al_size":32,"peer_slots":7},"type":"DRBD","children":[{"storage":{"storage_volumes":[{"usable_size_kib":1052672,"device_path":"/dev/data/one-vm-140-disk-2_00000","allocated_size_kib":1052672,"disk_state":"[]","volume_number":0}]},"type":"STORAGE"}]},"name":"one-vm-140-disk-2","node_name":"m1c6","state":{"in_use":false},"volumes":[{"device_path":"/dev/drbd1076","allocated_size_kib":52,"provider_kind":"LVM_THIN","layer_data_list":[{"data":{"drbd_volume_definition":{"minor_number":1076,"resource_name_suffix":"one-vm-140-disk-2","volume_number":0},"device_path":"/dev/drbd1076","allocated_size_kib":1048840,"backing_device":"/dev/data/one-vm-140-disk-2_00000","usable_size_kib":1048576},"type":"DRBD"},{"data":{"usable_size_kib":1052672,"device_path":"/dev/data/one-vm-140-disk-2_00000","allocated_size_kib":1052672,"disk_state":"[]","volume_number":0},"type":"STORAGE"}],"volume_number":0,"state":{"disk_state":"UpToDate"},"storage_pool_name":"thindata","uuid":"5a257264-5551-44a0-80f9-329152661aca"}],"props":{"StorPoolName":"thindata","AutoSelectedStorPoolName":"thindata"},"uuid":"44b28c91-fcd9-4621-814e-a919f3cd8a0b"}]]

even curl shows something different

# curl -s -X GET http://localhost:3370/v1/view/resources?resources=one-vm-140-disk-2 | jq -r 
[{"name":"one-vm-140-disk-2","node_name":"m1c4","props":{"AutoSelectedStorPoolName":"thindata","StorPoolName":"thindata"},"layer_object":{"children":[{"type":"STORAGE","storage":{"storage_volumes":[{"volume_number":0,"device_path":"/dev/data/one-vm-140-disk-2_00000","allocated_size_kib":1052672,"usable_size_kib":1052672,"disk_state":"[]"}]}}],"type":"DRBD","drbd":{"drbd_resource_definition":{"resource_name_suffix":"one-vm-140-disk-2","peer_slots":7,"al_stripes":1,"al_stripe_size_kib":32,"port":7076,"transport_type":"IP","secret":"Uunh6VZ3tUQJmcZy/DNa","down":false},"node_id":1,"peer_slots":7,"al_stripes":1,"al_size":32,"drbd_volumes":[{"drbd_volume_definition":{"resource_name_suffix":"one-vm-140-disk-2","volume_number":0,"minor_number":1076},"device_path":"/dev/drbd1076","backing_device":"/dev/data/one-vm-140-disk-2_00000","allocated_size_kib":1048840,"usable_size_kib":1048576}]}},"state":{"in_use":false},"volumes":[{"volume_number":0,"storage_pool_name":"thindata","provider_kind":"LVM_THIN","device_path":"/dev/drbd1076","allocated_size_kib":52,"state":{"disk_state":"UpToDate"},"layer_data_list":[{"type":"DRBD","data":{"drbd_volume_definition":{"resource_name_suffix":"one-vm-140-disk-2","volume_number":0,"minor_number":1076},"device_path":"/dev/drbd1076","backing_device":"/dev/data/one-vm-140-disk-2_00000","allocated_size_kib":1048840,"usable_size_kib":1048576}},{"type":"STORAGE","data":{"volume_number":0,"device_path":"/dev/data/one-vm-140-disk-2_00000","allocated_size_kib":1052672,"usable_size_kib":1052672,"disk_state":"[]"}}],"uuid":"036e92f5-acfd-4edd-8d1d-f652a19154f2"}],"uuid":"52642f25-d813-42c1-86df-cdce8e718680"},{"name":"one-vm-140-disk-2","node_name":"m1c6","props":{"AutoSelectedStorPoolName":"thindata","StorPoolName":"thindata"},"layer_object":{"children":[{"type":"STORAGE","storage":{"storage_volumes":[{"volume_number":0,"device_path":"/dev/data/one-vm-140-disk-2_00000","allocated_size_kib":1052672,"usable_size_kib":1052672,"disk_state":"[]"}]}}],"type":"DRBD","drbd":{"drbd_resource_definition":{"resource_name_suffix":"one-vm-140-disk-2","peer_slots":7,"al_stripes":1,"al_stripe_size_kib":32,"port":7076,"transport_type":"IP","secret":"Uunh6VZ3tUQJmcZy/DNa","down":false},"node_id":0,"peer_slots":7,"al_stripes":1,"al_size":32,"drbd_volumes":[{"drbd_volume_definition":{"resource_name_suffix":"one-vm-140-disk-2","volume_number":0,"minor_number":1076},"device_path":"/dev/drbd1076","backing_device":"/dev/data/one-vm-140-disk-2_00000","allocated_size_kib":1048840,"usable_size_kib":1048576}]}},"state":{"in_use":false},"volumes":[{"volume_number":0,"storage_pool_name":"thindata","provider_kind":"LVM_THIN","device_path":"/dev/drbd1076","allocated_size_kib":52,"state":{"disk_state":"UpToDate"},"layer_data_list":[{"type":"DRBD","data":{"drbd_volume_definition":{"resource_name_suffix":"one-vm-140-disk-2","volume_number":0,"minor_number":1076},"device_path":"/dev/drbd1076","backing_device":"/dev/data/one-vm-140-disk-2_00000","allocated_size_kib":1048840,"usable_size_kib":1048576}},{"type":"STORAGE","data":{"volume_number":0,"device_path":"/dev/data/one-vm-140-disk-2_00000","allocated_size_kib":1052672,"usable_size_kib":1052672,"disk_state":"[]"}}],"uuid":"5a257264-5551-44a0-80f9-329152661aca"}],"uuid":"44b28c91-fcd9-4621-814e-a919f3cd8a0b"}]

For get nodes list for the resource I need to query it by three different ways:

• in first case I was using: .[].resource_states[].node_name
• in second case I should query: .[][].node_name
• in third case I should query: .[].node_name

[rp-]

It wasn't our intention to go that wild with the v1 output,
this was a combination of the new layer system and afterwards the port to the REST-API.
I would say that with finishing porting the client to the REST-API(v0.9.4) the v1 should now also be stable as it just takes the data from the REST-API and outputs it now(in the worst case merges some data together).
And we do not plan to break(remove stuff from) the REST-API v1.

[kvaps]

OK, don't you plan to remove v0 in near future? Can I continue using it? - it meets my needs fully and it's compatible with old clients

Thank you

[rp-]

No the v0 output isn't planned to be removed, I wrote a extra layer to continue supporting it.
Of course it could happen at some point that it will not be possible to further support it, but for now I don't see any problem with this.
And if we need to remove it, we will announce it in advance.