# 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.
