--- title: Call a web API in an ASP.NET Core Blazor app author: guardrex description: Learn how to call a web API in Blazor apps. monikerRange: '>= aspnetcore-3.1' ms.author: riande ms.custom: mvc ms.date: 06/03/2021 no-loc: [Home, Privacy, Kestrel, appsettings.json, "ASP.NET Core Identity", cookie, Cookie, Blazor, "Blazor Server", "Blazor WebAssembly", "Identity", "Let's Encrypt", Razor, SignalR] uid: blazor/call-web-api zone_pivot_groups: blazor-hosting-models --- # Call a web API from ASP.NET Core Blazor ::: zone pivot="webassembly" [Blazor WebAssembly](xref:blazor/hosting-models#blazor-webassembly) apps call web APIs using a preconfigured service, which is focused on making requests back to the server of origin. Additional service configurations for other web APIs can be created in developer code. Requests are composed using Blazor JSON helpers or with . Requests can include [Fetch API](https://developer.mozilla.org/docs/Web/API/Fetch_API) option configuration. ## Examples in this article In this article's component examples, a hypothetical todo list web API is used to create, read, update, and delete (CRUD) todo items on a server. The examples are based on a `TodoItem` class that stores the following todo item data: * ID (`Id`, `long`): Unique ID of the item. * Name (`Name`, `string`): Name of the item. * Status (`IsComplete`, `bool`): Indication if the todo item is finished. Use the following `TodoItem` class with this article's examples if you build the examples into a test app: ```csharp public class TodoItem { public long Id { get; set; } public string Name { get; set; } public bool IsComplete { get; set; } } ``` For guidance on how to create a server-side web API, see . For information on Cross-origin resource sharing (CORS), see the [CORS guidance](#cross-origin-resource-sharing-cors) later in this article. ## Packages Reference the [`System.Net.Http.Json`](https://www.nuget.org/packages/System.Net.Http.Json) NuGet package in the project file. ## Add the `HttpClient` service In `Program.Main`, add an service if it isn't already present from a Blazor project template used to create the app: ```csharp builder.Services.AddScoped(sp => new HttpClient { BaseAddress = new Uri(builder.HostEnvironment.BaseAddress) }); ``` ## `HttpClient` and JSON helpers is available as a preconfigured service for making requests back to the origin server. and JSON helpers () are also used to call third-party web API endpoints. is implemented using the browser's [Fetch API](https://developer.mozilla.org/docs/Web/API/Fetch_API) and is subject to its limitations, including enforcement of the [same-origin policy (discussed later in this article)](#cross-origin-resource-sharing-cors). The client's base address is set to the originating server's address. Inject an instance into a component using the [`@inject`](xref:mvc/views/razor#inject) directive: ```razor @using System.Net.Http @inject HttpClient Http ``` Use the namespace for access to , including , , and : ```razor @using System.Net.Http.Json ``` ### GET from JSON (`GetFromJsonAsync`) sends an HTTP GET request and parses the JSON response body to create an object. In the following component code, the `todoItems` are displayed by the component. is called when the component is finished initializing ([`OnInitializedAsync`](xref:blazor/components/lifecycle#component-initialization-oninitializedasync)). ```razor @using System.Net.Http @using System.Net.Http.Json @using System.Threading.Tasks @inject HttpClient Http @if (todoItems == null) {

No Todo Items found.

} else {
    @foreach (var item in todoItems) {
  • @item.Name
  • }
} @code { private TodoItem[] todoItems; protected override async Task OnInitializedAsync() => todoItems = await Http.GetFromJsonAsync("api/TodoItems"); } ``` ### POST as JSON (`PostAsJsonAsync`) sends a POST request to the specified URI containing the value serialized as JSON in the request body. In the following component code, `newItemName` is provided by a bound element of the component. The `AddItem` method is triggered by selecting a ` @code { private string newItemName; private async Task AddItem() { var addItem = new TodoItem { Name = newItemName, IsComplete = false }; await Http.PostAsJsonAsync("api/TodoItems", addItem); } } ``` Calls to return an . To deserialize the JSON content from the response message, use the extension method. The following example reads JSON weather data: ```csharp var content = await response.Content.ReadFromJsonAsync(); ``` ### PUT as JSON (`PutAsJsonAsync`) sends an HTTP PUT request with JSON-encoded content. In the following component code, `editItem` values for `Name` and `IsCompleted` are provided by bound elements of the component. The item's `Id` is set when the item is selected in another part of the UI (not shown) and `EditItem` is called. The `SaveItem` method is triggered by selecting the ` @code { private string id; private TodoItem editItem = new TodoItem(); private void EditItem(long id) { editItem = todoItems.Single(i => i.Id == id); } private async Task SaveItem() => await Http.PutAsJsonAsync($"api/TodoItems/{editItem.Id}", editItem); } ``` Calls to return an . To deserialize the JSON content from the response message, use the extension method. The following example reads JSON weather data: ```csharp var content = await response.Content.ReadFromJsonAsync(); ``` ### Additional extension methods includes additional extension methods for sending HTTP requests and receiving HTTP responses. is used to send an HTTP DELETE request to a web API. In the following component code, the ` @code { private long id; private async Task DeleteItem() => await Http.DeleteAsync($"api/TodoItems/{id}"); } ``` ## Named `HttpClient` with `IHttpClientFactory` services and the configuration of a named are supported. Reference the [`Microsoft.Extensions.Http`](https://www.nuget.org/packages/Microsoft.Extensions.Http) NuGet package in the project file: ```xml ``` In the preceding example, the `{VERSION}` placeholder is the version of the package. In `Program.Main` of the `Program.cs` file: ```csharp builder.Services.AddHttpClient("WebAPI", client => client.BaseAddress = new Uri(builder.HostEnvironment.BaseAddress)); ``` In the following component code: * An instance of creates a named . * The named is used to issue a GET request for JSON weather forecast data from the web API. `Pages/FetchDataViaFactory.razor`: ```razor @page "/fetch-data-via-factory" @using System.Net.Http @using System.Net.Http.Json @using System.Threading.Tasks @inject IHttpClientFactory ClientFactory

Fetch data via IHttpClientFactory

@if (forecasts == null) {

Loading...

} else {

Temperatures by Date

    @foreach (var forecast in forecasts) {
  • @forecast.Date.ToShortDateString(): @forecast.TemperatureC ℃ @forecast.TemperatureF ℉
  • }
} @code { private WeatherForecast[] forecasts; protected override async Task OnInitializedAsync() { var client = ClientFactory.CreateClient("WebAPI"); forecasts = await client.GetFromJsonAsync( "WeatherForecast"); } } ``` ## Typed `HttpClient` Typed uses one or more of the app's instances, default or named, to return data from one or more web API endpoints. `WeatherForecastClient.cs`: ```csharp using System.Net.Http; using System.Net.Http.Json; using System.Threading.Tasks; public class WeatherForecastHttpClient { private readonly HttpClient http; public WeatherForecastHttpClient(HttpClient http) { this.http = http; } public async Task GetForecastAsync() { try { return await http.GetFromJsonAsync( "WeatherForecast"); } catch { ... return new WeatherForecast[0]; } } } ``` In `Program.Main` of the `Program.cs` file: ```csharp builder.Services.AddHttpClient(client => client.BaseAddress = new Uri(builder.HostEnvironment.BaseAddress)); ``` Components inject the typed to call the web API. In the following component code: * An instance of the preceding `WeatherForecastHttpClient` is injected, which creates a typed . * The typed is used to issue a GET request for JSON weather forecast data from the web API. `Pages/FetchDataViaTypedHttpClient.razor`: ```razor @page "/fetch-data-via-typed-httpclient" @using System.Threading.Tasks @inject WeatherForecastHttpClient Http

Fetch data via typed HttpClient

@if (forecasts == null) {

Loading...

} else {

Temperatures by Date

    @foreach (var forecast in forecasts) {
  • @forecast.Date.ToShortDateString(): @forecast.TemperatureC ℃ @forecast.TemperatureF ℉
  • }
} @code { private WeatherForecast[] forecasts; protected override async Task OnInitializedAsync() { forecasts = await Http.GetForecastAsync(); } } ``` ## `HttpClient` and `HttpRequestMessage` with Fetch API request options [`HttpClient`](xref:fundamentals/http-requests) ([API documentation](xref:System.Net.Http.HttpClient)) and can be used to customize requests. For example, you can specify the HTTP method and request headers. The following component makes a `POST` request to a web API endpoint and shows the response body. `Pages/TodoRequest.razor`: ::: moniker range=">= aspnetcore-5.0" [!code-razor[](~/blazor/common/samples/5.x/BlazorSample_WebAssembly/Pages/call-web-api/TodoRequest.razor)] ::: moniker-end ::: moniker range="< aspnetcore-5.0" [!code-razor[](~/blazor/common/samples/3.x/BlazorSample_WebAssembly/Pages/call-web-api/TodoRequest.razor)] ::: moniker-end Blazor WebAssembly's implementation of uses [Fetch API](https://developer.mozilla.org/docs/Web/API/WindowOrWorkerGlobalScope/fetch). Fetch API allows the configuration of several [request-specific options](https://developer.mozilla.org/docs/Web/API/WindowOrWorkerGlobalScope/fetch#Parameters). Options can be configured with extension methods shown in the following table. | Extension method | Fetch API request property | | --- | --- | | | [`cache`](https://developer.mozilla.org/docs/Web/API/Request/cache) | | | [`credentials`](https://developer.mozilla.org/docs/Web/API/Request/credentials) | | | [`integrity`](https://developer.mozilla.org/docs/Web/API/Request/integrity) | | | [`mode`](https://developer.mozilla.org/docs/Web/API/Request/mode) | Set additional options using the generic extension method. The HTTP response is typically buffered to enable support for synchronous reads on the response content. To enable support for response streaming, use the extension method on the request. To include credentials in a cross-origin request, use the extension method: ```csharp requestMessage.SetBrowserRequestCredentials(BrowserRequestCredentials.Include); ``` For more information on Fetch API options, see [MDN web docs: WindowOrWorkerGlobalScope.fetch(): Parameters](https://developer.mozilla.org/docs/Web/API/WindowOrWorkerGlobalScope/fetch#Parameters). ## Call web API example The following example calls a web API. The example requires a running web API based on the sample app described by the article. This example makes requests to the web API at `https://localhost:10000/api/TodoItems`. If a different web API address is used, update the `ServiceEndpoint` constant value in the component's `@code` block. The following example makes a [cross-origin resource sharing (CORS)](xref:security/cors) request from `http://localhost:5000` or `https://localhost:5001` to the web API. Add the following CORS middleware configuration to the web API's service's `Startup.Configure` method: ```csharp app.UseCors(policy => policy.WithOrigins("http://localhost:5000", "https://localhost:5001") .AllowAnyMethod() .WithHeaders(HeaderNames.ContentType)); ``` Adjust the domains and ports of `WithOrigins` as needed for the Blazor app. For more information, see . ::: moniker range=">= aspnetcore-5.0" By default, ASP.NET Core apps use ports 5000 (HTTP) and 5001 (HTTPS). To run both apps on the same machine at the same time for testing, use a different port for the web API app (for example, port 10000). For more information on setting the port, see . ::: moniker-end ::: moniker range="< aspnetcore-5.0" By default, ASP.NET Core apps use ports 5000 (HTTP) and 5001 (HTTPS). To run both apps on the same machine at the same time for testing, use a different port for the web API app (for example, port 10000). For more information on setting the port, see . ::: moniker-end `Pages/CallWebAPI.razor`: ::: moniker range=">= aspnetcore-5.0" [!code-razor[](~/blazor/common/samples/5.x/BlazorSample_WebAssembly/Pages/call-web-api/CallWebAPI.razor)] ::: moniker-end ::: moniker range="< aspnetcore-5.0" [!code-razor[](~/blazor/common/samples/3.x/BlazorSample_WebAssembly/Pages/call-web-api/CallWebAPI.razor)] ::: moniker-end ## Handle errors Handle web API response errors in developer code when they occur. For example, expects a JSON response from the web API with a `Content-Type` of `application/json`. If the response isn't in JSON format, content validation throws a . In the following example, the URI endpoint for the weather forecast data request is misspelled. The URI should be to `WeatherForecast` but appears in the call as `WeatherForcast`, which is missing the letter `e` in `Forecast`. The call expects JSON to be returned, but the web API returns HTML for an unhandled exception with a `Content-Type` of `text/html`. The unhandled exception occurs because the path to `/WeatherForcast` isn't found and middleware can't serve a page or view for the request. In on the client, is thrown when the response content is validated as non-JSON. The exception is caught in the `catch` block, where custom logic could log the error or present a friendly error message to the user. `Pages/FetchDataReturnsHTMLOnException.razor`: ```razor @page "/fetch-data-returns-html-on-exception" @using System.Net.Http @using System.Net.Http.Json @using System.Threading.Tasks @inject HttpClient Http

Fetch data but receive HTML on unhandled exception

@if (forecasts == null) {

Loading...

} else {

Temperatures by Date

    @foreach (var forecast in forecasts) {
  • @forecast.Date.ToShortDateString(): @forecast.TemperatureC ℃ @forecast.TemperatureF ℉
  • }
}

@exceptionMessage

@code { private WeatherForecast[] forecasts; private string exceptionMessage; protected override async Task OnInitializedAsync() { try { // The URI endpoint "WeatherForecast" is misspelled on purpose on the // next line. See the preceding text for more information. forecasts = await Http.GetFromJsonAsync("WeatherForcast"); } catch (NotSupportedException exception) { exceptionMessage = exception.Message; } } } ``` > [!NOTE] > The preceding example is for demonstration purposes. A web API can be configured to return JSON even when an endpoint doesn't exist or an unhandled exception occurs on the server. For more information, see . ::: zone-end ::: zone pivot="server" [Blazor Server](xref:blazor/hosting-models#blazor-server) apps call web APIs using instances, typically created using . For guidance that applies to Blazor Server, see . A Blazor Server app doesn't include an service by default. Provide an to the app using the [`HttpClient` factory infrastructure](xref:fundamentals/http-requests). In `Startup.`ConfigureServices` of `Startup.cs`: ```csharp services.AddHttpClient(); ``` The following Blazor Server Razor component makes a request to a web API for GitHub branches similar to the *Basic Usage* example in the article. `Pages/CallWebAPI.razor`: ```razor @page "/call-web-api" @using System.Text.Json @using System.Text.Json.Serialization; @inject IHttpClientFactory ClientFactory

Call web API from a Blazor Server Razor component

@if (getBranchesError) {

Unable to get branches from GitHub. Please try again later.

} else {
    @foreach (var branch in branches) {
  • @branch.Name
  • }
} @code { private IEnumerable branches = Array.Empty(); private bool getBranchesError; private bool shouldRender; protected override bool ShouldRender() => shouldRender; protected override async Task OnInitializedAsync() { var request = new HttpRequestMessage(HttpMethod.Get, "https://api.github.com/repos/dotnet/AspNetCore.Docs/branches"); request.Headers.Add("Accept", "application/vnd.github.v3+json"); request.Headers.Add("User-Agent", "HttpClientFactory-Sample"); var client = ClientFactory.CreateClient(); var response = await client.SendAsync(request); if (response.IsSuccessStatusCode) { using var responseStream = await response.Content.ReadAsStreamAsync(); branches = await JsonSerializer.DeserializeAsync >(responseStream); } else { getBranchesError = true; } shouldRender = true; } public class GitHubBranch { [JsonPropertyName("name")] public string Name { get; set; } } } ``` For an additional working example, see the Blazor Server file upload example that uploads files to a web API controller in the article. ::: zone-end ## Cross-origin resource sharing (CORS) Browser security restricts a webpage from making requests to a different domain than the one that served the webpage. This restriction is called the *same-origin policy*. The same-origin policy restricts (but doesn't prevent) a malicious site from reading sensitive data from another site. To make requests from the browser to an endpoint with a different origin, the *endpoint* must enable [cross-origin resource sharing (CORS)](https://www.w3.org/TR/cors/). ::: zone pivot="webassembly" For information on CORS requests in Blazor WebAssembly apps, see . For information on CORS, see . The article's examples don't pertain directly to Blazor WebAssembly apps, but the article is useful for learning general CORS concepts. ::: zone-end ::: zone pivot="server" For more information, see . ::: zone-end ## Blazor framework component examples for testing web API access Various network tools are publicly available for testing web API backend apps directly, such as [Fiddler](https://www.telerik.com/fiddler), [Firefox Browser Developer](https://www.mozilla.org/firefox/developer/), and [Postman](https://www.postman.com). Blazor framework's reference source includes test assets that are useful for testing: [`HttpClientTest` assets in the `dotnet/aspnetcore` GitHub repository](https://github.com/dotnet/aspnetcore/tree/main/src/Components/test/testassets/BasicTestApp/HttpClientTest) [!INCLUDE[](~/blazor/includes/aspnetcore-repo-ref-source-links.md)] ## Additional resources ::: zone pivot="webassembly" * : Includes coverage on using to make secure web API requests. * : Although the content applies to ASP.NET Core apps, not Blazor WebAssembly apps, the article covers general CORS concepts. * [Cross Origin Resource Sharing (CORS) at W3C](https://www.w3.org/TR/cors/) * [Fetch API](https://developer.mozilla.org/docs/Web/API/WindowOrWorkerGlobalScope/fetch) ::: zone-end ::: zone pivot="server" ::: moniker range=">= aspnetcore-5.0" * : Includes coverage on using to make secure web API requests. * * * * [Kestrel HTTPS endpoint configuration](xref:fundamentals/servers/kestrel/endpoints) * [Cross Origin Resource Sharing (CORS) at W3C](https://www.w3.org/TR/cors/) ::: moniker-end ::: moniker range="< aspnetcore-5.0" * : Includes coverage on using to make secure web API requests. * * * * [Kestrel HTTPS endpoint configuration](xref:fundamentals/servers/kestrel#endpoint-configuration) * [Cross Origin Resource Sharing (CORS) at W3C](https://www.w3.org/TR/cors/) ::: moniker-end ::: zone-end