.gitignore

@@ -1,10 +1,16 @@
 # Secrets
 .env*
 !.env.template
+env.json
 
 # Dependencies
 node_modules
 
 # OS files
 .DS_Store
-Thumbs.db
+Thumbs.db
+
+# Automatically generated stuff
+autodocs/**/*
+
+*.temp

README.md

@@ -0,0 +1,50 @@
+# API collections
+
+This is the repository where most frequent HTTP requests are stored as Bruno collections.
+
+## Requisites
+
+A Windows-based OS with Powershell version >= 7.5.x
+
+One or more of:
+
+- Bruno desktop client (<https://www.usebruno.com/>)
+- VSCode (<https://code.visualstudio.com/>) with httpyac extension (<https://marketplace.visualstudio.com/items?itemName=anweber.vscode-httpyac>)
+
+## Preparation
+
+After having cloned the repository, move in the root folder and follow these steps:
+
+1. launch `setup-tools.bat`: this will check the current Powershell environment and try to install required modules
+2. launch `setup-json-environment.bat`: follow the instrucions to generate a base environment file starting form the structure defined in the `env.json.template` file; at the end of the process you should have a `env.json` file in the root folder containing base values and secrets
+
+### Bruno collections
+
+If you have Bruno installed and intend to use it as the main tool, also do the following:
+
+1. launch `update-bruno-environments.bat`: the script will generate an environment file named `.env` in each one of the Bruno collection folders, using the base environment generated in the previous step; this minimizes the manual intervention needed to insert secrets in those collections
+2. launch Bruno and open the base collection folder named `bruno`.
+
+### httpyac requests
+
+If you want to use VSCode with httpyac extension, also do the following:
+
+1. launch `generate-httpyac-requests.bat`: the script will create an `autodocs/httpyac` folder in the root of the project containing the same Bruno requests in a standard HTTP format which can be read by VSCode and/or httpyac extension
+2. launch `update-httpyac-environments.bat`: the script will generate an environment file named `.env` in each one of the generated folders, using the base environment generated in the previous step
+3. launch VSCode and open the base project folder: with the explorer navigate to the `autodocs/httpyac` folder and browse to the request you want to use
+
+## Development
+
+**The main development tool to be used to manage API requests is Bruno.**
+
+The autodocs folder and its subfolder is (and must be) excluded from versioning: if you need to persist updates of any kind, this must be done through Bruno, because modifications to anything under autodocs will be ignored.
+
+### Secrets management
+
+Be careful to not save secret values in Bruno requests or anywhere else!
+
+To make secret management easier in Bruno, in each collection there is an environment file called `.env.template`: this file contains the Bruno variables whose values must not be versioned with an empty value.
+
+**Note**: it's strongly suggested to use the `update-*-environments.bat` scripts to automatically generate the local environment files.
+
+If you want to proceed manually, you should just copy-paste the template file to a new `.env` file and insert the appropriate secret values; this works because only the `.env.template` file is versioned, while all other `.env*` files are excluded.

bruno/collections/ESSE3 Anagrafica API/environments/ESSE3 Anagrafica Pre-Prod #2.yml

@@ -1,6 +1,6 @@
-name: "ESSE3 Pre-Prod #2"
+name: "ESSE3 Anagrafica Pre-Prod #2"
 variables:
-  - name: rootUrl
+  - name: esse3apiRootUrl
     value: https://unipr2.esse3.pp.cineca.it
   - name: esse3apiUsername
     value: "{{process.env.esse3apiUsername}}"

bruno/collections/ESSE3 Anagrafica API/opencollection.yml

@@ -21,7 +21,7 @@ request:
     password: "{{esse3apiPassword}}"
   variables:
     - name: baseUrl
-      value: "{{rootUrl}}/e3rest/api/anagrafica-service-v2"
+      value: "{{esse3apiRootUrl}}/anagrafica-service-v2"
 bundled: false
 extensions:
   bruno: