Skip to content

README.md

Latest commit

 

History

History
387 lines (310 loc) · 10.6 KB

README.md

File metadata and controls

387 lines (310 loc) · 10.6 KB

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.

.NET

Features

Architecture & API

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

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
  1. 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.