add postman collection

- plus documentation and examples
- the goal is to have new contributors be able to quickly test the api

tools/postman/podkrepi.bg.postman_collection.json

@@ -0,0 +1,132 @@
+{
+	"info": {
+		"_postman_id": "c5e2027f-85c2-41ba-ab2d-bebe0aa984bb",
+		"name": "podkrepi.bg",
+		"schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json"
+	},
+	"item": [
+		{
+			"name": "1 get token",
+			"event": [
+				{
+					"listen": "test",
+					"script": {
+						"exec": [
+							"var data = JSON.parse(responseBody);",
+							"",
+							"postman.setGlobalVariable(\"access_token\", data.accessToken);",
+							"postman.setGlobalVariable(\"refresh_token\", data.refreshToken);"
+						],
+						"type": "text/javascript",
+						"packages": {}
+					}
+				}
+			],
+			"request": {
+				"method": "POST",
+				"header": [],
+				"body": {
+					"mode": "raw",
+					"raw": "{\n    \"email\": \"{{user}}\",\n    \"password\": \"{{password}}\"\n}",
+					"options": {
+						"raw": {
+							"language": "json"
+						}
+					}
+				},
+				"url": {
+					"raw": "https://dev.podkrepi.bg/api/v1/login",
+					"protocol": "https",
+					"host": [
+						"dev",
+						"podkrepi",
+						"bg"
+					],
+					"path": [
+						"api",
+						"v1",
+						"login"
+					]
+				}
+			},
+			"response": []
+		},
+		{
+			"name": "User donations",
+			"protocolProfileBehavior": {
+				"disableBodyPruning": true
+			},
+			"request": {
+				"method": "GET",
+				"header": [],
+				"body": {
+					"mode": "raw",
+					"raw": "{\n    \"aggregations\": {\n        \"cloudTags\": {\n            \"aggregationType\": \"Terms\",\n            \"fieldName\": \"tags.key\",\n            \"subAggregations\": {\n                \"tagsValues\": {\n                    \"aggregationType\": \"Terms\",\n                    \"fieldName\": \"tags.value\"\n                }\n            }\n        }\n    }\n}",
+					"options": {
+						"raw": {
+							"language": "json"
+						}
+					}
+				},
+				"url": {
+					"raw": "https://dev.podkrepi.bg/api/v1/donation/user-donations",
+					"protocol": "https",
+					"host": [
+						"dev",
+						"podkrepi",
+						"bg"
+					],
+					"path": [
+						"api",
+						"v1",
+						"donation",
+						"user-donations"
+					]
+				}
+			},
+			"response": []
+		}
+	],
+	"auth": {
+		"type": "bearer",
+		"bearer": [
+			{
+				"key": "token",
+				"value": "{{access_token}}",
+				"type": "string"
+			}
+		]
+	},
+	"event": [
+		{
+			"listen": "prerequest",
+			"script": {
+				"type": "text/javascript",
+				"exec": [
+					""
+				]
+			}
+		},
+		{
+			"listen": "test",
+			"script": {
+				"type": "text/javascript",
+				"exec": [
+					""
+				]
+			}
+		}
+	],
+	"variable": [
+		{
+			"key": "aassdasdasda",
+			"value": "",
+			"type": "string"
+		},
+		{
+			"key": "asdasd",
+			"value": "asdasd",
+			"type": "string"
+		}
+	]
+}

tools/postman/readme.md

@@ -0,0 +1,23 @@
+# Podkrepi.bg postman collection
+
+## Getting started
+
+- Get the postman app 
+- Import the collection ![import image missing](./import.png)
+- Create an environment and add your username and password *ensure the password is a **secret** ![create an environment image missing](./env_demo.png)
+- Get the tokens via the `get token` request (it will use the postman env variables from previous step and store a access_token in postman global variables) ![authenticate image missing](./get_tokens.png)
+
+Done - now you can make authenticated requests: ![example for authenticated request](./user_donations_example.png)
+
+## Contributing to the collection
+
+The way to contribute is edit in a postman editor and then export it (Postman stores the collections in a db somewhere and there's no trivial way to have it store it where we need it - in the repo)
+
+- Edit in postman 
+
+![add new image missing](./add_new_via_duplicate.png)
+
+![edit](./user_donations_example.png)
+
+- Export and overwrite in the repo
+![export overwrite](./export.png)