docs.storageos.com - API webpage
================================

TODO: Openind paragraph of text has multiple typos and grammar errors. Need to fix this. [DONE]
TODO: hard to see the text for the example JSON post messages on the RHS. Possibly a Safari thing?!
TODO: some of the JSON examples on the RHS of the webpage look wrong?! Safari issue?
TODO: docs should use all lowercase for consistency?

VOLUMES
=======

List volumes
============

===============================================================================

SCENARIO:
- Fresh start - 3 node cluster - no provisioned volumes.
- No auth username and password supplied.
-->
GET: 172.28.128.3:5705/v1/namespaces/default/volumes
<--
401 UNAUTHORIZED
Unauthorized
-EXPECTED-

===============================================================================

SCENARIO:
- Fresh start - 3 node cluster - no provisioned volumes.
- bad namespace used.
-->
GET: 172.28.128.3:5705/v1/namespaces/defaultxxx/volumes
<--
404 NOT FOUND
JSON: "message": "Not found"
Unauthorized
-EXPECTED-

===============================================================================

SCENARIO:
- Fresh start - 3 node cluster - no provisioned volumes.
- Dropped the {namespace} path parameter.
-->
GET: 172.28.128.3:5705/v1/namespaces/volumes
<--
404 NOT FOUND
Not found
-EXPECTED-

===============================================================================

SCENARIO:
- Fresh start - 3 node cluster - no provisioned volumes.
- One volume has already been created successfully.
-->
GET: 172.28.128.3:5705/v1/namespaces/volumes
<--
JSON: valid volume/inode state data (note: this time the master data is correctly set i.e. has non-zero data)
-EXPECTED-

===============================================================================

SCENARIO:
- 3 node cluster - single provisioned volumes.
-->
GET: 172.28.128.3:5705/v1/namespaces/volumes
<--
JSON: valid volume/inode state data.
-EXPECTED-

===============================================================================

SCENARIO:
- 3 node cluster - multiple provisioned volumes.
-->
GET: 172.28.128.3:5705/v1/namespaces/volumes
<--
JSON: an array of valid volume/inode state data for multiple volumes.
-EXPECTED-

===============================================================================

SCENARIO:
- 3 node cluster - multiple provisioned volumes.
- labelSelector
-->
GET: 172.28.128.3:5705/v1/namespaces/volumes?labelSelector=com.example.some-label
<--
JSON: an array of valid volume/inode state data for multiple volumes.
-FAILED- doesn't appear to filter.
XXX:

===============================================================================

SCENARIO:
- 3 node cluster - multiple provisioned volumes.
- fieldSelector
-->
GET: 172.28.128.3:5705/v1/namespaces/volumes?fieldSelector=<????>
<--
JSON: an array of valid volume/inode state data for multiple volumes.
-UNTESTED- don't know what to put for fieldSelector's value??
XXX:

===============================================================================


Create volumes
==============

===============================================================================

SCENARIO:
- Fresh start - 3 node cluster - no provisioned volumes.
-->
POST: 172.28.128.3:5705/v1/namespaces/default/volumes
BODY (JSON):
{
    "name": "redis-vol01",
    "size": 1
}
<--
JSON: valid volume/inode state data (note: master data is all zerod at this point)
-EXPECTED-

===============================================================================

SCENARIO:
- Fresh start - 3 node cluster - with a single volume already provisioned.
-->
POST: 172.28.128.3:5705/v1/namespaces/default/volumes
BODY (JSON):
{
    "name": "redis-vol02",
    "size": 2
}
<--
JSON: valid volume/inode state data (note: master data is all zerod at this point)
-EXPECTED-

===============================================================================

SCENARIO:
- Fresh start - 3 node cluster - with two volumes already provisioned.
- Now trying to provision a third with bad JSON body -- using CAPITAL first letters for Name and Size.
-->
POST: 172.28.128.3:5705/v1/namespaces/default/volumes
BODY (JSON):
{
    "Name": "redis-vol03",
    "Size": 3
}
<--
JSON: valid volume/inode state data (note: master data is all zerod at this point)
-EXPECTED- WORKS?! This implies that the JSON keys are non-case sensitive.

===============================================================================

SCENARIO:
- Fresh start - 3 node cluster - with two volumes already provisioned.
- Now trying to provision a third with bad JSON body -- using all CAPITALS for NAME and SIZE.
-->
POST: 172.28.128.3:5705/v1/namespaces/default/volumes
BODY (JSON):
{
    "NAME": "redis-vol03",
    "SIZE": 3
}
<--
JSON: valid volume/inode state data (note: master data is all zerod at this point)
-EXPECTED- WORKS?! This implies that the JSON keys are non-case sensitive.

===============================================================================

SCENARIO:
- Fresh start - 3 node cluster - with two volumes already provisioned.
- Now trying to provision a volume with bad JSON body -- missing size parameter.
-->
POST: 172.28.128.3:5705/v1/namespaces/default/volumes
BODY (JSON):
{
    "name": "redis-vol05",
}
<--
JSON: valid volume/inode state data (note: master data is all zerod at this point)
-EXPECTED- Size defaults to 10
TODO: update documentation to reflect this. [DONE]

===============================================================================

SCENARIO:
- Fresh start - 3 node cluster - with two volumes already provisioned.
- Now trying to provision a volume with bad JSON body -- with size (0) parameter.
-->
POST: 172.28.128.3:5705/v1/namespaces/default/volumes
BODY (JSON):
{
    "name": "redis-vol05",
    "size" 0
}
<--
JSON: valid volume/inode state data (note: master data is all zerod at this point)
-EXPECTED- Size defaults to 10
TODO: update documentation to reflect this. [DONE]

===============================================================================

SCENARIO:
- Fresh start - 3 node cluster - with two volumes already provisioned.
- Now trying to provision a volume with bad JSON body -- empty JSON object.
-->
POST: 172.28.128.3:5705/v1/namespaces/default/volumes
BODY (JSON):
{
}
<--
volume name not valid
-EXPECTED-

===============================================================================

SCENARIO:
- Fresh start - 3 node cluster - with two volumes already provisioned.
- Now trying to provision a volume with no JSON body -- empty
-->
POST: 172.28.128.3:5705/v1/namespaces/default/volumes
BODY (JSON):
<--
JSON: "message": "EOF"
-EXPECTED-

===============================================================================

SCENARIO:
- 3 node cluster.
- Now trying to provision a volume with no JSON name field
-->
POST: 172.28.128.3:5705/v1/namespaces/default/volumes
BODY (JSON):
{
    "size": 2
}
<--
volume name not valid
-EXPECTED-

===============================================================================

SCENARIO:
- 3 node cluster.
- Now trying to provision a volume with no JSON name field
-->
POST: 172.28.128.3:5705/v1/namespaces/default/volumes
BODY (JSON):
{
    "size": 2
}
<--
volume name not valid
-EXPECTED-

===============================================================================

SCENARIO:
- 3 node cluster.
- Now trying to provision a volume with same name as one that has already been provisioned.
-->
POST: 172.28.128.3:5705/v1/namespaces/default/volumes
BODY (JSON):
{
    "name": "myvol1",
    "size": 5
}
<--
volume with name 'myvol1' already exists
-EXPECTED-

===============================================================================

SCENARIO:
- 3 node cluster.
- Now trying to provision a volume with pool name.
-->
POST: 172.28.128.3:5705/v1/namespaces/default/volumes
BODY (JSON):
{
    "name": "myvol1",
    "size": 5,
    "pool": "mypool1"
}
<--
JSON: valid volume/inode state data with correct pool field.
-EXPECTED-

===============================================================================

SCENARIO:
- 3 node cluster.
- Now trying to provision a volume with optional labels.
-->
POST: 172.28.128.3:5705/v1/namespaces/default/volumes
BODY (JSON):
{
  "Name": "vol01",
  "Size": 5,
  "Labels": {
    "com.example.some-label": "some-value",
    "com.example.some-other-label": "some-other-value"
  }
}
<--
JSON: valid volume/inode state data with correct labels.
-EXPECTED-

===============================================================================


Get volumes
===========

===============================================================================

SCENARIO:
- Fresh start - 3 node cluster - N provisioned volumes.
- Get by name.
-->
POST: 172.28.128.3:5705/v1/namespaces/default/volumes/redis-vol03
<--
JSON: correct volume/inode state data.
-EXPECTED-

===============================================================================

SCENARIO:
- Fresh start - 3 node cluster - N provisioned volumes.
- Get by id.
-->
POST: 172.28.128.3:5705/v1/namespaces/default/volumes/270c1fc2-c578-77f8-2d7c-1515e626b6c3
<--
JSON: correct volume/inode state data.
-EXPECTED-

===============================================================================

SCENARIO:
- Fresh start - 3 node cluster - N provisioned volumes.
- Passing bad name/id.
-->
POST: 172.28.128.3:5705/v1/namespaces/default/volumes/this-volume-does-not-exist
<--
Not Found
-EXPECTED-

===============================================================================


Update volumes
==============

===============================================================================

SCENARIO:
- Fresh start - 3 node cluster - N provisioned volumes.
- Update a volume
-->
PUT: 172.28.128.3:5705/v1/namespaces/default/volumes/redis-vol03
JSON:
{
	"Description": "string",
	"Size": 5,
	"Labels": {
	"property1": "string",
	"property2": "string"
	}
}
<--
200 OK
-EXPECTED-

===============================================================================

SCENARIO:
- Fresh start - 3 node cluster - N provisioned volumes.
- Update a volume, trying with bad JSON, missing opening curly brace!
-->
PUT: 172.28.128.3:5705/v1/namespaces/default/volumes/redis-vol03
JSON:
	"Description": "string",
	"Size": 5,
	"Labels": {
	"property1": "string",
	"property2": "string"
	}
}
<--
400 BAD REQUEST
Request decode failed: json: cannot unmarshal string into Go value of type types.Volume
-EXPECTED-

===============================================================================

SCENARIO:
- Fresh start - 3 node cluster - N provisioned volumes.
- Update a volume, trying with size (0) and same property1 and new property3.
-->
PUT: 172.28.128.3:5705/v1/namespaces/default/volumes/redis-vol03
JSON:
{
	"Description": "string",
	"Size": 0,
	"Labels": {
	"property1": "string",
	"property3": "string3"
	}
}
<--
200 OK
-NOT EXPECTED-
The old labels are completely overwritten anew (hence the previous property2 label is not present). I assume this is the desired behaviour?!
TODO: However size is now zero?! Check this is ok! Probably not; since the Create volume API defaults to 10 when 0 is passed or omitted.
XXX:

===============================================================================

SCENARIO:
- Fresh start - 3 node cluster - N provisioned volumes.
- Update a volume, trying with omitting size parameter
-->
PUT: 172.28.128.3:5705/v1/namespaces/default/volumes/volxyz
JSON:
{
	"Description": "string",
	"Labels": {
	"property1": "string",
	"property3": "string3"
	}
}
<--
200 OK
-NOT EXPECTED-
XXX: size is now zero when not passing size in JSON body of PUT request.

===============================================================================

SCENARIO:
- Fresh start - 3 node cluster - N provisioned volumes.
- Update a volume, trying with omitting description parameter
-->
PUT: 172.28.128.3:5705/v1/namespaces/default/volumes/volxyz
JSON:
{
	"Labels": {
	"property1": "string",
	"property3": "string3"
	}
}
<--
200 OK
-NOT EXPECTED-
XXX: description string is empty i.e. "" when not passing description in JSON body of PUT request.
The above implies that the update volume PUT request receiving side interprets missing update parameters as their null-value counterparts. So it's is not possible to update just specific parameters.

===============================================================================


Delete volumes
==============

===============================================================================

SCENARIO:
- Fresh start - 3 node cluster - N provisioned volumes.
- Delete a volume. But not specifying a name in the path.
-->
DELETE: 172.28.128.3:5705/v1/namespaces/default/volumes
<--
404 NOT FOUND
404 page not found
-EXPECTED-

===============================================================================

SCENARIO:
- Fresh start - 3 node cluster - N provisioned volumes.
- Delete a volume by specifying the volume's name.
-->
DELETE: 172.28.128.3:5705/v1/namespaces/default/volumes/redis-vol05
<--
200 OK
-EXPECTED-
TODO: But when doing a GET ~volumes/redis-vol05 it is still present So DELETE volumes doesn't appear to be working.

===============================================================================

SCENARIO:
- Fresh start - 3 node cluster - N provisioned volumes.
- Delete a volume by specifying the volume's id.
-->
DELETE: 172.28.128.3:5705/v1/namespaces/default/volumes/5233930b-b77f-2863-0895-b1eb5d73ec45
<--
200 OK
-EXPECTED-
TODO: But when doing a GET ~volumes/5233930b-b77f-2863-0895-b1eb5d73ec45 it is still present So DELETE volumes doesn't appear to be working.

===============================================================================

SCENARIO:
- Fresh start - 3 node cluster - N provisioned volumes.
- Trying to delete a mounted volume
-->
DELETE: 172.28.128.3:5705/v1/namespaces/default/volumes/volxyz
<--
412 PRECONDITION FAILED
cannot delete mounted volume
-EXPECTED-
TODO: seems correct, this hints that the mount is working which is in conflict with my observation below for MOUNT and UNMOUNT. Q. Is it checking the mount status via the OS, or by some other means i.e. locally cached value?

===============================================================================

SCENARIO:
- Fresh start - 3 node cluster - N provisioned volumes.
- Trying to delete a unmounted volume
-->
DELETE: 172.28.128.3:5705/v1/namespaces/default/volumes/volxyz
<--
200 OK
-EXPECTED-

===============================================================================


Mount volumes
=============

===============================================================================

SCENARIO:
- Fresh start - 3 node cluster - N provisioned volumes.
- Mount a volume. But not specifying a name in the path.
-->
POST: 172.28.128.3:5705/v1/namespaces/default/volumes/redis-vol02/mount
JSON:
{
	"client": "storageos-1-68228"
}
<--
200 OK
-EXPECTED-
NOTE: in the JSON response, no_of_mounts does increase correctly by one each time. And mounted is set to true correctly.
TODO: although this worked, the documentation doesn't give the proper JSON request body.
TODO: no_of_mounts is still 0 in /var/lib/storageos/state/inode/178101 (should increase by 1 for every mount.)
BUG^
TODO: Also not sure if really mounted this volume, since running the storageos cli e.g.:
$ ./storageos volume ls
The MOUNTED BY column is always empty ?? Either cli doesn't show this info, yet. Or the volume isn't mounted.
===============================================================================


Unmount volumes
===============

===============================================================================

SCENARIO:
- Fresh start - 3 node cluster - N provisioned volumes.
- Mount a volume. But not specifying a name in the path.
-->
POST: 172.28.128.3:5705/v1/namespaces/default/volumes/redis-vol02/unmount
JSON:
{
	"can-be-anything": "storageos-1-68228"
}
<--
200 OK
-EXPECTED-
NOTE: in the JSON response, mounted is set back to false correctly.
TODO: although this worked, the documentation doesn't give the proper JSON request body. The

===============================================================================


POOLS
=====

List pools
==========

===============================================================================

SCENARIO:
- Fresh start - 3 node cluster.
- No auth username and password supplied.
-->
GET: 172.28.128.3:5705/v1/pools
<--
401 UNAUTHORIZED
Unauthorized
-EXPECTED-

===============================================================================

SCENARIO:
- Fresh start - 3 node cluster. No pools.
-->
GET: 172.28.128.3:5705/v1/pools
<--
200 OK
JSON: an array of pools.
-EXPECTED-

===============================================================================


Create pools
============

===============================================================================

SCENARIO:
- Fresh start - 3 node cluster.
-->
POST: 172.28.128.3:5705/v1/volumes
BODY (JSON):
{
	"name": "mypool1"
}
<--
201 CREATED
JSON: valid pool data.
-EXPECTED-

===============================================================================

SCENARIO:
- Fresh start - 3 node cluster.
- Trying to create a pool with the same name as another already created.
-->
POST: 172.28.128.3:5705/v1/volumes
BODY (JSON):
{
	"name": "mypool1"
}
<--
409 CONFLICT
Pool with name 'mypool1' already exists
-EXPECTED-

===============================================================================

SCENARIO:
- Fresh start - 3 node cluster.
- Trying to create a pool with the same name as another already created.
-->
POST: 172.28.128.3:5705/v1/volumes
BODY (JSON):
{
	"name": "mypool2",
	"description": "hello world!"
}
<--
201 CREATED
JSON: valid pool data.
-EXPECTED-

===============================================================================

SCENARIO:
- Fresh start - 3 node cluster.
- Trying to create a pool with the defaultDriver string set.
-->
POST: 172.28.128.3:5705/v1/volumes
BODY (JSON):
{
	"name": "mypool6",
	"description": "hello world again!",
	"default": true,
	"defautDriver": "I'm the default driver :)"
}
<--
201 CREATED
JSON: Is correct for the most part, but defaultDriver is an empty string??
-NOT EXPECTED-
XXX

===============================================================================


Get Pools
=========

===============================================================================

SCENARIO:
- Fresh start - 3 node cluster - N provisioned volumes.
- Get by name.
-->
POST: 172.28.128.3:5705/v1/pools/mypool1
<--
200 OK
JSON: correct pool data.
-EXPECTED-

===============================================================================

SCENARIO:
- Fresh start - 3 node cluster - N provisioned volumes.
- Get by id.
-->
POST: 172.28.128.3:5705/v1/pools/ea477d68-8193-1179-d889-aa6ea8797082
<--
200 OK
JSON: correct pool data.
-EXPECTED-

===============================================================================

SCENARIO:
- Fresh start - 3 node cluster - N provisioned volumes.
- Get by name. Try passing invalid name.
-->
POST: 172.28.128.3:5705/v1/pools/mypool1xxx
<--
404 NOT FOUND
Not Found
-EXPECTED-

===============================================================================


Delete Pools
============

===============================================================================

SCENARIO:
- Fresh start - 3 node cluster - N provisioned pools.
- Trying to delete without specifying name etc. in the path.
-->
POST: 172.28.128.3:5705/v1/pools
<--
404 NOT FOUND
404 page not found
-EXPECTED-

===============================================================================

SCENARIO:
- Fresh start - 3 node cluster - N provisioned pools.
- Delete by name.
-->
POST: 172.28.128.3:5705/v1/pools/mypool2
<--
200 OK
-EXPECTED-

===============================================================================

SCENARIO:
- Fresh start - 3 node cluster - N provisioned pools.
- Delete by id.
-->
POST: 172.28.128.3:5705/v1/pools/9a10bbfe-eaaa-af3c-2a9b-d78e0790efb4
<--
200 OK
-EXPECTED-

===============================================================================
