Docu refinements

README.md

@@ -10,12 +10,11 @@
 
 ## Getting started
 
-* Check out our [example repository](https://github.com/avenga/couper-examples) for a first glance.
-* Read more about our use-cases on [couper.io](https://couper.io).
 * The quickest way to start is to use our [Docker image](https://hub.docker.com/r/avenga/couper).
-* Continue with the [documentation](https://github.com/avenga/couper/tree/master/docs).
+* The [documentation](https://github.com/avenga/couper/tree/master/docs) gives an introduction to Couper.
+* Check out the [example repository](https://github.com/avenga/couper-examples) to learn about Couper's features in detail.
 * Dive into the [Configuration Reference](docs/REFERENCE.md)
-
+* Use-cases can be found on [couper.io](https://couper.io).
 
 ## Features
 
@@ -29,24 +28,22 @@ Couper …
 
 Key features are:
 
-* **Easy configuration** powered by [HCL 2](https://github.com/hashicorp/hcl/tree/hcl2)
-* Exposes local and remote backend services in a consolidated frontend API
-* Operation and **observability**:
-  * Timeout handling
-  * Logging access and upstream requests as tab fields or json format
-* Centralized **Access-Control** layer:
+* **Easy Configuration & Deployment**
+* HTTP Request Routing / Forwarding
+* Custom Requests and Responses
+* Request / Response Manipulation
+* Centralized **Access-Control** Layer:
   * Basic-Auth
-  * JWT
-    * RS/HS 256,386,512 algorithms
-    * Custom claim validation
-    * pass claim values to upstream services
-   * Single Sign On with SAML2
-* Uniform **error handling** with custom templates across different backend services
-  * api endpoints serving a json error response, defaults to html otherwise
-* **SPA** support with configurable path fallbacks
-
-The full list of features of Couper 1.0 is [here](FEATURES.md).
-
+  * JWT  Validation & Signing
+  * Single Sign On with SAML2
+  * OAuth2 Client Credentials
+* **Configurable Service Connectivity**
+* Upstream Validation & CORS
+* SPA & Web Serving
+* Error Handling
+* Observability
+
+The full list of features of Couper 1.0 is [here](FEATURES.md) or at [https://couper.io/features](https://couper.io/features).
 
 ## Contributing
 

docs/README.md

@@ -18,7 +18,7 @@
 
 Couper is a lightweight open-source API gateway that acts as an entry point for clients to your application (frontend API gateway) and an exit point to upstream services (upstream API gateway).
 
-It exposes endpoints with use cases and adds access control, observability, and back-end connectivity on a separate layer. This will keep your core application code more simple.
+It adds access control, observability, and back-end connectivity on a separate layer. This will keep your core application code more simple.
 
 Couper does not need any special development skills and offers easy configuration and integration.
 
@@ -58,18 +58,17 @@ Copy/paste the following configuration to the file and save it.
 ```hcl
 server "hello" {
   endpoint "/**" {
-        response {
-            body = "Hello World!"
-        }
+    response {
+      body = "Hello World!"
     }
+  }
 }
 ```
 
 Now `cd` into the directory with the configuration file and start Couper in a docker container:
 
 ```sh
 $ docker run --rm -p 8080:8080 -v "$(pwd)":/conf avenga/couper
-
 {"addr":"0.0.0.0:8080","level":"info","message":"couper gateway is serving","timestamp":"2020-08-27T16:39:18Z","type":"couper"}
 ```
 
@@ -78,10 +77,18 @@ browser or `curl` to [`localhost:8080`](http://localhost:8080/) to see what's go
 
 Press `CTRL+c` to stop the container.
 
+The [following section](#configuration-file) will give you an introduction into Couper's configuration file.  
+
+[Here](./REFERENCE.md) you will find the full configuration reference.
+
+If you prefer to learn about Couper by checking out certain features, visit the [example repository](https://github.com/avenga/couper-examples).
+
 ## Configuration File
 
 The language for Couper's configuration file is [HCL 2.0](https://github.com/hashicorp/hcl/tree/hcl2#information-model-and-syntax), a configuration language by HashiCorp.
 
+**⚠ Couper's configuration reference can be found [here](./REFERENCE.md).**
+
 ### IDE Extension
 
 Couper provides its own IDE extension that adds Couper-specific highlighting and autocompletion to Couper's configuration file `couper.hcl` in Visual Studio Code.

docs/REFERENCE.md

@@ -321,7 +321,6 @@ required _label_.
 |Context|Label|Nested block(s)|
 | :-----------| :-----------| :-----------|
 | [Definitions Block](#definitions-block)| ⚠ required |-|
-<!-- warum claims fett?-->
 | Attribute(s) | Type |Default|Description|Characteristic(s)| Example|
 | :------------------------------ | :--------------- | :--------------- | :--------------- | :--------------- | :--------------- |
 | `cookie`  |string|-|Read `AccessToken` key to gain the token value from a cookie.|&#9888; available value: `AccessToken`|`cookie = "AccessToken"`|
@@ -377,7 +376,7 @@ required _label_.
 
 To configure protection of the OAuth2 flow against Cross-Site Request Forgery (CSRF) use either the `pkce` or the `csrf` block. If the authorization server supports PKCE, we recommend `pkce`.
 
-##### PKCE Block
+#### PKCE Block
 
 Use PKCE (Proof Key for Code Exchange) as defined in [RFC 7636](https://datatracker.ietf.org/doc/html/rfc7636) for protection against CSRF and code injection.
 
@@ -390,7 +389,7 @@ Use PKCE (Proof Key for Code Exchange) as defined in [RFC 7636](https://datatrac
 | `code_challenge_method` | string | - | The method to calculate the PKCE code challenge. |&#9888; required, available values: `S256` or (not recommended) `plain`|-|
 | `code_verifier_value` | string or expression | - | The value of the code verifier. |&#9888; required; e.g. using cookie value created with [`beta_oauth_code_verifier()` function](#functions)|`code_verifier_value = request.cookies.code_verifier` |
 
-##### CSRF Block
+#### CSRF Block
 
 Use `state` or `nonce` for protection against CSRF.
 
@@ -506,20 +505,22 @@ For a [JWT Block](#jwt-block), the variable contains claims from the JWT used fo
 
 For a [SAML Block](#saml-block), the variable contains
 
- - `sub`: the `NameID` of the SAML assertion
- - `exp`: optional expiration date (value of `SessionNotOnOrAfter` of the SAML assertion)
- - `attributes`: a map of attributes from the SAML assertion
+- `sub`: the `NameID` of the SAML assertion
+- `exp`: optional expiration date (value of `SessionNotOnOrAfter` of the SAML assertion)
+- `attributes`: a map of attributes from the SAML assertion
 
 For an [OAuth2 AC Block](#oauth2-ac-block), the variable contains the response from the token endpoint, e.g.
- - `access_token`: the access token retrieved from the token endpoint
- - `token_type`: the token type
- - `expires_in`: the token lifetime
- - `scope`: the granted scope (if different from the requested scope)
+
+- `access_token`: the access token retrieved from the token endpoint
+- `token_type`: the token type
+- `expires_in`: the token lifetime
+- `scope`: the granted scope (if different from the requested scope)
 
 and for OIDC additionally:
- - `id_token`: the ID token
- - `id_token_claims`: a map of claims from the ID token
- - `userinfo`: a map of claims retrieved from the userinfo endpoint
+
+- `id_token`: the ID token
+- `id_token_claims`: a map of claims from the ID token
+- `userinfo`: a map of claims retrieved from the userinfo endpoint
 
 ### `backend_requests`