feat: add new API doc

.github/workflows/deploy-documentation.yml

@@ -0,0 +1,31 @@
+name: "Deploy documentation"
+
+on:
+  workflow_dispatch:
+  release:
+    types: [published]
+
+permissions:
+  contents: write
+
+jobs:
+  deploy-documentation:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Setup Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: 3.x
+
+      - name: Install MkDocs Material
+        run: |
+          pip install mkdocs-material mkdocs-static-i18n[material] mkdocs-open-in-new-tab
+
+      - name: Push documentation to gh-pages branch
+        working-directory: documentation
+        run: mkdocs gh-deploy

.gitignore

@@ -8,4 +8,5 @@ build/
 *private_api_key.json
 bin/
 obj/
-__pycache__/
+__pycache__/
+site/

documentation/README.md

@@ -0,0 +1,32 @@
+# MkDocs Local Setup
+
+This project uses [MkDocs](https://www.mkdocs.org/) with the following plugins:
+
+- Material theme
+- Static i18n (internationalization)
+- Open links in new tab
+
+---
+
+## Prerequisites
+
+Make sure you have:
+
+- Python 3.x
+- pip (or pip3)
+
+---
+
+## Install dependencies
+
+```bash
+pip install mkdocs-material mkdocs-static-i18n[material] mkdocs-open-in-new-tab
+```
+
+## Running the documentation locally
+
+```bash
+mkdocs serve
+```
+
+Once running, open your browser at [http://127.0.0.1:8000](http://127.0.0.1:8000)

documentation/docs/en/authentication.md

@@ -0,0 +1,36 @@
+### Base URL
+
+<code>
+https://api.forms-formulaires.alpha.canada.ca/v1/...
+</code>
+
+
+> _Note: You may need to use a cloud provider such as Microsoft Azure or Amazon Web Services (AWS), to be able to access the endpoint._
+
+### How authentication works
+
+The GC Forms API leverages an OAuth 2.0 Signed JSON Web Token ([JWT](https://jwt.io/)) flow with a self-hosted Identity provider (IDP), Zitadel, to establish machine-to-machine authentication in a safe and secure way for the API endpoint. 
+
+Authentication is done through an opaque token, with basic authorization handled via the user profile and the requested form ID. The OAuth server provides a short-lived access token that can be used to make API requests by verifying the client’s JWT that has been signed with a private key and includes their client ID. This access token is valid for 30 minutes.
+
+The API requires authentication with a Government of Canada email, an associated **formID**, a JWT signed with a **Private key** and verified using a **Public key** with the IDP. This token contains a claim to specify the form ID from which it is associated.
+
+### Integration examples
+
+Once you’ve created a form, you can submit mock form submissions to simulate an active form and be able to test generating an access token. 
+
+Use these examples as a reference to generate access tokens in your preferred programming language:
+- [.NET / C#](https://github.com/cds-snc/forms-api/blob/main/examples/dotnet/AccessTokenGenerator.cs)
+- [Node.JS / Typescript](https://github.com/cds-snc/forms-api/blob/main/examples/nodejs/accessTokenGenerator.ts)
+- [Python](https://github.com/cds-snc/forms-api/blob/main/examples/python/access_token_generator.py)
+- [Bash /Curl](https://github.com/cds-snc/forms-api/blob/main/examples/bash/get_access_token.sh)
+
+### Authorization header
+
+Use this header for each API request to verify it’s you:
+<code>
+<br>
+<br> curl \
+<br>   --request GET "$FORMS_URL" \
+<br>   --header "Authorization: Bearer $ACCESS_TOKEN"
+</code>

documentation/docs/en/getting-started.md

@@ -0,0 +1,13 @@
+### Overview
+
+The purpose of this API is to allow you to securely and reliably retrieve form submissions directly from an API endpoint. This should help alleviate the effort associated for very high volumes of form submissions. So, rather than having to manually download and sign off on the removal of responses to confirm their retrieval from the database, the API will automate the workflow with systems that talk to each other and exchange data. 
+
+### What you will need
+  - A [GC Forms account](https://articles.alpha.canada.ca/forms-formulaires/)
+  - A draft form (Unclassified, Protected A, or Protected B)
+  - An API key (that you generate in Settings > API integration).
+  - A few “mock” responses submitted to the form
+  - A target system where you plan on receiving form submission data
+  - Infrastructure development resources who can craft HTTP requests to reach the API. _No infrastructure development capabilities available? This first version of the API might not be ready for you just yet._
+
+> **IMPORTANT: You must keep this API key secure as it is used to authenticate API requests and could be used to access protected data. Use encrypted email if you must share it with a developer team member to set up the integration.**

documentation/docs/en/getting-support.md

@@ -0,0 +1,3 @@
+We’re open to all questions and welcome any feedback you might have to help us improve. You can get in touch with our team directly with any questions or needs for technical support, by filling out the [Support form](https://forms-formulaires.alpha.canada.ca/en/support).
+
+> Please include your name, email address, the form ID, response IDs (if relevant), and a description of the problem. We'll do our best to be in touch within 2 business days.

documentation/docs/en/index.md

@@ -0,0 +1,5 @@
+### Welcome
+
+Welcome to the technical documentation for the GC Forms application programming interface (API). This site is for developers who want to use the GC Forms API to retrieve form submission data programmatically into their department’s web application or back-office system.
+
+Here you'll find how to set up an initial integration to securely retrieve form submissions. We appreciate your open and honest feedback to help us improve GC Forms and shape the future of this product.