--- title: Build web APIs with ASP.NET Core author: scottaddie description: Learn about the features available for building a web API in ASP.NET Core and when it's appropriate to use each feature. ms.author: scaddie ms.custom: mvc ms.date: 01/11/2019 uid: web-api/index --- # Build web APIs with ASP.NET Core By [Scott Addie](https://github.com/scottaddie) [View or download sample code](https://github.com/aspnet/Docs/tree/master/aspnetcore/web-api/define-controller/samples) ([how to download](xref:index#how-to-download-a-sample)) This document explains how to build a web API in ASP.NET Core and when it's most appropriate to use each feature. ## Derive class from ControllerBase Inherit from the class in a controller that's intended to serve as a web API. For example: ::: moniker range=">= aspnetcore-2.1" [!code-csharp[](define-controller/samples/WebApiSample.Api.21/Controllers/PetsController.cs?name=snippet_PetsController&highlight=3)] ::: moniker-end ::: moniker range="<= aspnetcore-2.0" [!code-csharp[](define-controller/samples/WebApiSample.Api.Pre21/Controllers/PetsController.cs?name=snippet_PetsController&highlight=3)] ::: moniker-end The `ControllerBase` class provides access to several properties and methods. In the preceding code, examples include and . These methods are called within action methods to return HTTP 400 and 201 status codes, respectively. The property, also provided by `ControllerBase`, is accessed to handle request model validation. ::: moniker range=">= aspnetcore-2.1" ## Annotation with ApiController attribute ASP.NET Core 2.1 introduces the [[ApiController]](xref:Microsoft.AspNetCore.Mvc.ApiControllerAttribute) attribute to denote a web API controller class. For example: [!code-csharp[](define-controller/samples/WebApiSample.Api.21/Controllers/ProductsController.cs?name=snippet_ControllerSignature&highlight=2)] A compatibility version of 2.1 or later, set via , is required to use this attribute at the controller level. For example, the highlighted code in `Startup.ConfigureServices` sets the 2.1 compatibility flag: [!code-csharp[](define-controller/samples/WebApiSample.Api.21/Startup.cs?name=snippet_SetCompatibilityVersion&highlight=2)] For more information, see . ::: moniker-end ::: moniker range=">= aspnetcore-2.2" In ASP.NET Core 2.2 or later, the `[ApiController]` attribute can be applied to an assembly. Annotation in this manner applies web API behavior to all controllers in the assembly. Beware that there's no way to opt out for individual controllers. As a recommendation, assembly-level attributes should be applied to the `Startup` class: [!code-csharp[](define-controller/samples/WebApiSample.Api.22/Startup.cs?name=snippet_ApiControllerAttributeOnAssembly&highlight=1)] A compatibility version of 2.2 or later, set via , is required to use this attribute at the assembly level. ::: moniker-end ::: moniker range=">= aspnetcore-2.1" The `[ApiController]` attribute is commonly coupled with `ControllerBase` to enable REST-specific behavior for controllers. `ControllerBase` provides access to methods such as and . Another approach is to create a custom base controller class annotated with the `[ApiController]` attribute: [!code-csharp[](define-controller/samples/WebApiSample.Api.21/Controllers/MyBaseController.cs?name=snippet_ControllerSignature)] The following sections describe convenience features added by the attribute. ### Automatic HTTP 400 responses Model validation errors automatically trigger an HTTP 400 response. Consequently, the following code becomes unnecessary in your actions: [!code-csharp[](define-controller/samples/WebApiSample.Api.Pre21/Controllers/PetsController.cs?name=snippet_ModelStateIsValidCheck)] Use to customize the output of the resulting response. Disabling the default behavior is useful when your action can recover from a model validation error. The default behavior is disabled when the property is set to `true`. Add the following code in `Startup.ConfigureServices` after `services.AddMvc().SetCompatibilityVersion(CompatibilityVersion.Version_);`: ::: moniker-end ::: moniker range=">= aspnetcore-2.2" [!code-csharp[](define-controller/samples/WebApiSample.Api.22/Startup.cs?name=snippet_ConfigureApiBehaviorOptions&highlight=7)] ::: moniker-end ::: moniker range="= aspnetcore-2.1" [!code-csharp[](define-controller/samples/WebApiSample.Api.21/Startup.cs?name=snippet_ConfigureApiBehaviorOptions&highlight=5)] ::: moniker-end ::: moniker range=">= aspnetcore-2.2" With a compatibility flag of 2.2 or later, the default response type for HTTP 400 responses is . The `ValidationProblemDetails` type complies with the [RFC 7807 specification](https://tools.ietf.org/html/rfc7807). Set the `SuppressUseValidationProblemDetailsForInvalidModelStateResponses` property to `true` to instead return the ASP.NET Core 2.1 error format of . Add the following code in `Startup.ConfigureServices`: ```csharp services.AddMvc() .SetCompatibilityVersion(CompatibilityVersion.Version_2_2) .ConfigureApiBehaviorOptions(options => { options .SuppressUseValidationProblemDetailsForInvalidModelStateResponses = true; }); ``` ::: moniker-end ::: moniker range=">= aspnetcore-2.1" ### Binding source parameter inference A binding source attribute defines the location at which an action parameter's value is found. The following binding source attributes exist: |Attribute|Binding source | |---------|---------| |**[[FromBody]](xref:Microsoft.AspNetCore.Mvc.FromBodyAttribute)** | Request body | |**[[FromForm]](xref:Microsoft.AspNetCore.Mvc.FromFormAttribute)** | Form data in the request body | |**[[FromHeader]](xref:Microsoft.AspNetCore.Mvc.FromHeaderAttribute)** | Request header | |**[[FromQuery]](xref:Microsoft.AspNetCore.Mvc.FromQueryAttribute)** | Request query string parameter | |**[[FromRoute]](xref:Microsoft.AspNetCore.Mvc.FromRouteAttribute)** | Route data from the current request | |**[[FromServices]](xref:mvc/controllers/dependency-injection#action-injection-with-fromservices)** | The request service injected as an action parameter | > [!WARNING] > Don't use `[FromRoute]` when values might contain `%2f` (that is `/`). `%2f` won't be unescaped to `/`. Use `[FromQuery]` if the value might contain `%2f`. Without the `[ApiController]` attribute, binding source attributes are explicitly defined. Without `[ApiController]` or other binding source attributes like `[FromQuery]`, the ASP.NET Core runtime attempts to use the complex object model binder. The complex object model binder pulls data from value providers (which have a defined order). For instance, the 'body model binder' is always opt in. In the following example, the `[FromQuery]` attribute indicates that the `discontinuedOnly` parameter value is provided in the request URL's query string: [!code-csharp[](define-controller/samples/WebApiSample.Api.21/Controllers/ProductsController.cs?name=snippet_BindingSourceAttributes&highlight=3)] Inference rules are applied for the default data sources of action parameters. These rules configure the binding sources you're otherwise likely to manually apply to the action parameters. The binding source attributes behave as follows: * **[FromBody]** is inferred for complex type parameters. An exception to this rule is any complex, built-in type with a special meaning, such as and . The binding source inference code ignores those special types. `[FromBody]` isn't inferred for simple types such as `string` or `int`. Therefore, the `[FromBody]` attribute should be used for simple types when that functionality is needed. When an action has more than one parameter explicitly specified (via `[FromBody]`) or inferred as bound from the request body, an exception is thrown. For example, the following action signatures cause an exception: [!code-csharp[](define-controller/samples/WebApiSample.Api.21/Controllers/TestController.cs?name=snippet_ActionsCausingExceptions)] > [!NOTE] > In ASP.NET Core 2.1, collection type parameters such as lists and arrays are incorrectly inferred as [[FromQuery]](xref:Microsoft.AspNetCore.Mvc.FromQueryAttribute). [[FromBody]](xref:Microsoft.AspNetCore.Mvc.FromBodyAttribute) should be used for these parameters if they are to be bound from the request body. This behavior is fixed in ASP.NET Core 2.2 or later, where collection type parameters are inferred to be bound from the body by default. * **[FromForm]** is inferred for action parameters of type and . It's not inferred for any simple or user-defined types. * **[FromRoute]** is inferred for any action parameter name matching a parameter in the route template. When more than one route matches an action parameter, any route value is considered `[FromRoute]`. * **[FromQuery]** is inferred for any other action parameters. The default inference rules are disabled when the property is set to `true`. Add the following code in `Startup.ConfigureServices` after `services.AddMvc().SetCompatibilityVersion(CompatibilityVersion.Version_);`: ::: moniker-end ::: moniker range=">= aspnetcore-2.2" [!code-csharp[](define-controller/samples/WebApiSample.Api.22/Startup.cs?name=snippet_ConfigureApiBehaviorOptions&highlight=6)] ::: moniker-end ::: moniker range="= aspnetcore-2.1" [!code-csharp[](define-controller/samples/WebApiSample.Api.21/Startup.cs?name=snippet_ConfigureApiBehaviorOptions&highlight=4)] ::: moniker-end ::: moniker range=">= aspnetcore-2.1" ### Multipart/form-data request inference When an action parameter is annotated with the [[FromForm]](xref:Microsoft.AspNetCore.Mvc.FromFormAttribute) attribute, the `multipart/form-data` request content type is inferred. The default behavior is disabled when the property is set to `true`. ::: moniker-end ::: moniker range=">= aspnetcore-2.2" Add the following code in `Startup.ConfigureServices`: [!code-csharp[](define-controller/samples/WebApiSample.Api.22/Startup.cs?name=snippet_ConfigureApiBehaviorOptions&highlight=5)] ::: moniker-end ::: moniker range="= aspnetcore-2.1" Add the following code in `Startup.ConfigureServices` after `services.AddMvc().SetCompatibilityVersion(CompatibilityVersion.Version_2_1);`: [!code-csharp[](define-controller/samples/WebApiSample.Api.21/Startup.cs?name=snippet_ConfigureApiBehaviorOptions&highlight=3)] ::: moniker-end ::: moniker range=">= aspnetcore-2.1" ### Attribute routing requirement Attribute routing becomes a requirement. For example: [!code-csharp[](define-controller/samples/WebApiSample.Api.21/Controllers/ProductsController.cs?name=snippet_ControllerSignature&highlight=1)] Actions are inaccessible via [conventional routes](xref:mvc/controllers/routing#conventional-routing) defined in or by in `Startup.Configure`. ::: moniker-end ::: moniker range=">= aspnetcore-2.2" ### Problem details responses for error status codes In ASP.NET Core 2.2 or later, MVC transforms an error result (a result with status code 400 or higher) to a result with . `ProblemDetails` is: * A type based on the [RFC 7807 specification](https://tools.ietf.org/html/rfc7807). * A standardized format for specifying machine-readable error details in an HTTP response. Consider the following code in a controller action: [!code-csharp[](define-controller/samples/WebApiSample.Api.22/Controllers/ProductsController.cs?name=snippet_ProblemDetailsStatusCode)] The HTTP response for `NotFound` has a 404 status code with a `ProblemDetails` body. For example: ```json { type: "https://tools.ietf.org/html/rfc7231#section-6.5.4", title: "Not Found", status: 404, traceId: "0HLHLV31KRN83:00000001" } ``` The problem details feature requires a compatibility flag of 2.2 or later. The default behavior is disabled when the `SuppressMapClientErrors` property is set to `true`. Add the following code in `Startup.ConfigureServices`: [!code-csharp[](define-controller/samples/WebApiSample.Api.22/Startup.cs?name=snippet_ConfigureApiBehaviorOptions&highlight=8)] Use the `ClientErrorMapping` property to configure the contents of the `ProblemDetails` response. For example, the following code updates the `type` property for 404 responses: [!code-csharp[](define-controller/samples/WebApiSample.Api.22/Startup.cs?name=snippet_ConfigureApiBehaviorOptions&highlight=10-11)] ::: moniker-end ## Additional resources * * * * * ****