api-collections/README.md

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.