DotNet API Boilerplate

Overview

This project is a boilerplate for building .NET API applications with various features such as authentication, rate limiting, CORS, and logging using Serilog.

Features

Architecture & API

• Vertical Slicing Architecture
• Minimal API
• Swagger
• Health check endpoint
• Middlewares
• Entity Framework Core with SQLite

Authentication & Authorization

• Authentication using JWT Bearer tokens
• Authorization with role-based access control
• CORS policies for secure cross-origin requests
• Rate limiting to prevent API abuse

Validation & Logging

• FluentValidation
• Logging with Serilog
• Serilog with structured logging

Performance & Resiliency

• Response caching and compression
• Performance
  • Response Compression
  • Response Caching
  • GraphQL query optimization
  • DataLoaders for efficient data fetching

GraphQL API with HotChocolate

• Professional architecture with clean separation
• Complete blog management domain (Blogs, Posts, Comments)
• DataLoaders for N+1 query prevention
• Real-time subscriptions with Redis
• Built-in GraphQL Playground and Schema explorer
• Query complexity analysis and rate limiting
• Field-level authorization support
• Comprehensive error handling
• Performance monitoring and observability

Deployment & CI/CD

• Docker
• Podman
• CloudFormation
• Github Action

Integrations

• Vault Integration
• MQ Integration

Getting Started

Prerequisites

• .NET 9 SDK
• Keycloak for authentication

Installation

1. Clone the repository:

   git clone https://github.com/FullstackCodingGuy/netapi-boilerplate.git
   cd netapi-boilerplate

2. Install the required NuGet packages:

   dotnet restore

3. Update the appsettings.json and appsettings.Development.json files with your configuration.

Running the Application

1. Build and run the application:

   dotnet run
   
   or
   
   dotnet run --launch-profile "https"
   

1.1 Setting cert

dotnet dev-certs https -ep ${HOME}/.aspnet/https/dotnetapi-boilerplate.pfx -p mypassword234
dotnet dev-certs https --trust

Running with Docker

// To build the image
docker-compose build

// To run the container
docker-compose up

// To kill container
docker-compose down

2. The application will be available at http://localhost:8000 and https://localhost:8001 (or the configured URL).

Health Check Endpoint

The application includes a health check endpoint to verify that the API is running. You can access it at:

GET /health

This will return a simple "Healthy" message.

GraphQL API

This boilerplate includes a comprehensive GraphQL implementation using HotChocolate, designed with professional architecture patterns and enterprise-grade features.

GraphQL Features

🏗️ Professional Architecture

• Clean Architecture: Vertical slicing with clear separation of concerns
• Domain-Driven Design: Blog management domain with Blogs, Posts, and Comments
• Repository Pattern: Abstracted data access with Entity Framework Core
• Service Layer: Business logic separation with comprehensive services

🚀 Core GraphQL Capabilities

• Complete CRUD Operations: Full Create, Read, Update, Delete support
• Advanced Querying: Complex filtering, sorting, and pagination
• Real-time Subscriptions: Live updates using Redis as message broker
• Field-level Authorization: Granular security control
• Input Validation: Comprehensive data validation and sanitization

⚡ Performance Optimization

• DataLoaders: Automatic N+1 query prevention with batch loading
• Query Complexity Analysis: Protection against expensive queries
• Response Caching: Intelligent caching strategies
• Database Optimization: Efficient EF Core queries with projections

🔐 Security & Observability

• JWT Authentication: Seamless integration with existing auth
• Role-based Authorization: Fine-grained access control
• Rate Limiting: GraphQL-specific rate limiting
• Comprehensive Logging: Structured logging with Serilog
• Error Handling: Professional error responses with detailed context

🛠️ Developer Experience

• Built-in GraphQL Playground: Interactive query interface at /graphql
• Schema Explorer: Full schema documentation and introspection
• Type Safety: Strongly typed resolvers and models
• Extensible Design: Easy to add new types and features

GraphQL Endpoints

Main GraphQL Endpoint

POST /graphql

• Primary endpoint for all GraphQL operations
• Supports queries, mutations, and subscriptions
• Built-in GraphQL Playground available in development

GraphQL Playground (Development)

GET /graphql

• Interactive GraphQL IDE
• Schema exploration and documentation
• Query testing and validation
• Real-time subscription testing

Example Queries

Get All Blogs with Posts

query GetBlogsWithPosts {
  blogs {
    id
    name
    description
    posts {
      id
      title
      content
      author {
        name
        email
      }
      comments {
        id
        content
        author
      }
    }
  }
}

Create a New Blog

mutation CreateBlog {
  createBlog(input: {
    name: "Tech Blog"
    description: "A blog about technology"
    author: "John Doe"
    tags: ["tech", "programming"]
  }) {
    blog {
      id
      name
      description
      author
      tags
      createdAt
    }
    errors {
      message
    }
  }
}

Subscribe to New Posts

subscription NewPosts {
  onPostCreated {
    id
    title
    content
    blog {
      name
    }
    author {
      name
    }
  }
}

Complex Query with Filtering

query SearchPosts {
  posts(
    where: {
      and: [
        { title: { contains: "GraphQL" } }
        { isPublished: { eq: true } }
        { createdAt: { gte: "2024-01-01" } }
      ]
    }
    order: [{ createdAt: DESC }]
    take: 10
  ) {
    id
    title
    content
    blog {
      name
    }
    commentCount
    viewCount
  }
}

Architecture Overview

Features/GraphQL/
├── Configuration/          # GraphQL server configuration
│   └── GraphQLConfiguration.cs
├── Models/                 # GraphQL types and DTOs
│   ├── BlogType.cs
│   ├── PostType.cs
│   ├── CommentType.cs
│   └── AuthorType.cs
├── Services/              # Business logic services
│   ├── IBlogService.cs
│   ├── BlogService.cs
│   ├── IPostService.cs
│   └── PostService.cs
├── Resolvers/             # GraphQL resolvers
│   ├── Query.cs           # Query operations
│   ├── Mutation.cs        # Mutation operations
│   ├── Subscription.cs    # Real-time subscriptions
│   └── FieldResolvers.cs  # Field-level resolvers
└── DataLoaders/           # Performance optimization
    ├── BlogDataLoaders.cs
    └── PostDataLoaders.cs

Performance Features

DataLoaders

Automatically batches and caches database queries to prevent N+1 problems:

• BlogByIdDataLoader: Efficient blog loading by ID
• PostsByBlogIdDataLoader: Batch loading of posts by blog
• CommentsByPostIdDataLoader: Efficient comment loading

Query Complexity Analysis

Protects against expensive queries with configurable limits:

• Maximum query depth: 10 levels
• Maximum query complexity: 1000 points
• Field introspection limits in production

Caching Strategy

Multi-level caching for optimal performance:

• DataLoader-level caching (request scoped)
• Service-level caching for expensive operations
• Response caching for static data

Getting Started with GraphQL

1. Start the application:

   dotnet run

2. Open GraphQL Playground: Navigate to http://localhost:8000/graphql

3. Explore the Schema: Use the schema explorer to understand available types and operations

4. Try Sample Queries: Copy and paste the example queries above

5. Test Real-time Features: Open multiple browser tabs to test subscriptions

Configuration

GraphQL is configured in Features/GraphQL/Configuration/GraphQLConfiguration.cs with:

• HotChocolate Server: Latest version with all features enabled
• Entity Framework Integration: Automatic query translation
• Redis Subscriptions: Real-time capabilities
• Authentication Integration: JWT token validation
• Error Handling: Professional error responses
• Performance Monitoring: Query execution tracking

Best Practices Implemented

• Single Responsibility: Each resolver handles one concern
• Dependency Injection: All services properly registered
• Async/Await: Non-blocking operations throughout
• Error Boundaries: Comprehensive error handling
• Type Safety: Strong typing for all operations
• Documentation: Inline documentation for all types
• Testing Ready: Architecture supports unit and integration testing

This GraphQL implementation provides a solid foundation for building modern, efficient APIs with excellent developer experience and enterprise-grade performance.

Logging with Serilog

Serilog is configured to log to the console and a file with daily rotation. You can customize the logging settings in the serilog.json file.

Example configuration in Program.cs:

Log.Logger = new LoggerConfiguration()
    .WriteTo.Console()   // Log to console
    .WriteTo.File("logs/api-log.txt", rollingInterval: RollingInterval.Day) // Log to a file (daily rotation)
    .Enrich.FromLogContext()
    .MinimumLevel.Information()
    .CreateLogger();

builder.Host.UseSerilog();

Additional Configuration

• Authentication: Configure the JWT Bearer options in Program.cs to match your Keycloak settings.
• CORS: Update the CORS policies in Program.cs to match your frontend URLs.
• Rate Limiting: Adjust the rate limiting settings in Program.cs as needed.