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 <gparlakov@vmware.com>
Co-authored-by: Aleksandar Petkov <sashko506@gmail.com>

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/podkrepi.bg.postman_collection.json

@@ -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": "admin@podkrepi.bg",
+ "type": "string"
+ },
+ {
+ "key": "password",
+ "value": "$ecurePa33",
+ "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)