github.com/avenga/couper@v1.12.2/docs/website/content/1.getting-started/3.examples.md (about)

     1  # Examples
     2  
     3  ## File and Web Serving
     4  
     5  Couper contains a Web server for simple file serving and also takes care of the more complex web serving of SPA assets.
     6  
     7  ```hcl
     8  server "example" {
     9  
    10    files {
    11      document_root = "htdocs"
    12    }
    13  
    14    spa {
    15      bootstrap_file = "htdocs/index.html"
    16      paths = ["/**"]
    17    }
    18  }
    19  ```
    20  
    21  The `files` block configures Couper's file server. It needs to know which directory to serve (`document_root`).
    22  
    23  The `spa` block is responsible for serving the bootstrap document for all paths that match the paths list.
    24  
    25  ## Exposing APIs
    26  
    27  Couper's main concept is exposing APIs via the configuration block `endpoint`, fetching data from upstream or remote services, represented by the configuration block `backend`.
    28  
    29  ```hcl
    30  server "example"{
    31  
    32    endpoint "/public/**"{
    33  
    34      proxy {
    35        backend {
    36          origin = "https://httpbin.org"
    37          path = "/**"
    38        }
    39      }
    40    }
    41  }
    42  ```
    43  
    44  This basic configuration defines an upstream backend service (`https://httpbin.org`) and "mounts" it on the local API endpoint `/public/**`.
    45  
    46  An incoming request `/public/foo` will result in an outgoing request `https://httpbin.org/foo`.
    47  
    48  ## Securing APIs
    49  
    50  Access control is controlled by an
    51  [access control](/configuration/access-control) attribute that can be set for many blocks.
    52  
    53  ```hcl
    54  server "example" {
    55  
    56    endpoint "/private/**" {
    57      access_control = ["accessToken"]
    58  
    59      proxy {
    60        backend {
    61          origin = "https://httpbin.org"
    62          path = "/**"
    63        }
    64      }
    65    }
    66  
    67    definitions {
    68      jwt "accessToken" {
    69        signature_algorithm = "RS256"
    70        key_file = "keys/public.pem"
    71        header = "Authorization"
    72      }
    73    }
    74  }
    75  ```
    76  
    77  This configuration protects the endpoint `/private/**` with the access control `"accessToken"` configured in the `definitions` block.
    78  
    79  ## Routing: Path Mapping
    80  
    81  ```hcl
    82  api "my_api" {
    83    base_path = "/api/v1"
    84  
    85    endpoint "/login/**" {
    86      proxy {
    87        backend {
    88          origin = "http://identityprovider:8080"
    89        }
    90      }
    91    }
    92  
    93    endpoint "/cart/**" {
    94      proxy {
    95        url = "http://cartservice:8080/api/v1/**"
    96      }
    97    }
    98  
    99    endpoint "/account/{id}" {
   100      proxy {
   101        backend {
   102          path = "/user/${request.param.id}/info"
   103          origin = "http://accountservice:8080"
   104        }
   105      }
   106    }
   107  }
   108  ```
   109  
   110  | Incoming request       | Outgoing request                              |
   111  |:-----------------------|:----------------------------------------------|
   112  | /api/v1/login/foo      | `http://identityprovider:8080/login/foo`      |
   113  | /api/v1/cart/items     | `http://cartservice:8080/api/v1/items`        |
   114  | /api/v1/account/brenda | `http://accountservice:8080/user/brenda/info` |
   115  
   116  ## Using Variables and Expressions
   117  
   118  An example to send an additional header with client request header to a configured
   119  backend and gets evaluated on per-request basis:
   120  
   121  ```hcl
   122  server {
   123    endpoint "/" {
   124      proxy {
   125        backend {
   126          origin = "https://httpbin.org/"
   127          path = "/anything"
   128          set_request_headers = {
   129            # simple variable lookup
   130            x-uuid = request.id
   131            # template string
   132            user-agent = "myproxyClient/${request.headers.app-version}"
   133            # expressions and function calls
   134            x-env-user = env.USER != "" ? to_upper(env.USER) : "UNKNOWN"
   135          }
   136        }
   137      }
   138    }
   139  }
   140  ```