Add comprehensive link handling and serializer documentation

[Copilot]

Extends TypedRest documentation with detailed coverage of link navigation mechanisms and serialization formats across .NET and TypeScript implementations.

New Pages

• relative-uris.md - Hard-coded relative URIs and the non-standard ./ prefix pattern for trailing slash handling
• uri-templates.md - RFC 6570 URI template resolution, server-provided templates, and built-in defaults in Collection/Indexer endpoints
• link-header.md - RFC 8288 Link header extraction with GetLinks()/Link() methods and the non-standard templated=true extension
• hal.md - HAL (application/hal+json) link extraction, multiple/templated links, and AggregateLinkExtractor for combining sources
• serializers.md - Format support matrix (JSON/XML/BSON), System.Text.Json via separate NuGet package, custom TypeScript serializers, and +json suffix handling

Updated Pages

• link-handling/index.md - Expanded to overview page with link resolution method descriptions and navigation to all subtopics
• endpoints/index.md - Added "Navigating Between Endpoints" section explaining referrer parameter inheritance and linking to link-handling docs

Format

All code examples use tabbed format for C# and TypeScript:

=== "C#"
    ```csharp
    var contacts = new CollectionEndpoint<Contact>(client, relativeUri: "./contacts");
    var searchUri = contacts.LinkTemplate("search", new {name = "Smith"});
    ```

=== "TypeScript"
    ```typescript
    const contacts = new CollectionEndpoint<Contact>(client, "./contacts");
    const searchUri = contacts.linkTemplate("search", {name: "Smith"});
    ```

Documentation focuses on TypedRest-specific usage rather than duplicating RFC specifications.

Original prompt

Overview

Extend the TypedRest documentation with additional pages covering link handling features and serializers. The documentation should cover multiple language implementations (.NET and TypeScript) using the existing tabbed code example format.

New Pages to Create

1. docs/link-handling/relative-uris.md

Document hard-coded relative URIs between endpoints, including:

• Basic usage of relative URIs
• The non-standard ./ prefix pattern for appending trailing slashes to parent URIs before resolving relative URIs
• Examples showing the difference between "subresource" and "./subresource"
• When to use the ./ prefix
• Default links via SetDefaultLink

2. docs/link-handling/uri-templates.md

Document URI templates:

• Link to RFC 6570 for template syntax details (don't duplicate RFC content)
• Focus on how to use templates in TypedRest
• Server-provided templates via Link header and HAL
• Resolving templates with LinkTemplate() method
• Default link templates via SetDefaultLinkTemplate
• Built-in defaults in Collection/Indexer endpoints

3. docs/link-handling/link-header.md

Document links transmitted via HTTP Link Header:

• Link header format per RFC 8288
• Extracting links with GetLinks() and Link() methods
• The non-standard templated=true extension for URI templates in headers
• Supported link header attributes (rel, title, templated)

4. docs/link-handling/hal.md

Document links encoded in resources via HAL:

• Link to HAL specification (don't duplicate spec content)
• Focus on how to use HAL in TypedRest
• Content type application/hal+json
• Using HAL links with standard link resolution methods
• Multiple links and templated links in HAL
• Combining with header links via AggregateLinkExtractor

5. docs/link-handling/serializers.md

Document serializers with a table showing which formats are supported by which TypedRest version:

Format	.NET	TypeScript
JSON (Newtonsoft.Json)	✅ Default	❌
JSON (System.Text.Json)	✅ Separate NuGet	❌
JSON (Native)	❌	✅ Default
XML	✅	❌
BSON	✅	❌

Include:

• Configuration options for each serializer
• How to use System.Text.Json via TypedRest.SystemTextJson NuGet package
• Custom serializers in TypeScript
• Custom JSON media types (+json suffix handling)

Files to Update

docs/link-handling/index.md

Expand the current brief list into a proper overview with:

• Links to all new pages
• Brief description of link resolution methods (GetLinks, Link, LinkTemplate)
• Reference to serializers page

docs/link-handling/.pages

Create navigation file:

nav:
  - index.md
  - relative-uris.md
  - uri-templates.md
  - link-header.md
  - hal.md
  - serializers.md

docs/endpoints/index.md

Add a new section "Navigating Between Endpoints" at the end that:

• Explains the referrer parameter inherits configuration including serializers
• Lists the different ways to link endpoints (relative URIs, URI templates, Link headers, HAL)
• Links to the link-handling documentation

Code Examples

All code examples should use the existing tabbed format with both C# and TypeScript versions:

=== "C#"

    ```csharp
    // C# example
    ```

=== "TypeScript"

    ```typescript
    // TypeScript example
    ```

Reference Implementation Details

Relative URI ./ Pattern

From .NET UriExtensions.cs:

=> new(relativeUri.StartsWith("./") ? baseUri.EnsureTrailingSlash() : baseUri, relativeUri);

From TypeScript Endpoint.ts:

protected join(relativeUri: string): URL {
    return new URL(
        relativeUri,
        relativeUri.startsWith("./") ? Endpoint.ensureTrailingSlash(this.uri) : this.uri);
}

Link Template Support in Headers

The HeaderLinkExtractor in both implementations parses templated=true from Link headers - this is a non-standard extension.

HAL Link Extraction

Both implementations use HalLinkExtractor that looks for application/hal+json content type and parses _links objects.

Serializers

• .NET: NewtonsoftJsonSerializer (default), SystemTextJsonSerializer (separate package), XmlSerializer, BsonSerializer
• TypeScript: JsonSerializer (default, uses native JSON.parse/stringify)

This pull request was created from Copilot chat.

---

💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more Copilot coding agent tips in the docs.