# reactiveui/refit architecture

> Architecture diagram of the GitHub repository reactiveui/refit, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-03). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/reactiveui/refit
- Repository: https://github.com/reactiveui/refit

## Overview

##### Project type and purpose
- This is a .NET library that automatically generates type-safe REST API clients (inspired by Square’s Retrofit). Its purpose is to let developers define API interfaces (with HTTP attributes) and then have a “RestService” generate an implementation that makes HTTP calls.
- It includes support for multiple .NET targets (e.g., .NET Core, Xamarin, Blazor) with added integrations such as HttpClientFactory, JSON and XML serialization adapters, and even Roslyn-based source generation for interface stub generation.

##### File structure for major components
- Core Library – the “Refit” directory contains the core API classes (e.g., RestService, RequestBuilder, attributes for HTTP methods, exception handling, etc.).
- Interface Stub Generator – separate projects under InterfaceStubGenerator.Shared and the Roslyn-based versions (Roslyn38 and Roslyn41) indicate a code-generation component. This part is responsible for source generation that auto-implements the defined interfaces.
- Serialization Adapters – separate modules like Refit.Newtonsoft.Json and Refit.Xml show that the library supports different serialization strategies.
- HttpClientFactory Integration – the Refit.HttpClientFactory folder highlights integration with HttpClientFactory for dependency injection and middleware use.
- Testing and Benchmarks – projects like Refit.Tests, Refit.Benchmarks, and Refit.GeneratorTests contain test harnesses, benchmarks, and snapshot validations (for generated stubs). These help validate functionality and performance.
- Samples – under the “samples” folder there are sample projects demonstrating usage, which helps illustrate how consumers integrate with the library.

##### README for additional architectural insights
- The README emphasizes using interface attributes (like [Get], [Post], etc.) and how RestService turns these interfaces into live clients.
- The guidance on HttpClientFactory, DelegatingHandlers (for adding auth tokens), and exception handling points to integration components at runtime.

A. API Interface Definitions (Consumers write these)
- These are plain C# interfaces decorated with attributes (such as [Get], [Post], [Body], and [Headers]).
- They are located (and exemplified) in sample projects and referenced in tests.
B. Refit Core Library
- Contains the RestService class, RequestBuilder, and various attribute definitions.
- Provides common functionality to dynamically generate implementations based on the defined API interfaces.
- Implements the rules for querystring construction, body serialization, static/dynamic headers, etc.
C. Code Generation / Interface Stub Generation
- Represented by the InterfaceStubGenerator projects (including the Roslyn38 and Roslyn41 versions).
- Uses Roslyn-based source generators to produce the client code at compile time.
- This component feeds implementations into the Refit core so that interface calls are wired to HTTP calls.
D. Serialization Adapters
- Refit.Newtonsoft.Json for JSON serialization (with option to use Newtonsoft.Json’s settings).
- Refit.Xml for XML serialization.
- SystemTextJsonContentSerializer is built into the core by default.
E. HttpClientFactory and DelegatingHandlers Integration
- Refit.HttpClientFactory wraps RestService and integrates with ASP.NET Core’s dependency injection using HttpClientFactory.
- This shows additional middleware (like custom DelegatingHandlers) that modify requests (e.g., add authentication).
F. Test Harnesses and Benchmarking
- Refit.Tests and Refit.Benchmarks illustrate how the generated clients are validated and how performance is measured.
G. Samples and Integration Clients
- Sample client setups (like “samples/Meow.Common” and “samples/sampleUsngLocalApi”) that show how the library is used in real applications.

- Additional extension modules such as Refit.HttpClientFactory, Refit.Newtonsoft.Json, and Refit.Xml as plug-in components that augment the core client generation.
- Testing and benchmark components are shown as validating layers that help maintain code quality and performance.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Consumer Layer
    subgraph "Consumer Applications"
        A1["API Interface Definitions"]:::consumer
    end

    %% Generation Layer: Core and Code Generation
    subgraph "Refit Client Generation"
        subgraph "Refit Core Library"
            B1["RestService"]:::core
            B2["RequestBuilder"]:::core
            B3["HTTP Attribute Processing, Header & Query Handling"]:::note
        end
        subgraph "Interface Stub Generator"
            C1["InterfaceStubGenerator.Shared"]:::codegen
            C2["InterfaceStubGenerator.Roslyn38"]:::codegen
            C3["InterfaceStubGenerator.Roslyn41"]:::codegen
        end
    end

    %% Integration Layer: HTTP Client and Serialization
    subgraph "Runtime Integration and Adapters"
         D1["Refit.HttpClientFactory"]:::integration
         subgraph "Serialization Adapters"
             E1["Refit.Newtonsoft.Json"]:::adapter
             E2["Refit.Xml"]:::adapter
             E3["SystemTextJsonContentSerializer"]:::adapter
         end
    end

    %% Validation and Samples Layer
    subgraph "Validation & Usage"
         F1["Refit.Tests"]:::testing
         F2["Refit.Benchmarks"]:::testing
         F3["Refit.GeneratorTests"]:::testing
         subgraph "Samples"
            G1["samples/sampleUsngLocalApi"]:::sample
            G2["samples/Meow.Common"]:::sample
         end
    end

    %% Relationships
    A1 -->|"RestService.For<T>"| B1
    A1 -->|"SourceGeneration_via_Roslyn"| C1
    A1 -->|"SourceGeneration_via_Roslyn"| C2
    A1 -->|"SourceGeneration_via_Roslyn"| C3

    C1 -->|"Generates Client_Impl"| B1
    C2 -->|"Generates Client_Impl"| B1
    C3 -->|"Generates Client_Impl"| B1

    B2 --- B1
    B3 --- B1

    B1 -->|"Integrates_with"| D1
    B1 -->|"Uses"| E1
    B1 -->|"Uses"| E2
    B1 -->|"Uses"| E3

    %% Testing connections
    B1 --- F1
    B1 --- F2
    B1 --- F3
    C1 --- F1
    C1 --- F2
    C1 --- F3

    %% Samples consumption
    G1 -->|"Consumes_Client"| B1
    G2 -->|"Consumes_Client"| B1

    %% Click Events
    click A1 "https://github.com/reactiveui/refit/blob/main/samples/sampleUsngLocalApi/LibraryWithSDKandRefitService/IRestService.cs"
    click B1 "https://github.com/reactiveui/refit/blob/main/Refit/RestService.cs"
    click B2 "https://github.com/reactiveui/refit/blob/main/Refit/RequestBuilder.cs"
    click C1 "https://github.com/reactiveui/refit/blob/main/InterfaceStubGenerator.Shared"
    click C2 "https://github.com/reactiveui/refit/blob/main/InterfaceStubGenerator.Roslyn38"
    click C3 "https://github.com/reactiveui/refit/blob/main/InterfaceStubGenerator.Roslyn41"
    click E1 "https://github.com/reactiveui/refit/blob/main/Refit.Newtonsoft.Json"
    click E2 "https://github.com/reactiveui/refit/blob/main/Refit.Xml"
    click E3 "https://github.com/reactiveui/refit/blob/main/Refit/SystemTextJsonContentSerializer.cs"
    click D1 "https://github.com/reactiveui/refit/blob/main/Refit.HttpClientFactory/HttpClientFactoryExtensions.cs"
    click F1 "https://github.com/reactiveui/refit/blob/main/Refit.Tests"
    click F2 "https://github.com/reactiveui/refit/blob/main/Refit.Benchmarks"
    click F3 "https://github.com/reactiveui/refit/blob/main/Refit.GeneratorTests"
    click G1 "https://github.com/reactiveui/refit/tree/main/samples/sampleUsngLocalApi"
    click G2 "https://github.com/reactiveui/refit/blob/main/samples/Meow.Common"

    %% Styles
    classDef consumer fill:#f9c,stroke:#333,stroke-width:2px;
    classDef core fill:#bbf,stroke:#333,stroke-width:2px;
    classDef note fill:#eef,stroke:#333,stroke-width:2px,stroke-dasharray: 5 5;
    classDef codegen fill:#cfc,stroke:#333,stroke-width:2px;
    classDef integration fill:#fc9,stroke:#333,stroke-width:2px;
    classDef adapter fill:#cff,stroke:#333,stroke-width:2px;
    classDef testing fill:#fdd,stroke:#333,stroke-width:2px;
    classDef sample fill:#dfd,stroke:#333,stroke-width:2px;
```
