ASP.NET Core 2.1 adds a number of features that make it easier and more convenient to build Web APIs. These features include Web API controller specific conventions, more robust input processing and error handling, and JSON patch improvements.<\/p>\n
Please note that some of these features require enabling MVC compatibility with 2.1, so be sure to check out the post on MVC compatibility versions<\/a> as well.<\/p>\n ASP.NET Core 2.1 introduces new Web API controller specific conventions that make Web API development more convenient. These conventions can be applied to a controller using the new You can also now return Here’s an example Web API controller that uses these new enhancements:<\/p>\n Because these conventions are more descriptive tools like Swashbuckle<\/a> or NSwag<\/a> can do a better job generating an OpenAPI specification<\/a> for this Web API that includes information like return types, parameter sources, and possible error responses without needing addition attributes.<\/p>\n ASP.NET Core 2.1 does a much better job of providing appropriate error information when the request body fails to deserialize or the JSON is invalid.<\/p>\n For example, in ASP.NET Core 2.0 if your Web API received a request with a JSON property that had the wrong type (like a string instead of an int) you get a generic error message, like this:<\/p>\n In 2.1 we provide more detailed error information about what was wrong with the request including path and line number information:<\/p>\n Similarly, if the request is syntactically invalid (ex. missing a curly brace) then 2.1 will let you know:<\/p>\n You can also now add validation attributes to top level parameters of your action method. For example, you can mark a query string parameter as required like this:<\/p>\n[ApiController] and ActionResult<\/h3>\n
[ApiController]<\/code> attribute:<\/p>\n\n
[FromBody]<\/code> for complex types, [FromRoute]<\/code> when possible, otherwise [FromQuery]<\/code><\/li>\nActionResult<T><\/code> from your Web API actions, which allows you to return arbitrary action results or a specific return type (thanks to some clever use of implicit cast operators). Most Web API action methods have a specific return type, but also need to be able to return multiple different action results.<\/p>\n[<span class=\"hljs-name\">Route<\/span>(<span class=\"hljs-string\">\"api\/[controller]\"<\/span>)]\n[<span class=\"hljs-name\">ApiController<\/span>]\npublic class ProductsController : ControllerBase\n{\n private readonly ProductsRepository _repository<span class=\"hljs-comment\">;<\/span>\n\n public ProductsController(<span class=\"hljs-name\">ProductsRepository<\/span> repository)\n {\n _repository = repository<span class=\"hljs-comment\">;<\/span>\n }\n\n [<span class=\"hljs-name\">HttpGet<\/span>]\n public IEnumerable<Product> Get()\n {\n return _repository.GetProducts()<span class=\"hljs-comment\">;<\/span>\n }\n\n [<span class=\"hljs-name\">HttpGet<\/span>(<span class=\"hljs-string\">\"{id}\"<\/span>)]\n public ActionResult<Product> Get(<span class=\"hljs-name\">int<\/span> id)\n {\n if (<span class=\"hljs-name\">!_repository.TryGetProduct<\/span>(<span class=\"hljs-name\">id<\/span>, out var product))\n {\n return NotFound()<span class=\"hljs-comment\">;<\/span>\n }\n return product<span class=\"hljs-comment\">;<\/span>\n }\n\n [<span class=\"hljs-name\">HttpPost<\/span>]\n [<span class=\"hljs-name\">ProducesResponseType<\/span>(<span class=\"hljs-name\">201<\/span>)]\n public ActionResult<Product> Post(<span class=\"hljs-name\">Product<\/span> product)\n {\n _repository.AddProduct(<span class=\"hljs-name\">product<\/span>)<span class=\"hljs-comment\">;<\/span>\n return CreatedAtAction(<span class=\"hljs-name\">nameof<\/span>(<span class=\"hljs-name\">Get<\/span>), new { id = product.Id }, product)<span class=\"hljs-comment\">;<\/span>\n }\n}\n<\/code><\/pre>\nBetter input processing<\/h3>\n
{\n <span class=\"hljs-attr\">\"count\"<\/span>: [\n <span class=\"hljs-string\">\"The input was not valid.\"<\/span>\n ]\n}\n<\/code><\/pre>\n{\n <span class=\"hljs-attr\">\"count\"<\/span>: [\n <span class=\"hljs-string\">\"Could not convert string to integer: abc. Path 'count', line 1, position 16.\"<\/span>\n ]\n}\n<\/code><\/pre>\n{\n <span class=\"hljs-attr\">\"\"<\/span>: [\n <span class=\"hljs-string\">\"Unexpected end when reading JSON. Path '', line 1, position 1.\"<\/span>\n ]\n}\n<\/code><\/pre>\n[<span class=\"hljs-name\">HttpGet<\/span>(<span class=\"hljs-string\">\"test\/{testId}\"<\/span>)]\npublic ActionResult<TestResult> Get(<span class=\"hljs-name\"><span class=\"hljs-builtin-name\">string<\/span><\/span> testId, [<span class=\"hljs-name\">Required<\/span>]string name)\n<\/code><\/pre>\nProblem Details<\/h3>\n