add postman collection (#653)

* add postman collection

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

* chore: add link to readme

- update the postman collection to include the address as a variable

* default variables for local development

---------

Co-authored-by: Georgi Parlakov <[email protected]>
Co-authored-by: Aleksandar Petkov <[email protected]>

Author: 3 people

README.md

@@ -378,3 +378,7 @@ yarn prisma migrate deploy
 ```
 
 6. At this point you can re-deploy the `api-headless` deployment to trigger the standard flow of operation
+
+## Postman
+
+If you'd like to use Postman to query the API - see [postman doc](./tools/postman/readme.md)

tools/postman/add_new_via_duplicate.png

@@ -0,0 +1,106 @@
+{
+	"info": {
+		"name": "podkrepi.bg",
+		"schema": "https://schema.getpostman.com/json/collection/v2.0.0/collection.json"
+	},
+	"item": [
+		{
+			"name": "get token",
+			"event": [
+				{
+					"listen": "test",
+					"script": {
+						"exec": [
+							"// console.log('[INFO] Request: ', JSON.stringify(request))",
+							"var data = JSON.parse(responseBody);",
+							"// console.log('[info] response:', this)",
+							"postman.setGlobalVariable(\"access_token\", data.accessToken);",
+							"postman.setGlobalVariable(\"refresh_token\", data.refreshToken);"
+						],
+						"type": "text/javascript",
+						"packages": {}
+					}
+				}
+			],
+			"request": {
+				"auth": {
+					"type": "noauth"
+				},
+				"method": "POST",
+				"header": [
+					{
+						"key": "Content-Type",
+						"value": "application/json"
+					},
+					{
+						"key": "accept",
+						"value": "*/*"
+					}
+				],
+				"body": {
+					"mode": "raw",
+					"raw": "{\n    \"email\": \"{{user}}\",\n    \"password\": \"{{password}}\"\n}",
+					"options": {
+						"raw": {
+							"language": "json"
+						}
+					}
+				},
+				"url": "{{podkrepi_address}}/api/v1/login"
+			},
+			"response": []
+		},
+		{
+			"name": "User donations",
+			"request": {
+				"method": "GET",
+				"header": [],
+				"url": "{{podkrepi_address}}/api/v1/donation/user-donations"
+			},
+			"response": []
+		}
+	],
+	"auth": {
+		"type": "bearer",
+		"bearer": {
+			"token": "{{access_token}}"
+		}
+	},
+	"event": [
+		{
+			"listen": "prerequest",
+			"script": {
+				"type": "text/javascript",
+				"exec": [
+					""
+				]
+			}
+		},
+		{
+			"listen": "test",
+			"script": {
+				"type": "text/javascript",
+				"exec": [
+					""
+				]
+			}
+		}
+	],
+	"variable": [
+		{
+			"key": "podkrepi_address",
+			"value": "http://localhost:5010",
+			"type": "string"
+		},
+    {
+			"key": "user",
+			"value": "[email protected]",
+			"type": "string"
+		},
+    {
+			"key": "password",
+			"value": "$ecurePa33",
+			"type": "string"
+		}
+	]
+}

tools/postman/edit_example.png

@@ -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)