Adding a postman collection with a generic environment file

The full API is modeled in postman and includes placeholders and variables that are taken from
an environment file, and also dynamically generated based on the API responses

docs/API-v1.md

@@ -1,17 +1,41 @@
 # Table of contents
-1. [API](#API)
-2. [Token operations](#token)
-3. [VM operations](#vmops)
-4. [Add disks](#adddisks)
-5. [VM snapshots](#vmsnapshots)
-6. [Status and metrics](#statusmetrics)
-7. [Pool configuration](#poolconfig)
-8. [Ondemand VM provisioning](#ondemandvm)
+1. [API](#API) 
+2. [Postman collection](#postman)
+3. [Token operations](#token)
+4. [VM operations](#vmops)
+5. [Add disks](#adddisks)
+6. [VM snapshots](#vmsnapshots)
+7. [Status and metrics](#statusmetrics)
+8. [Pool configuration](#poolconfig)
+9. [Ondemand VM provisioning](#ondemandvm)
 
 ### API <a name="API"></a>
 
 vmpooler provides a REST API for VM management.  The following examples use `curl` for communication.
 
+### Postman collection <a name="postman"></a>
+
+An example postman collection can be imported by [downloading it](postman/vmpooler FULL API.postman_collection.json) and the [generic environment file](postman/vmpooler generic.postman_environment.json)
+You will have to set the values in the environment file as per your local setup. The full API is modeled and some queries should be run in order, because we use the post-test script to save important returned values that are required by the other APIs.
+
+![postman](postman/postman_screenshot.png)
+
+You can string API requests in a specific order to run use cases for example:
+
+folder "create vm"/"ondemand" you can run
+
+Step 1) **ondemand vm** will use the _url, api_prefix, token and ondemand_pool_name_ from the env file and as a post-test script save the returned "request_id" in a collection variable
+
+Step 2) **check ondemand** will use the collection variable from Step 1) to query the API, and a post-test script will save the returned "hostname" in a collection variable, to be used in other APIs like 'Add additional disk' or 'Create a snapshot'
+
+folder "other vm requests"
+
+Step 2) **Create a snapshot** will use the "hostname" from the previous request
+
+folder "create vm"/"ondemand" you can finally run
+
+Step 3) **delete ondemand** will use the collection variable from Step 1) to delete the VM via the "request_id"
+
 #### Token operations <a name="token"></a>
 
 Token-based authentication can be used when requesting or modifying VMs.  The `/token` route can be used to create, query, or delete tokens.  See the provided YAML configuration example, [vmpooler.yaml.example](vmpooler.yaml.example), for information on configuring an authentication store to use when performing token operations.

docs/postman/vmpooler generic.postman_environment.json

@@ -0,0 +1,63 @@
+{
+	"id": "8c770a8b-db0d-4722-82d0-ec06712b9a44",
+	"name": "vmpooler generic",
+	"values": [
+		{
+			"key": "url",
+			"value": "https://myserver.com/",
+			"type": "default",
+			"enabled": true
+		},
+		{
+			"key": "token",
+			"value": "",
+			"type": "default",
+			"enabled": true
+		},
+		{
+			"key": "api_prefix",
+			"value": "api/v2",
+			"type": "default",
+			"enabled": true
+		},
+		{
+			"key": "ldap_user",
+			"value": "",
+			"type": "default",
+			"enabled": true
+		},
+		{
+			"key": "ldap_pass",
+			"value": "",
+			"type": "secret",
+			"enabled": true
+		},
+		{
+			"key": "ondemand_pool_name",
+			"value": "",
+			"type": "default",
+			"enabled": true
+		},
+		{
+			"key": "pooled_pool_name",
+			"value": "",
+			"type": "default",
+			"enabled": true
+		},
+		{
+			"key": "additional_disk_size",
+			"value": "8",
+			"type": "default",
+			"enabled": true
+		},
+		{
+			"key": "pool_management",
+			"value": "",
+			"type": "default",
+			"enabled": true
+		}
+	],
+	"_postman_variable_scope": "environment",
+	"_postman_exported_at": "2022-04-01T17:17:09.868Z",
+	"_postman_exported_using": "Postman/9.15.2"
+}