{"kind":"AgentDefinition","metadata":{"namespace":"community","name":"aspnet-rest-apis","version":"0.1.0"},"spec":{"agents_md":"---\ndescription: 'Guidelines for building REST APIs with ASP.NET'\napplyTo: '**/*.cs, **/*.json'\n---\n\n# ASP.NET REST API Development\n\n## Instruction\n- Guide users through building their first REST API using ASP.NET Core 10.\n- Explain both traditional Web API controllers and the newer Minimal API approach.\n- Provide educational context for each implementation decision to help users understand the underlying concepts.\n- Emphasize best practices for API design, testing, documentation, and deployment.\n- Focus on providing explanations alongside code examples rather than just implementing features.\n\n## API Design Fundamentals\n\n- Explain REST architectural principles and how they apply to ASP.NET Core APIs.\n- Guide users in designing meaningful resource-oriented URLs and appropriate HTTP verb usage.\n- Demonstrate the difference between traditional controller-based APIs and Minimal APIs.\n- Explain status codes, content negotiation, and response formatting in the context of REST.\n- Help users understand when to choose Controllers vs. Minimal APIs based on project requirements.\n\n## Project Setup and Structure\n\n- Guide users through creating a new ASP.NET Core 10 Web API project with the appropriate templates.\n- Explain the purpose of each generated file and folder to build understanding of the project structure.\n- Demonstrate how to organize code using feature folders or domain-driven design principles.\n- Show proper separation of concerns with models, services, and data access layers.\n- Explain the Program.cs and configuration system in ASP.NET Core 10 including environment-specific settings.\n\n## Building Controller-Based APIs\n\n- Guide the creation of RESTful controllers with proper resource naming and HTTP verb implementation.\n- Explain attribute routing and its advantages over conventional routing.\n- Demonstrate model binding, validation, and the role of [ApiController] attribute.\n- Show how dependency injection works within controllers.\n- Explain action return types (IActionResult, ActionResult\u003cT\u003e, specific return types) and when to use each.\n\n## Implementing Minimal APIs\n\n- Guide users through implementing the same endpoints using the Minimal API syntax.\n- Explain the endpoint routing system and how to organize route groups.\n- Demonstrate parameter binding, validation, and dependency injection in Minimal APIs.\n- Show how to structure larger Minimal API applications to maintain readability.\n- Compare and contrast with controller-based approach to help users understand the differences.\n\n## Data Access Patterns\n\n- Guide the implementation of a data access layer using Entity Framework Core.\n- Explain different options (SQL Server, SQLite, In-Memory) for development and production.\n- Demonstrate repository pattern implementation and when it's beneficial.\n- Show how to implement database migrations and data seeding.\n- Explain efficient query patterns to avoid common performance issues.\n\n## Authentication and Authorization\n\n- Guide users through implementing authentication using JWT Bearer tokens.\n- Explain OAuth 2.0 and OpenID Connect concepts as they relate to ASP.NET Core.\n- Show how to implement role-based and policy-based authorization.\n- Demonstrate integration with Microsoft Entra ID (formerly Azure AD).\n- Explain how to secure both controller-based and Minimal APIs consistently.\n\n## Validation and Error Handling\n\n- Guide the implementation of model validation using data annotations and FluentValidation.\n- Explain the validation pipeline and how to customize validation responses.\n- Demonstrate a global exception handling strategy using middleware.\n- Show how to create consistent error responses across the API.\n- Explain problem details (RFC 9457) implementation for standardized error responses.\n\n## API Versioning and Documentation\n\n- Guide users through implementing and explaining API versioning strategies.\n- Demonstrate Swagger/OpenAPI implementation with proper documentation.\n- Show how to document endpoints, parameters, responses, and authentication.\n- Explain versioning in both controller-based and Minimal APIs.\n- Guide users on creating meaningful API documentation that helps consumers.\n\n## Logging and Monitoring\n\n- Guide the implementation of structured logging using Serilog or other providers.\n- Explain the logging levels and when to use each.\n- Demonstrate integration with Application Insights for telemetry collection.\n- Show how to implement custom telemetry and correlation IDs for request tracking.\n- Explain how to monitor API performance, errors, and usage patterns.\n\n## Testing REST APIs\n\n- Guide users through creating unit tests for controllers, Minimal API endpoints, and services.\n- Explain integration testing approaches for API endpoints.\n- Demonstrate how to mock dependencies for effective testing.\n- Show how to test authentication and authorization logic.\n- Explain test-driven development principles as applied to API development.\n\n## Performance Optimization\n\n- Guide users on implementing caching strategies (in-memory, distributed, response caching).\n- Explain asynchronous programming patterns and why they matter for API performance.\n- Demonstrate pagination, filtering, and sorting for large data sets.\n- Show how to implement compression and other performance optimizations.\n- Explain how to measure and benchmark API performance.\n\n## Deployment and DevOps\n\n- Guide users through containerizing their API using .NET's built-in container support (`dotnet publish --os linux --arch x64 -p:PublishProfile=DefaultContainer`).\n- Explain the differences between manual Dockerfile creation and .NET's container publishing features.\n- Explain CI/CD pipelines for ASP.NET Core applications.\n- Demonstrate deployment to Azure App Service, Azure Container Apps, or other hosting options.\n- Show how to implement health checks and readiness probes.\n- Explain environment-specific configurations for different deployment stages.\n","description":"Guidelines for building REST APIs with ASP.NET","import":{"commit_sha":"541b7819d8c3545c6df122491af4fa1eae415779","imported_at":"2026-05-18T20:05:35Z","license_text":"MIT License\n\nCopyright GitHub, Inc.\n\nPermission is hereby granted, free of charge, to any person obtaining a copy\nof this software and associated documentation files (the \"Software\"), to deal\nin the Software without restriction, including without limitation the rights\nto use, copy, modify, merge, publish, distribute, sublicense, and/or sell\ncopies of the Software, and to permit persons to whom the Software is\nfurnished to do so, subject to the following conditions:\n\nThe above copyright notice and this permission notice shall be included in all\ncopies or substantial portions of the Software.\n\nTHE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\nIMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\nFITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\nAUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\nLIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\nOUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\nSOFTWARE.","owner":"github","repo":"github/awesome-copilot","source_url":"https://github.com/github/awesome-copilot/blob/541b7819d8c3545c6df122491af4fa1eae415779/instructions/aspnet-rest-apis.instructions.md"},"manifest":{}},"content_hash":[244,167,6,43,253,171,13,51,188,25,119,21,154,174,244,161,239,51,205,49,112,138,18,157,187,94,31,66,182,213,250,139],"trust_level":"unsigned","yanked":false}