### Full Form Authentication Example

Source: https://github.com/badgerati/pode/blob/develop/docs/Tutorials/Authentication/Methods/Form.md

A comprehensive example demonstrating setup, validation of user credentials, and route-specific authentication.

```powershell
Start-PodeServer {
    Add-PodeEndpoint -Address * -Port 8080 -Protocol Http

    # setup form authentication to validate a user
    New-PodeAuthScheme -Form | Add-PodeAuth -Name 'Login' -Sessionless -ScriptBlock {
        param($username, $password)

        # here you'd check a real user storage, this is just for example
        if ($username -eq 'morty' -and $password -eq 'pickle') {
            return @{ 'user' = @{
                'ID' ='M0R7Y302'
                'Name' = 'Morty';
                'Type' = 'Human';
            } }
        }

        return $null
    }

    # check the request on this route against the authentication
    Add-PodeRoute -Method Get -Path '/cpu' -Authentication 'Login' -ScriptBlock {
        Write-PodeJsonResponse -Value @{ 'cpu' = 82 }
    }

    # this route will not be validated against the authentication
    Add-PodeRoute -Method Get -Path '/memory' -ScriptBlock {
        Write-PodeJsonResponse -Value @{ 'memory' = 14 }
    }
}
```

--------------------------------

### Run Pode HelloWorld Example

Source: https://github.com/badgerati/pode/blob/develop/docs/Getting-Started/GitHubCodespace.md

Execute this script in the PowerShell terminal within your GitHub Codespace to start the Pode web server for the HelloWorld example.

```powershell
./examples/HelloWorld/HelloWorld.ps1
```

--------------------------------

### Full Client Certificate Authentication Example

Source: https://github.com/badgerati/pode/blob/develop/docs/Tutorials/Authentication/Methods/ClientCertificate.md

A complete example demonstrating setup, validation of a client certificate's thumbprint, and applying authentication to specific routes.

```powershell
Start-PodeServer {
    Add-PodeEndpoint -Address * -Port 8443 -Protocol Https -SelfSigned -AllowClientCertificate

    # setup client cert authentication to validate a user
    New-PodeAuthScheme -ClientCertificate | Add-PodeAuth -Name 'Login' -Sessionless -ScriptBlock {
        param($cert, $errors)

        # validate the thumbprint - here you would check a real cert store, or database
        if ($cert.Thumbprint -ieq '3571B3BE3CA202FA56F73691FC258E653D0874C1') {
            return @{
                User = @{
                    ID ='M0R7Y302'
                    Name = 'Morty'
                    Type = 'Human'
                }
            }
        }

        # an invalid cert
        return @{ Message = 'Invalid certificate supplied' }
    }

    # check the request on this route against the authentication
    Add-PodeRoute -Method Get -Path '/cpu' -Authentication 'Login' -ScriptBlock {
        Write-PodeJsonResponse -Value @{ 'cpu' = 82 }
    }

    # this route will not be validated against the authentication
    Add-PodeRoute -Method Get -Path '/memory' -ScriptBlock {
        Write-PodeJsonResponse -Value @{ 'memory' = 14 }
    }
}
```

--------------------------------

### Full API Key Authentication Example

Source: https://github.com/badgerati/pode/blob/develop/docs/Tutorials/Authentication/Methods/ApiKey.md

A comprehensive example demonstrating setup, configuration for header-based API key validation, and applying authentication to a specific route.

```powershell
Start-PodeServer {
    Add-PodeEndpoint -Address * -Port 8080 -Protocol Http

    # setup apikey authentication to validate a user
    New-PodeAuthScheme -ApiKey | Add-PodeAuth -Name 'Authenticate' -Sessionless -ScriptBlock {
        param($key)

        # here you'd check a real storage, this is just for example
        if ($key -eq 'test-key') {
            return @{
                User = @{
                    'ID' ='M0R7Y302'
                    'Name' = 'Morty'
                    'Type' = 'Human'
                }
            }
        }

        # authentication failed
        return $null
    }

    # check the request on this route against the authentication
    Add-PodeRoute -Method Get -Path '/cpu' -Authentication 'Authenticate' -ScriptBlock {
        Write-PodeJsonResponse -Value @{ 'cpu' = 82 }
    }

    # this route will not be validated against the authentication
    Add-PodeRoute -Method Get -Path '/memory' -ScriptBlock {
        Write-PodeJsonResponse -Value @{ 'memory' = 14 }
    }
}
```

--------------------------------

### Full Negotiate Authentication Example

Source: https://github.com/badgerati/pode/blob/develop/docs/Tutorials/Authentication/Methods/Negotiate.md

A complete example demonstrating the setup of Negotiate authentication, including endpoint configuration, scheme creation, and applying authentication to a specific route. It also shows an unauthenticated route for comparison.

```powershell
Start-PodeServer -Threads 2 {
    Add-PodeEndpoint -Address localhost -Port 8080 -Host 'pode.example.com' -Protocol Http

    # setup negotiate authentication
    $keytab = '.\pode.keytab'
    New-PodeAuthScheme -Negotiate -KeytabPath $keytab | Add-PodeAuth -Name 'Login' -Sessionless -ScriptBlock {
        param($claim)
        return @{ User = $claim }
    }

    # check the request on this route against the authentication
    Add-PodeRoute -Method Get -Path '/cpu' -Authentication 'Login' -ScriptBlock {
        Write-PodeJsonResponse -Value @{ 'cpu' = 82 }
    }

    # this route will not be validated against the authentication
    Add-PodeRoute -Method Get -Path '/memory' -ScriptBlock {
        Write-PodeJsonResponse -Value @{ 'memory' = 14 }
    }
}
```

--------------------------------

### Full Bearer Authentication Example

Source: https://github.com/badgerati/pode/blob/develop/docs/Tutorials/Authentication/Methods/Bearer.md

A comprehensive example demonstrating setup, token validation, and route-specific authentication using Bearer tokens.

```powershell
Start-PodeServer {
    Add-PodeEndpoint -Address * -Port 8080 -Protocol Http

    # setup bearer authentication to validate a user
    New-PodeAuthScheme -Bearer | Add-PodeAuth -Name 'Authenticate' -Sessionless -ScriptBlock {
        param($token)

        # here you'd check a real storage, this is just for example
        if ($token -eq 'test-token') {
            return @{
                User = @{
                    'ID' ='M0R7Y302'
                    'Name' = 'Morty'
                    'Type' = 'Human'
                }
                # Scope = 'read'
            }
        }

        # authentication failed
        return $null
    }

    # check the request on this route against the authentication
    Add-PodeRoute -Method Get -Path '/cpu' -Authentication 'Authenticate' -ScriptBlock {
        Write-PodeJsonResponse -Value @{ 'cpu' = 82 }
    }

    # this route will not be validated against the authentication
    Add-PodeRoute -Method Get -Path '/memory' -ScriptBlock {
        Write-PodeJsonResponse -Value @{ 'memory' = 14 }
    }
}
```

--------------------------------

### Full Azure AD Authentication Example

Source: https://github.com/badgerati/pode/blob/develop/docs/Tutorials/Authentication/Inbuilt/AzureAD.md

A comprehensive example demonstrating the setup and configuration of Azure AD authentication. This includes setting up endpoints, session middleware, authentication schemes, and defining routes for home, login, and logout.

```powershell
Start-PodeServer {
    Add-PodeEndpoint -Address * -Port 8080 -Protocol Http
    Set-PodeViewEngine -Type Pode

    # setup session details
    Enable-PodeSessionMiddleware -Duration 120 -Extend

    # setup authentication to validate a user
    $scheme = New-PodeAuthAzureADScheme -ClientID '<clientId>' -ClientSecret '<clientSecret>' -Tenant '<tenant>'

    $scheme | Add-PodeAuth -Name 'Login' -FailureUrl '/login' -SuccessUrl '/' -ScriptBlock {
        param($user, $accessToken, $refreshToken, $response)

        # check if the user is valid

        return @{ User = $user }
    }

    # home page:
    # redirects to login page if not authenticated
    Add-PodeRoute -Method Get -Path '/' -Authentication Login -ScriptBlock {
        Write-PodeViewResponse -Path 'home' -Data @{ Username = $WebEvent.Auth.User.name }
    }

    # login - this will just redirect to azure
    # NOTE: you do not need the -Login switch
    Add-PodeRoute -Method Get -Path '/login' -Authentication Login

    # logout
    Add-PodeRoute -Method Post -Path '/logout' -Authentication Login -Logout
}
```

--------------------------------

### Full Basic Authentication Example

Source: https://github.com/badgerati/pode/blob/develop/docs/Tutorials/Authentication/Methods/Basic.md

A comprehensive example demonstrating the setup of Basic authentication, including user validation and applying it to a specific route. Unprotected routes can also be defined.

```powershell
Start-PodeServer {
    Add-PodeEndpoint -Address * -Port 8080 -Protocol Http

    # setup basic authentication to validate a user
    New-PodeAuthScheme -Basic | Add-PodeAuth -Name 'Login' -Sessionless -ScriptBlock {
        param($username, $password)

        # here you'd check a real user storage, this is just for example
        if ($username -eq 'morty' -and $password -eq 'pickle') {
            return @{
                User = @{
                    'ID' ='M0R7Y302'
                    'Name' = 'Morty';
                    'Type' = 'Human';
                }
            }
        }

        # authentication failed
        return $null
    }

    # check the request on this route against the authentication
    Add-PodeRoute -Method Get -Path '/cpu' -Authentication 'Login' -ScriptBlock {
        Write-PodeJsonResponse -Value @{ 'cpu' = 82 }
    }

    # this route will not be validated against the authentication
    Add-PodeRoute -Method Get -Path '/memory' -ScriptBlock {
        Write-PodeJsonResponse -Value @{ 'memory' = 14 }
    }
}
```

--------------------------------

### Full Pode MCP Server Example

Source: https://github.com/badgerati/pode/blob/develop/docs/Tutorials/Misc/MCP.md

This script demonstrates how to start a Pode server, configure an MCP group, add an MCP tool to retrieve Windows services by state, and set up the MCP route. Ensure your MCP server is configured to connect to `http://localhost:8080/mcp`.

```powershell
Start-PodeServer -Threads 2 {
    Add-PodeEndpoint -Address localhost -Port 8080 -Protocol Http

    # Create a simple default group for MCP tools
    Add-PodeMcpGroup -Name 'Default' -Description 'Default group for MCP tools'

    # Add a simple MCP tool for returning windows services names for a given state
    Add-PodeMcpTool -Name 'GetWindowsServicesByState' -Description 'Returns Windows service names for a given state' -Group 'Default' -AutoSchema -ScriptBlock {
        param(
            [Parameter(Mandatory = $true, HelpMessage = 'The state of the services to retrieve')]
            [ValidateSet('Running', 'Stopped', 'Paused')]
            [string]
            $State
        )

        $services = Get-Service -ErrorAction Ignore | Where-Object { $_.Status -ieq $State } | Select-Object Name
        if (($null -eq $services) -or (Test-PodeIsEmpty $services)) {
            $services = "No services found in the '$State' state."
        }

        return New-PodeMcpTextContent -Value $services
    }

    # Add the MCP route
    Add-PodeRoute -Method Post -Path '/mcp' -ScriptBlock {
        Resolve-PodeMcpRequest -Group 'Default'
    }
}
```

--------------------------------

### Start Pode Server as Desktop App

Source: https://github.com/badgerati/pode/blob/develop/docs/Tutorials/Misc/DesktopApp.md

Use Show-PodeGui to display a Pode server as a desktop application. The Title parameter is mandatory. This example sets up a basic HTTP server on localhost:8080 and serves an 'index' view.

```powershell
Start-PodeServer {
    Add-PodeEndpoint -Address localhost -Port 8080 -Protocol Http

    Show-PodeGui -Title 'Basic Server'

    Add-PodeRoute -Method Get -Path '/' -ScriptBlock {
        Write-PodeViewResponse -Path 'index'
    }
}
```

--------------------------------

### Full Digest Authentication Example

Source: https://github.com/badgerati/pode/blob/develop/docs/Tutorials/Authentication/Methods/Digest.md

A complete example demonstrating the setup of Digest authentication, including user validation within the ScriptBlock and applying it to a specific route.

```powershell
Start-PodeServer {
    Add-PodeEndpoint -Address * -Port 8080 -Protocol Http

    # setup digest authentication to validate a user
    New-PodeAuthScheme -Digest | Add-PodeAuth -Name 'Authenticate' -Sessionless -ScriptBlock {
        param($username, $params)

        # here you'd check a real user storage, this is just for example
        if ($username -eq 'morty') {
            return @{
                User = @{
                    'ID' ='M0R7Y302'
                    'Name' = 'Morty';
                    'Type' = 'Human';
                }
                Password = 'pickle'
            }
        }

        # authentication failed
        return $null
    }

    # check the request on this route against the authentication
    Add-PodeRoute -Method Get -Path '/cpu' -Authentication 'Authenticate' -ScriptBlock {
        Write-PodeJsonResponse -Value @{ 'cpu' = 82 }
    }

    # this route will not be validated against the authentication
    Add-PodeRoute -Method Get -Path '/memory' -ScriptBlock {
        Write-PodeJsonResponse -Value @{ 'memory' = 14 }
    }
}
```

--------------------------------

### Full Twitter Authentication Example

Source: https://github.com/badgerati/pode/blob/develop/docs/Tutorials/Authentication/Inbuilt/Twitter.md

A comprehensive example demonstrating the setup of Twitter authentication, including endpoint configuration, scheme definition, and route definitions for home, login, and logout.

```powershell
Start-PodeServer {
    Add-PodeEndpoint -Address * -Port 8080 -Protocol Http
    Set-PodeViewEngine -Type Pode

    # setup authentication to validate a user
    $scheme = New-PodeAuthTwitterScheme -ClientID '<clientId>' -ClientSecret '<clientSecret>'

    $scheme | Add-PodeAuth -Name 'Login' -FailureUrl '/login' -SuccessUrl '/' -ScriptBlock {
        param($user, $accessToken, $refreshToken, $response)

        # check if the user is valid

        return @{ User = $user.data }
    }

    # home page:
    # redirects to login page if not authenticated
    Add-PodeRoute -Method Get -Path '/' -Authentication Login -ScriptBlock {
        Write-PodeViewResponse -Path 'home' -Data @{ Username = $WebEvent.Auth.User.name }
    }

    # login - this will just redirect to twitter
    # NOTE: you do not need the -Login switch
    Add-PodeRoute -Method Get -Path '/login' -Authentication Login

    # logout
    Add-PodeRoute -Method Post -Path '/logout' -Authentication Login -Logout
}
```

--------------------------------

### Start Pode Server with Ping Endpoint

Source: https://github.com/badgerati/pode/blob/develop/README.md

This snippet demonstrates how to start a Pode web server and define a simple '/ping' endpoint that responds with JSON. Ensure Pode is installed and accessible in your PowerShell environment.

```powershell
Start-PodeServer -ScriptBlock {
    Add-PodeEndPoint -Address localhost -port 32005 -Protocol Http

    Add-PodeRoute -Method Get -Path '/ping' -ScriptBlock {
        Write-PodeJsonResponse -Value @{value = 'pong' }
    }
}

# then call "http://127.0.0.1:32005/ping"
```

--------------------------------

### Start Pode Server with ScriptBlock

Source: https://github.com/badgerati/pode/blob/develop/docs/Tutorials/Basics.md

Define your server's logic within a ScriptBlock passed to the -ScriptBlock parameter of Start-PodeServer. This example configures an HTTP endpoint on port 8080 and adds a page to display running processes.

```powershell
Start-PodeServer {
    # attach to port 8080 for http
    Add-PodeEndpoint -Address * -Port 8080 -Protocol Http

    # a simple page for displaying services
    Add-PodePage -Name 'processes' -ScriptBlock { Get-Process }
}
```

--------------------------------

### Install Local Modules

Source: https://github.com/badgerati/pode/blob/develop/docs/Getting-Started/LocalModules.md

Run 'pode install' to download modules defined in package.json. Use 'pode -d install' to also download dev-modules.

```bash
pode install
```

```bash
pode -d install
```

--------------------------------

### Paths Object Example (YAML)

Source: https://github.com/badgerati/pode/blob/develop/docs/Tutorials/OpenAPI/Specification/v3.0.3.md

An example of the Paths Object in YAML format, defining a GET operation for the '/pets' path with a 200 OK response.

```yaml
/pets:
  get:
    description: Returns all pets from the system that the user has access to
    responses:
      '200':
        description: A list of pets.
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/pet'
```

--------------------------------

### Path Item Object Example with External Servers

Source: https://github.com/badgerati/pode/blob/develop/docs/Tutorials/OpenAPI/Specification/v3.0.3.md

This example demonstrates how to define a path item object with external servers, including GET method, parameters, and responses.

```APIDOC
## GET /peta/:id

### Description
Returns pets based on ID

### Method
GET

### Endpoint
/peta/:id

### Parameters
#### Path Parameters
- **id** (array of string) - Required - ID of pet to use

### Request Example
```json
{
  "example": "request body"
}
```

### Response
#### Success Response (200)
- ***/* ** (array of Pet) - pet response

#### Response Example
```json
{
  "example": "response body"
}
```

#### Error Response (default)
- **text/html** (ErrorModel) - error payload
```

--------------------------------

### Example package.json Structure

Source: https://github.com/badgerati/pode/blob/develop/docs/Getting-Started/CLI.md

An example of a `package.json` file used by Pode, demonstrating the structure for defining project metadata and scripts.

```json
{
    "name":  "example",
    "description":  "",
    "version":  "1.0.0",
    "main":  "./server.ps1",
    "scripts":  {
        "start":  "./server.ps1",
        "test":  "invoke-pester ./tests/*.ps1",
        "install":  "yarn install --force --ignore-scripts --modules-folder pode_modules",
        "build": "psake"
    },
    "author":  "Rick Sanchez",
    "license":  "MIT"
}
```

--------------------------------

### Create a Simple REST API Endpoint with Pode

Source: https://github.com/badgerati/pode/blob/develop/docs/index.md

Use this snippet to quickly set up a Pode server that listens on a specific port and responds to a GET request at a defined path with a JSON object. Ensure the Pode module is installed and accessible.

```powershell
Start-PodeServer {
    Add-PodeEndpoint -Address localhost -Port 8080 -Protocol Http

    Add-PodeRoute -Method Get -Path '/ping' -ScriptBlock {
        Write-PodeJsonResponse -Value @{ 'value' = 'pong' }
    }
}
```

--------------------------------

### Install dotnet (MacOS)

Source: https://github.com/badgerati/pode/blob/develop/docs/Getting-Started/build.md

Installs the .NET SDK on macOS using Homebrew.

```shell
brew install dotnet
```

--------------------------------

### Media Type Examples in YAML

Source: https://github.com/badgerati/pode/blob/develop/docs/Tutorials/OpenAPI/Specification/v3.0.3.md

Demonstrates the structure for defining media type examples in YAML, mirroring the JSON format with schema references and example values.

```yaml
application/json:
  schema:
    $ref: "#/components/schemas/Pet"
  examples:
    cat:
      summary: An example of a cat
      value:
        name: Fluffy
        petType: Cat
        color: White
        gender: male
        breed: Persian
    dog:
      summary: An example of a dog with a cat's name
      value:
        name: Puma
        petType: Dog
        color: Black
        gender: Female
        breed: Mixed
    frog:
      $ref: "#/components/examples/frog-example"
```

--------------------------------

### Setup API Key Authentication for Advanced Merge

Source: https://github.com/badgerati/pode/blob/develop/docs/Tutorials/Authentication/Overview.md

Configures an API key authentication scheme, similar to the previous example, for use in a more complex merge scenario.

```powershell
# setup apikey auth
New-PodeAuthScheme -ApiKey -Location Header | Add-PodeAuth -Name 'ApiKey' -Sessionless -ScriptBlock {
    param($key)

    # here you'd check a real user storage, this is just for example
    if ($key -ieq 'test-api-key') {
        return @{ User = @{ Name = 'Morty' } }
    }

    return $null
}
```

--------------------------------

### Define Response Examples in YAML

Source: https://github.com/badgerati/pode/blob/develop/docs/Tutorials/OpenAPI/Specification/v3.0.3.md

YAML snippet showing how to reference an example for a successful response.

```yaml
responses:
  '200':
    description: your car appointment has been booked
    content:
      application/json:
        schema:
          $ref: '#/components/schemas/SuccessResponse'
        examples:
          confirmation-success:
            $ref: '#/components/examples/confirmation-success'
```

--------------------------------

### Define Parameter Examples in YAML

Source: https://github.com/badgerati/pode/blob/develop/docs/Tutorials/OpenAPI/Specification/v3.0.3.md

YAML structure for referencing an example for a query parameter.

```yaml
parameters:
  - name: 'zipCode'
    in: 'query'
    schema:
      type: 'string'
      format: 'zip-code'
    examples:
      zip-example:
        $ref: '#/components/examples/zip-example'
```

--------------------------------

### Start Pode Server with Endpoint

Source: https://github.com/badgerati/pode/blob/develop/docs/Getting-Started/FirstApp.md

Start the Pode server and configure it to listen on a specific address and port for HTTP requests.

```powershell
Start-PodeServer {
    # logic
}
```

```powershell
Start-PodeServer {
    Add-PodeEndpoint -Address localhost -Port 8080 -Protocol Http
}
```

--------------------------------

### Media Type Examples in JSON

Source: https://github.com/badgerati/pode/blob/develop/docs/Tutorials/OpenAPI/Specification/v3.0.3.md

Illustrates how to define media type examples for a request body in JSON format, including schema references and direct example values.

```json
{
  "application/json": {
    "schema": {
         "$ref": "#/components/schemas/Pet"
    },
    "examples": {
      "cat" : {
        "summary": "An example of a cat",
        "value":
          {
            "name": "Fluffy",
            "petType": "Cat",
            "color": "White",
            "gender": "male",
            "breed": "Persian"
          }
      },
      "dog": {
        "summary": "An example of a dog with a cat's name",
        "value" :  {
          "name": "Puma",
          "petType": "Dog",
          "color": "Black",
          "gender": "Female",
          "breed": "Mixed"
        },
      "frog": {
          "$ref": "#/components/examples/frog-example"
        }
      }
    }
  }
}
```

--------------------------------

### Install k6 on Windows

Source: https://github.com/badgerati/pode/blob/develop/tests/perf/README.md

Use Chocolatey to install k6 on Windows systems.

```powershell
choco install k6 -y
```

--------------------------------

### Install Pode from PowerShell Gallery

Source: https://github.com/badgerati/pode/blob/develop/docs/Getting-Started/Installation.md

Use this command to install the Pode module from the PowerShell Gallery.

```powershell
Install-Module -Name Pode
```

--------------------------------

### Install Packages with Pode CLI

Source: https://github.com/badgerati/pode/blob/develop/docs/Getting-Started/CLI.md

Runs the installation script defined in the `package.json` file under the `scripts/install` property. This is useful for managing project dependencies.

```powershell
pode install
```

--------------------------------

### Media Type Object Examples

Source: https://github.com/badgerati/pode/blob/develop/docs/Tutorials/OpenAPI/Specification/v3.0.3.md

Illustrates the usage of the Media Type Object with examples for JSON content.

```APIDOC
## Media Type Object Examples

### Description
Demonstrates how to define media types and their associated examples.

### PowerShell Example
```powershell
New-PodeOARequestBody -Content @{ 'application/json' = 'Pet' } -Examples (
  New-PodeOAExample -ContentType 'application/json' -Name 'cat' -Summary 'An example of a cat' -Value  @{name = 'Fluffy'; petType = 'Cat'; color = 'White'; gender = 'male'; breed = 'Persian' } |
    New-PodeOAExample -ContentType 'application/json' -Name 'dog' -Summary "An example of a dog with a cat's name" -Value    @{name = 'Puma'; petType = 'Dog'; color = 'Black'; gender = 'Female'; breed = 'Mixed' }|
    New-PodeOAExample -ContentType 'application/json' -Reference 'frog-example'
  )
```

### JSON Example
```json
{
  "application/json": {
    "schema": {
         "$ref": "#/components/schemas/Pet"
    },
    "examples": {
      "cat" : {
        "summary": "An example of a cat",
        "value":
          {
            "name": "Fluffy",
            "petType": "Cat",
            "color": "White",
            "gender": "male",
            "breed": "Persian"
          }
      },
      "dog": {
        "summary": "An example of a dog with a cat's name",
        "value" :  {
          "name": "Puma",
          "petType": "Dog",
          "color": "Black",
          "gender": "Female",
          "breed": "Mixed"
        },
      "frog": {
          "$ref": "#/components/examples/frog-example"
        }
      }
    }
  }
}
```

### YAML Example
```yaml
application/json:
  schema:
    $ref: "#/components/schemas/Pet"
  examples:
    cat:
      summary: An example of a cat
      value:
        name: Fluffy
        petType: Cat
        color: White
        gender: male
        breed: Persian
    dog:
      summary: An example of a dog with a cat's name
      value:
        name: Puma
        petType: Dog
        color: Black
        gender: Female
        breed: Mixed
    frog:
      $ref: "#/components/examples/frog-example"
```
```

--------------------------------

### Example Script File for Route

Source: https://github.com/badgerati/pode/blob/develop/docs/Tutorials/Routes/Overview.md

This is an example of a script file that can be referenced by the `-FilePath` parameter in `Add-PodeRoute` to define route logic.

```powershell
{
    Write-PodeJsonResponse -Value @{ 'value' = 'pong'; }
}
```

--------------------------------

### Install and Start Windows Service with NSSM

Source: https://github.com/badgerati/pode/blob/develop/docs/Hosting/RunAsService.md

Installs the new Windows service using NSSM with the defined parameters and then starts the service.

```powershell
nssm install $name $exe $arg
nssm start $name
```

--------------------------------

### Full Example: Web Server with SecretStore

Source: https://github.com/badgerati/pode/blob/develop/docs/Tutorials/Secrets/Examples/SecretStore.md

A comprehensive example demonstrating how to set up a Pode web server that registers a local SecretStore vault, manages a secret, and exposes it via routes. Includes setting, mounting, retrieving, and updating secrets.

```powershell
Start-PodeServer -Threads 2 {
    Add-PodeEndpoint -Address * -Port 8080 -Protocol Http

    # register the vault
    Register-PodeSecretVault `
        -Name 'ExampleVault' `
        -ModuleName 'Microsoft.PowerShell.SecretStore' `
        -UnlockSecret 'Sup3rSecur3Pa$$word!'

    # set a secret in the local vault
    Set-PodeSecret -Key 'example' -Vault 'ExampleVault' -InputObject 'hello, world!'

    # mount the "example" secret from local vault, making it accessible via $secret:example
    Mount-PodeSecret -Name 'example' -Vault 'ExampleVault' -Key 'example'

    # retrieve the secret in a route
    Add-PodeRoute -Method Get -Path '/' -ScriptBlock {
        Write-PodeJsonResponse @{ Value = $secret:example }
    }

    # update the secret in a route
    Add-PodeRoute -Method Post -Path '/' -ScriptBlock {
        $secret:example = $WebEvent.Data.Value
    }
}
```

--------------------------------

### Install Add-Debugger Script

Source: https://github.com/badgerati/pode/blob/develop/docs/Getting-Started/Debug.md

Install the Add-Debugger script from the PowerShell Gallery to enable debugging within the same console that started Pode.

```powershell
Install-Script -Name Add-Debugger
```

--------------------------------

### Install InvokeBuild Module (PowerShell Gallery)

Source: https://github.com/badgerati/pode/blob/develop/docs/Getting-Started/build.md

Installs the InvokeBuild module from the PowerShell Gallery for use in building Pode.

```powershell
Install-Module InvokeBuild -Scope CurrentUser
```

--------------------------------

### Paths Object Example

Source: https://github.com/badgerati/pode/blob/develop/docs/Tutorials/OpenAPI/Specification/v3.0.3.md

An example demonstrating the Paths Object in OpenAPI Specification, showing how to define a GET endpoint for retrieving pets.

```APIDOC
## GET /pets

### Description
Returns all pets from the system that the user has access to

### Method
GET

### Endpoint
/pets

### Response
#### Success Response (200)
- **items** (array) - A list of pets.
  - **$ref** (string) - Reference to the Pet schema

### Response Example
```json
{
  "/pets": {
    "get": {
      "description": "Returns all pets from the system that the user has access to",
      "responses": {
        "200": {
          "description": "A list of pets.",
          "content": {
            "application/json": {
              "schema": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/pet"
                }
              }
            }
          }
        }
      }
    }
  }
}
```
```

--------------------------------

### Load and Use Port from Configuration

Source: https://github.com/badgerati/pode/blob/develop/docs/Tutorials/Configuration.md

Demonstrates how to start a Pode server and use a port defined in the `server.psd1` configuration file.

```powershell
Start-PodeServer {
    $port = (Get-PodeConfig).Port
    Add-PodeEndpoint -Address * -Port $port -Protocol Http
}
```

--------------------------------

### Paths Object Example (JSON)

Source: https://github.com/badgerati/pode/blob/develop/docs/Tutorials/OpenAPI/Specification/v3.0.3.md

An example of the Paths Object in JSON format, defining a GET operation for the '/pets' path with a 200 OK response.

```json
{
  "/pets": {
    "get": {
      "description": "Returns all pets from the system that the user has access to",
      "responses": {
        "200": {
          "description": "A list of pets.",
          "content": {
            "application/json": {
              "schema": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/pet"
                }
              }
            }
          }
        }
      }
    }
  }
}
```

--------------------------------

### Initialize Pode Project

Source: https://github.com/badgerati/pode/blob/develop/docs/Getting-Started/FirstApp.md

Use the `pode init` command to create a basic `package.json` file for your Pode project. Press Enter to accept default values.

```powershell
PS> pode init
name (my-first-pode-app):
version (1.0.0):
description:
entry point (./server.ps1):
author:
license (MIT):
Success, saved package.json
```

--------------------------------

### Full Server Setup with Authentication

Source: https://github.com/badgerati/pode/blob/develop/docs/Tutorials/Routes/Examples/LoginPage.md

This script sets up a Pode server with HTTP endpoints, session middleware, form authentication, and defines routes for the homepage, login, and logout.

```powershell
Start-PodeServer -Thread 2 {
    Add-PodeEndpoint -Address * -Port 8080 -Protocol Http

    # use pode template engine
    Set-PodeViewEngine -Type Pode

    # setup session middleware
    Enable-PodeSessionMiddleware -Duration 120 -Extend

    # setup form authentication
    New-PodeAuthScheme -Form | Add-PodeAuth -Name 'Login' -FailureUrl '/login' -SuccessUrl '/' -ScriptBlock {
        param($username, $password)

        # here you'd check a real user storage, this is just for example
        if ($username -eq 'morty' -and $password -eq 'pickle') {
            return @{
                User = @{
                    ID ='M0R7Y302'
                    Name = 'Morty'
                    Type = 'Human'
                }
            }
        }

        # aww geez! no user was found
        return @{ Message = 'Invalid details supplied' }
    }

    # the "GET /" endpoint for the homepage
    Add-PodeRoute -Method Get -Path '/' -Authentication 'Login' -ScriptBlock {
        $WebEvent.Session.Data.Views++

        Write-PodeViewResponse -Path 'auth-home' -Data @{
            Username = $WebEvent.Auth.User.Name;
            Views = $WebEvent.Session.Data.Views;
        }
    }

    # the "GET /login" endpoint for the login page
    Add-PodeRoute -Method Get -Path '/login' -Authentication 'Login' -Login -ScriptBlock {
        Write-PodeViewResponse -Path 'auth-login' -FlashMessages
    }

    # the "POST /login" endpoint for user authentication
    Add-PodeRoute -Method Post -Path '/login' -Authentication 'Login' -Login

    # the "POST /logout" endpoint for ending the session
    Add-PodeRoute -Method Post -Path '/logout' -Authentication 'Login' -Logout
}
```

--------------------------------

### Start Pode Server with Custom Config Path

Source: https://github.com/badgerati/pode/blob/develop/docs/Tutorials/Configuration.md

Shows how to specify a custom configuration file path when starting the Pode server using the `-ConfigFile` parameter.

```powershell
Start-PodeServer -ConfigFile "C:\Configs\custom_server.psd1" {
    $port = (Get-PodeConfig).Port
    Add-PodeEndpoint -Address * -Port $port -Protocol Http
}
```

--------------------------------

### Start Project with Pode CLI

Source: https://github.com/badgerati/pode/blob/develop/docs/Getting-Started/CLI.md

Executes the start script defined in `package.json` at `scripts/start`. If `scripts/start` is not set, it defaults to running the script specified in the `main` property.

```powershell
pode start
```

--------------------------------

### Register Login Event for Basic Authentication

Source: https://github.com/badgerati/pode/blob/develop/docs/Tutorials/Authentication/Overview.md

Sets up a basic authentication method named 'Example' and then registers a scriptblock to handle the 'Login' event, logging the username to the console.

```powershell
# create the basic authentication method
New-PodeAuthScheme -Basic | Add-PodeAuth -Name 'Example' -Sessionless -ScriptBlock { }

# register for the Login event
Register-PodeAuthEvent -Name 'Example' -Type Login -EventName 'OnLogin' -ScriptBlock {
    "User logged in: $($TriggeredEvent.User.Name)" | Out-Default
}
```

--------------------------------

### Example Server.psd1 Configuration

Source: https://github.com/badgerati/pode/blob/develop/docs/Tutorials/Configuration.md

Illustrates the structure for defining server configuration options within the server.psd1 file, specifically showing SSL protocol settings.

```powershell
@{
    Server = @{
        Ssl= @{
            Protocols = @('TLS', 'TLS11', 'TLS12')
        }
    }
}
```

--------------------------------

### Configure OAuth2 with OIDC Discovery and PKCE

Source: https://github.com/badgerati/pode/blob/develop/docs/Tutorials/Authentication/Methods/OAuth2.md

This example shows how to automatically build an OAuth2 scheme using OIDC discovery, suitable for providers like Google. PKCE is enabled in this configuration.

```powershell
$scheme = ConvertFrom-PodeOIDCDiscovery -Url 'https://accounts.google.com' -ClientId '<client_id>' -UsePKCE

$scheme | Add-PodeAuth -Name 'Login' -FailureUrl '/login' -SuccessUrl '/' -ScriptBlock {
    param($user, $accessToken, $refreshToken, $response)

    # check if the user is valid

    return @{ User = $user }
}
```

--------------------------------

### Defining Path Parameter

Source: https://github.com/badgerati/pode/blob/develop/docs/Tutorials/OpenAPI/1Overview.md

This example shows how to define a required integer path parameter named 'userId' for a GET request.

```APIDOC
## GET /api/users/:userId

### Description
Defines a GET route to retrieve a user by their ID, specifying 'userId' as a required path parameter.

### Method
GET

### Endpoint
/api/users/:userId

### Parameters
#### Path Parameters
- **userId** (integer) - Required - The ID of the user to retrieve.

### Responses
#### Success Response (200)
- **Description**: Default success response.

### Request Example
(No request body defined)

### Response Example
```json
{
  "Name": "Rick",
  "UserId": 123
}
```
```

--------------------------------

### Add-PodeRoute Example

Source: https://github.com/badgerati/pode/blob/develop/docs/Tutorials/OpenAPI/Specification/v3.0.3.md

This snippet demonstrates how to define a GET route for '/pet/:petId' using Add-PodeRoute and how to set OpenAPI information for the operation.

```APIDOC
## GET /pet/:petId

### Description
Retrieves a pet's information based on its ID.

### Method
GET

### Endpoint
/pet/:petId

### Parameters
#### Path Parameters
- **petId** (string) - Required - The ID of the pet to retrieve.

### Request Example
(No request body example provided in source)

### Response
#### Success Response (200)
- **value** (object) - The pet object containing pet details.

#### Response Example
(No response body example provided in source)
```

--------------------------------

### Defining Query Parameters

Source: https://github.com/badgerati/pode/blob/develop/docs/Tutorials/OpenAPI/1Overview.md

This example demonstrates defining two required string query parameters, 'name' and 'city', for a GET request.

```APIDOC
## GET /api/users

### Description
Defines a GET route to retrieve users, accepting 'name' and 'city' as required query parameters.

### Method
GET

### Endpoint
/api/users

### Parameters
#### Query Parameters
- **name** (string) - Required - The name to filter users by.
- **city** (string) - Required - The city to filter users by.

### Responses
#### Success Response (200)
- **Description**: Default success response.

### Request Example
(No request body defined)

### Response Example
```json
{
  "Name": "Rick",
  "UserId": "some_query_param_value"
}
```
```

--------------------------------

### Dockerfile for Default Ubuntu Pode Image

Source: https://github.com/badgerati/pode/blob/develop/docs/Hosting/Docker.md

This Dockerfile example shows how to pull the latest Pode Ubuntu image, copy your application files, expose the necessary port, and run the server script.

```dockerfile
# pull down the pode image
FROM badgerati/pode:latest

# or use the following for GitHub
# FROM docker.pkg.github.com/badgerati/pode/pode:latest

# copy over the local files to the container
COPY . /usr/src/app/

# expose the port
EXPOSE 8085

# run the server
CMD [ "pwsh", "-c", "cd /usr/src/app; ./web-pages-docker.ps1" ]
```

--------------------------------

### Manual Route Addition Example

Source: https://github.com/badgerati/pode/blob/develop/docs/Tutorials/Routes/Utilities/AutomaticFunctionsAndModules.md

This demonstrates the equivalent manual route additions that `ConvertTo-PodeRoute` performs for `Get-ChildItem` (GET) and `Invoke-Expression` (POST).

```powershell
Add-PodeRoute -Method Get -Path '/Get-ChildItem' -ScriptBlock {
    $parameters = $WebEvent.Query
    $result = (Get-ChildItem @parameters)
    Write-PodeJsonResponse -Value $result -Depth 1
}

Add-PodeRoute -Method Post -Path '/Invoke-Expression' -ScriptBlock {
    $parameters = $WebEvent.Data
    $result = (Invoke-Expression @parameters)
    Write-PodeJsonResponse -Value $result -Depth 1
}
```

--------------------------------

### Get Request Header Value

Source: https://github.com/badgerati/pode/blob/develop/docs/Tutorials/Headers.md

Retrieve the value of a specific header from the incoming request using Get-PodeHeader. This example retrieves the value of 'X-Header-Name'.

```powershell
Add-PodeRoute -Method Get -Path '/' -ScriptBlock {
    Get-PodeHeader -Name 'X-Header-Name'
}
```

--------------------------------

### Getting Endpoint Name with PassThru

Source: https://github.com/badgerati/pode/blob/develop/docs/Getting-Started/Migrating/1X-to-2X.md

If no `-Name` is supplied to `Add-PodeEndpoint` in v2.X, a random GUID is used. Use `-PassThru` to retrieve the generated endpoint name.

```powershell
Add-PodeEndpoint -PassThru
```

--------------------------------

### Full Example: Register, Mount, and Access Azure Key Vault Secret

Source: https://github.com/badgerati/pode/blob/develop/docs/Tutorials/Secrets/Types/SecretManagement.md

This example demonstrates a complete workflow: registering an Azure Key Vault, mounting a specific secret from it, and setting up routes to retrieve and update that secret within a Pode server. Requires 'Connect-AzAccount' and appropriate Azure Key Vault parameters.

```powershell
param(
    [Parameter(Mandatory=$true)]
    [string]
    $VaultName,

    [Parameter(Mandatory=$true)]
    [string]
    $SubscriptionId
)

Start-PodeServer {
    Add-PodeEndpoint -Address * -Port 8080 -Protocol Http

    # secret manage azure keyvault - need to run "Connect-AzAccount" first!
    Register-PodeSecretVault -Name 'FriendlyVaultName' -ModuleName 'Az.KeyVault' -VaultParameters @{
        AZKVaultName = $VaultName
        SubscriptionId = $SubscriptionId
    }

    # mount a secret from az keyvault
    Mount-PodeSecret -Name 'SecretName' -Vault 'FriendlyVaultName' -Key 'AKVSecretName'


    # routes to get/update secret in az keyvault
    Add-PodeRoute -Method Get -Path '/secret' -ScriptBlock {
        Write-PodeJsonResponse @{ Value = $secret:SecretName }
    }

    Add-PodeRoute -Method Post -Path '/secret' -ScriptBlock {
        $secret:SecretName = $WebEvent.Data.Value
    }
}
```

--------------------------------

### Install ASP.NET Core Windows Hosting Bundle

Source: https://github.com/badgerati/pode/blob/develop/docs/Hosting/IIS.md

Installs the necessary hosting components for ASP.NET Core applications on Windows. This is required for Pode to run correctly under IIS.

```powershell
choco install dotnet-windowshosting -y
```

--------------------------------

### Install k6 on Linux

Source: https://github.com/badgerati/pode/blob/develop/tests/perf/README.md

Download, extract, and copy the k6 binary to your system's PATH on Linux.

```bash
sudo curl -OL https://github.com/loadimpact/k6/releases/download/v0.20.0/k6-v0.20.0-linux64.tar.gz
sudo tar -xzf k6-v0.20.0-linux64.tar.gz
sudo cp k6-v0.20.0-linux64/k6 /usr/local/bin
```

--------------------------------

### Example Route Invocation (GET)

Source: https://github.com/badgerati/pode/blob/develop/docs/Tutorials/Routes/Utilities/AutomaticFunctionsAndModules.md

Demonstrates invoking the `/Get-ChildItem` route. Parameters can be passed directly in the URI query string or as a hashtable in the POST body. Parameters are accessed via `$WebEvent.Query`.

```powershell
#Direct Query Parameters
Invoke-RestMethod -Uri 'http://localhost:8080/Get-ChildItem?Path=/some/path'

#Powershell Hashtable to Query Parameter Conversion
Invoke-Restmethod http://localhost:8080/Get-ChildItem -Body @{Path = "/some/path"}  -Method GET
```

--------------------------------

### Pode Routing in AWS Lambda

Source: https://github.com/badgerati/pode/blob/develop/docs/Hosting/AwsLambda.md

Implement routing within your AWS Lambda Function using `Add-PodeRoute`. This example defines GET routes for '/users' and '/message', returning JSON responses.

```powershell
#Requires -Modules @{ModuleName='AWSPowerShell.NetCore';ModuleVersion='3.3.509.0'}
#Requires -Modules @{ModuleName='Pode';ModuleVersion='<version>'}

Start-PodeServer -Request $LambdaInput -ServerlessType AwsLambda {
    # get some user data
    Add-PodeRoute -Method Get -Path '/users' -ScriptBlock {
        Write-PodeJsonResponse -Value @{ 'Users' = @() }
    }

    # get some messages data
    Add-PodeRoute -Method Get -Path '/message' -ScriptBlock {
        Write-PodeJsonResponse -Value @{ 'UserId' = 123; 'Messages' = @() }
    }
}
```

--------------------------------

### Initialize package.json with Pode CLI

Source: https://github.com/badgerati/pode/blob/develop/docs/Getting-Started/CLI.md

Creates a new `package.json` file from scratch by interactively prompting for project details like author and name. Pode can pre-populate common script values.

```powershell
pode init
```

--------------------------------

### Start SMTP Server with TLS Endpoints

Source: https://github.com/badgerati/pode/blob/develop/docs/Servers/SMTP.md

This example shows how to configure SMTP endpoints with both explicit and implicit TLS. It uses self-signed certificates for demonstration purposes. The handler logs email details.

```powershell
Start-PodeServer {
    Add-PodeEndpoint -Address * -Protocol Smtps -SelfSigned -TlsMode Explicit
    Add-PodeEndpoint -Address * -Protocol Smtps -SelfSigned -TlsMode Implicit

    Add-PodeHandler -Type Smtp -Name 'Main' -ScriptBlock {
        Write-Host $SmtpEvent.Email.From
        Write-Host $SmtpEvent.Email.To
        Write-Host $SmtpEvent.Email.Body
    }
}
```

--------------------------------

### Add Route for SSE Connection

Source: https://github.com/badgerati/pode/blob/develop/docs/Tutorials/Routes/Utilities/SSE.md

Defines a GET route at '/sse' that converts incoming HTTP requests into an SSE connection named 'Example'. This route is used in conjunction with SSE event registration.

```powershell
# a Route to convert the HTTP request to an SSE connection
Add-PodeRoute -Method Get -Path '/sse' -ScriptBlock {
    ConvertTo-PodeSseConnection -Name 'Example'
}
```

--------------------------------

### Comprehensive CORS Configuration Example

Source: https://github.com/badgerati/pode/blob/develop/docs/Tutorials/CORS.md

An example demonstrating how to configure multiple CORS settings simultaneously, including origin, methods, headers, credentials, cache duration, automatic detection, and pre-flight request handling.

```powershell
Set-PodeSecurityAccessControl -Origin 'https://example.com' -Methods 'GET', 'POST' -Headers 'Content-Type', 'Authorization' -Duration 7200 -Credentials -WithOptions -AutoHeaders -AutoMethods -CrossDomainXhrRequests
```

--------------------------------

### Setup Negotiate Authentication Scheme

Source: https://github.com/badgerati/pode/blob/develop/docs/Tutorials/Authentication/Methods/Negotiate.md

Sets up the Negotiate authentication scheme using a generated keytab file and adds it to Pode's authentication system. The provided scriptblock is executed upon successful authentication, receiving the ClaimsPrincipal object.

```powershell
$keytab = '.\pode.keytab'
New-PodeAuthScheme -Negotiate -KeytabPath $keytab | Add-PodeAuth -Name 'Login' -Sessionless -ScriptBlock {
    param($claim)

    # perform any optional additional validation on the claim
    # the user's name will be under $claim.Identity.Name

    return @{ User = $claim }
}
```

--------------------------------

### Configure Login Route (GET and POST)

Source: https://github.com/badgerati/pode/blob/develop/docs/Tutorials/Routes/Examples/LoginPage.md

Sets up the login route. The GET method displays the login page, and the POST method handles authentication. The `-Login` switch ensures users with existing sessions are redirected to the home page and displays the login page on authentication failure instead of a 403 error.

```powershell
# the login page itself
Add-PodeRoute -Method Get -Path '/login' -Authentication 'Login' -Login -ScriptBlock {
    Write-PodeViewResponse -Path 'auth-login' -FlashMessages
}

# the POST action for the <form>
Add-PodeRoute -Method Post -Path '/login' -Authentication 'Login' -Login
```