Extended documentation

Author: bastianeicher

docs/.pages

@@ -3,6 +3,7 @@ nav:
   - introduction.md
   - getting-started
   - endpoints
+  - serializers
   - error-handling
   - link-handling
   - code-generation

docs/endpoints/index.md

@@ -30,4 +30,4 @@ TypedRest provides a number of endpoint types modelling common REST patterns. Mo
 - [Streaming endpoint](reactive/streaming.md) - stream of entities via persistent connection
 - [Streaming Collection endpoint](reactive/streaming-collection.md) - collection of entities observable as append-only stream
 
-The constructors of all endpoints except entry endpoints take a `referrer` parameter. This is uses to inherit relative URI bases and configuration such as [error handling](../error-handling/index.md) and [link handling](../link-handling/index.md).
+The constructors of all endpoints (except entry endpoints) take a `referrer` parameter. This is used to inherit [relative URI bases](../link-handling/index.md), [serializers](../serializers/index.md) and [error handling](../error-handling/index.md).

docs/index.md

@@ -115,6 +115,9 @@ TypedRest helps you build type-safe, fluent-style REST API clients. Common REST
 [Endpoints](endpoints/index.md)
 : Documentation for all endpoint types provided by TypedRest.
 
+[Serializers](serializers/index.md)
+: How to convert objects to and from the wire format (e.g., JSON).
+
 [Error handling](error-handling/index.md)
 : How to handle API errors with TypedRest.
 

docs/link-handling/.pages

@@ -0,0 +1,7 @@
+nav:
+  - index.md
+  - relative-uris.md
+  - uri-templates.md
+  - link-header.md
+  - hal.md
+  - serializers.md

docs/link-handling/hal.md

@@ -0,0 +1,130 @@
+# HAL (Hypertext Application Language)
+
+TypedRest supports extracting links from response bodies using the [HAL specification](https://datatracker.ietf.org/doc/html/draft-kelly-json-hal). HAL provides a consistent format for embedding links and embedded resources within JSON responses.
+
+## HAL format
+
+HAL adds a `_links` object to JSON responses containing links organized by relation type:
+
+```json
+{
+    "id": 123,
+    "name": "John Doe",
+    "_links": {
+        "self": { "href": "/users/123" },
+        "orders": { "href":  "/users/123/orders" },
+        "search": { "href":  "/users/{id}", "templated": true }
+    }
+}
+```
+
+## Content Type
+
+TODO: Check the content type is actually used
+
+TypedRest recognizes HAL responses by the `application/hal+json` content type:
+
+```
+Content-Type: application/hal+json
+```
+
+When this content type is present, TypedRest automatically parses the `_links` object and makes the links available through the standard link resolution methods.
+
+## Using HAL links
+
+After receiving a HAL response, you can resolve links just like with HTTP Link headers:
+
+TODO: Check code samples
+
+=== "C#"
+
+    ```csharp
+    await endpoint.ReadAsync();
+
+    // Resolve a single link
+    Uri ordersUri = endpoint.Link("orders");
+
+    // Resolve a templated link
+    Uri userUri = endpoint.LinkTemplate("search", new { id = "456" });
+    ```
+
+=== "TypeScript"
+
+    ```typescript
+    await endpoint.read();
+
+    // Resolve a single link
+    const ordersUri = endpoint.link("orders");
+
+    // Resolve a templated link
+    const userUri = endpoint.linkTemplate("search", { id: "456" });
+    ```
+
+## Multiple links
+
+HAL supports multiple links for the same relation type using an array:
+
+```json
+{
+    "_links": {
+        "item": [
+            { "href": "/items/1", "title": "First Item" },
+            { "href": "/items/2", "title": "Second Item" }
+        ]
+    }
+}
+```
+
+Retrieve all links with `GetLinks`:
+
+TODO: Check code samples
+
+=== "C#"
+
+    ```csharp
+    var items = endpoint.GetLinks("item");
+    foreach (var (uri, title) in items)
+    {
+        Console.WriteLine($"{title}: {uri}");
+    }
+    ```
+
+=== "TypeScript"
+
+    ```typescript
+    const items = endpoint.getLinks("item");
+    for (const { uri, title } of items) {
+        console.log(`${title}: ${uri}`);
+    }
+    ```
+
+## Templated links
+
+HAL links can be marked as [templates](uri-templates.md) with the `templated` property:
+
+```json
+{
+    "_links": {
+        "find": {
+            "href": "/users{?name,email}",
+            "templated": true
+        }
+    }
+}
+```
+
+TODO: Check code samples
+
+=== "C#"
+
+    ```csharp
+    var findUri = endpoint.LinkTemplate("find", new { name = "John", email = "john@example.com" });
+    // Result: /users?name=John&email=john%40example.com
+    ```
+
+=== "TypeScript"
+
+    ```typescript
+    const findUri = endpoint.linkTemplate("find", { name: "John", email: "john@example.com" });
+    // Result: /users? name=John&email=john%40example.com
+    ```

docs/link-handling/index.md

@@ -1,8 +1,26 @@
 # Link handling
 
-TypedRest supports a variety of different links:
+TypedRest supports a variety of different ways to establish links between [endpoints](../endpoints/index.md):
 
-- Hard-coded relative URIs between [endpoints](../endpoints/index.md)
-- Links transmitted via the HTTP Link Header
-- Links encoded in resources via HAL
-- URI templates
+- [Hard-coded relative URIs](relative-uris.md)
+- [URI templates](uri-templates.md) for dynamic URL construction
+- [Links via HTTP Link Header](link-header.md) transmitted in response headers
+- [Links encoded in resources via HAL](hal.md) for hypermedia-driven APIs
+
+## Link resolution
+
+All endpoints provide methods for resolving links:
+
+=== "C#"
+
+    - `GetLinks(rel)` - Resolves all links with a specific relation type
+    - `Link(rel)` - Resolves a single link with a specific relation type
+    - `LinkTemplate(rel, variables)` - Resolves a link template with variables
+
+=== "TypeScript"
+
+    - `getLinks(rel)` - Resolves all links with a specific relation type
+    - `link(rel)` - Resolves a single link with a specific relation type
+    - `linkTemplate(rel, variables)` - Resolves a link template with variables
+
+These methods use cached data from the last response. On cache miss, they perform a lazy lookup using HTTP `HEAD`.

docs/link-handling/link-header.md

@@ -0,0 +1,96 @@
+# HTTP Link header
+
+TypedRest can extract links from HTTP `Link` headers as defined in [RFC 8288](https://tools.ietf. org/html/rfc8288). This enables HATEOAS-style navigation where the server provides links to related resources in response headers.
+
+## Header format
+
+The HTTP `Link` header follows this format:
+
+```
+Link: <target-uri>; rel="relation-type"; title="optional title"
+```
+
+Multiple links can be specified in a single header, separated by commas:
+
+```
+Link: <http://example.com/users>; rel=collection, <http://example.com/user/123>; rel=self
+```
+
+## Extracting links
+
+TypedRest automatically extracts links from response headers after each request. You can then resolve them:
+
+TODO: Check code samples
+
+=== "C#"
+
+    ```csharp
+    // Perform a request
+    await endpoint.ReadAsync();
+
+    // Get all links with a specific relation type
+    var links = endpoint.GetLinks("collection");
+    foreach (var (uri, title) in links)
+    {
+        Console.WriteLine($"URI: {uri}, Title: {title}");
+    }
+
+    // Get a single link
+    Uri collectionUri = endpoint. Link("collection");
+    ```
+
+=== "TypeScript"
+
+    ```typescript
+    // Perform a request
+    await endpoint.read();
+
+    // Get all links with a specific relation type
+    const links = endpoint.getLinks("collection");
+    for (const { uri, title } of links) {
+        console.log(`URI: ${uri}, Title: ${title}`);
+    }
+
+    // Get a single link
+    const collectionUri = endpoint.link("collection");
+    ```
+
+## Templated links
+
+TypedRest extends the standard Link header format to support [URI templates](uri-templates.md). Templates are indicated with `templated=true`:
+
+```
+Link: </users/{id}>; rel=user; templated=true
+```
+
+This is a non-standard extension, but it allows servers to provide dynamic link templates via headers without needing HAL or another hypermedia format in the response body.
+
+=== "C#"
+
+    ```csharp
+    // Server response:
+    // Link: </users/{id}>; rel=user; templated=true
+
+    var userUri = endpoint.LinkTemplate("user", new { id = "123" });
+    // Result: http://example.com/users/123
+    ```
+
+=== "TypeScript"
+
+    ```typescript
+    // Server response:
+    // Link: </users/{id}>; rel=user; templated=true
+
+    const userUri = endpoint.linkTemplate("user", { id: "123" });
+    // Result: http://example.com/users/123
+    ```
+
+## Link header attributes
+
+The following attributes are supported:
+
+| Attribute    | Description                                        |
+|--------------|----------------------------------------------------|
+| `rel`        | The relation type (required)                       |
+| `title`      | Human-readable title for the link (optional)       |
+| `templated`  | Indicates a URI template when set to `true` (non-standard) |