Open-source tools, packages, and extensions for HTTP API developers<\/h2>\n
This post will cover a variety of things any .NET developer who plans on building HTTP APIs will want in their toolchain or dependency list. We’ll show you some new and exciting frameworks coming up that are built atop ASP.NET Core web API and hopefully make the craft of building and testing HTTP APIs with .NET easier. There are so many opportunities in the form of NuGet packages, Visual Studio and Visual Studio Code extensions, and independently-maintained frameworks, we can’t capture them all in one post. Feel free to use the comments below to share some of your favorite web API tools and packages.<\/p>\n
NuGet packages for building .NET HTTP APIs<\/h2>\n
This first section will cover some of the most important NuGet packages in your HTTP API toolchain. Many of these tools are used in our own pet projects and workshops. Some of the tools appear in our templates and tools as dependencies.<\/p>\n
OpenAPI generation<\/h3>\n
In the first article in this series<\/a>, we touched on the idea of creating discoverable APIs. Since the term discoverable<\/em> in API lingo is associated with service discovery<\/em>, maybe the better term for the article would have been well-described<\/strong>. By describing APIs using the OpenAPI specification (formerly Swagger specification), developers get all kinds of code-generation and integration opportunities. We’ll touch on those later in the series. The point is that OpenAPI generation is important<\/strong> and should be something you’re at least generating, if not designing.<\/p>\n Some consider the idea of generating OpenAPI specifications from code an “inside-out” approach, and design tools are a topic we’ll touch on later. But when building quickly, or maintaining a level of “well-designedness” whilst still generating the specification from code, you have two main options with traditional ASP.NET and ASP.NET Core web API: NSwag<\/a> and Swashbuckle<\/a>. Both of these projects are maintained almost entirely by single individuals with small teams of passionate contributors, and both have had a signifcant impact in the .NET HTTP API ecosystem.<\/p>\n Whilst NSwag’s most popular usage scenario is OpenAPI specification generation from web API controller projects via NSwag.AspNetCore<\/a>, the project’s team has contributed all manner of other contributions:<\/p>\n NSwag’s rich ecosystem of NuGet packages is used by the Visual Studio Connected Services “OpenAPI SDK Generation” feature, which we’ll explore in more detail in the third article in this series. NSwag’s code generation tools produce quality, idiomatic C# client code for well-described<\/strong> APIs.<\/p>\n Swashbuckle<\/a> has been used by millions of web API projects built by customers and internal teams. It was also adopted by the Swagger Codegen<\/a> team in their templates, which are used by many API ecosystem products. Given the presence Swashbuckle has in the web API space, it has been used in our templates since the .NET 5 RC release. It is on-by-default but can be toggled in the new project dialog in Visual Studio (or using the Swashbuckle also has a .NET CLI tool, Swashbuckle.CLI<\/a>, that can be used to generate OpenAPI specifications during your MSBuild or No list of important NuGet packages for the HTTP API developer ecosystem would be complete without Microsoft.OpenAPI<\/a>. A dependency of most of the OpenAPI-supporting projects in the .NET and Azure community, this package is responsible for a variety of features:<\/p>\n If you’re building an app or NuGet package for .NET HTTP API developers using OpenAPI, you’ll probably want to take a look at One of the most important concepts in building APIs that no one tells you about until too late is that, at some point, you’ll need to release breaking changes in APIs many of your customers continue to use. Versioning APIs is complex, and it doesn’t help when you have to do everything manually, so having a fantastic (and used by so many customers and internal teams I’d argue prolific<\/em>), is ASP.NET API Versioning<\/a>. Scott Hanselman wrote about API Versioning<\/a> way back in 2016, and since then it has become an important asset in web API development.<\/p>\n API Versioning enables you to decorate your API controllers with additional attributes that enable the API versions in which the controller’s operations should appear.<\/p>\n Controller action methods can be decorated as well, to identify the versions in which they map or “appear.” In the sample code<\/a> complementing this series, you’ll see the API Versioning has many samples and Wiki articles on how to get started. One of these shows how to use API Versioning and Swashbuckle together<\/a>, which I’ve borrowed for the sample project accompanying this blog series. By adding a small amount of additional code to Note the The code generation tools in Visual Studio Connected Services OpenAPI SDK generation features are aware of the Refit<\/a> is the automatic type-safe REST library for .NET. It turns your interface into a live REST client. Consider the Refit’s If you’re hand-rolling your own client code for back-end APIs, Refit is a great option you should investigate. Refit enables a simplified approach to creating clients for HTTP APIs and abstracts away all of the nuanced In addition to these useful NuGet packages, there are a handful of great tools you can use from both the command line and within your favorite IDEs for designing, building, and testing HTTP APIs.<\/p>\n The HttpRepl<\/a> is a .NET CLI Global tool that can be that provides a directory-style way of exploring an HTTP API described by an OpenAPI specification. Once installed, you can use the command If you haven’t tried the HttpRepl, check out the HttpRepl docs<\/a> for more information on the various commands it offers. The docs also show how you can set up the HttpRepl as a “browser” so you can “F5 debug into the HttpRepl” if you’re more comfortable in the terminal.<\/p>\n There are some impressive HTTP API tools that ship as extensions to Visual Studio Code. One of these, REST Client<\/a>, offers in-IDE HTTP API request testing. By creating Microsoft Edge DevTools recently included an experimental feature<\/a> named Network Console<\/strong>. Network Console offers Edge users in-browser HTTP API testing features. To try it out you’ll first need to enable the Network Console in Edge DevTools experimental features.<\/p>\n Once Network Console is enabled, you can right-click any previously made HTTP request and select the Edit and Resend<\/strong> menu item.<\/p>\n Clicking Edit and Resend will open an HTTP API testing tool, right inside of Edge. So, when you’re building web apps that make HTTP API calls back to the server, or when you’re building Blazor apps that do this sort of thing, you can resend the messages and analyze the API behavior without leaving your browser.<\/p>\n Editing or manually-creating OpenAPI documents can be daunting, so it helps when you can install a great editor and OpenAPI design extension right into Visual Studio Code. OpenAPI Editor<\/a> provides just such functionality. This extension includes features like:<\/p>\n I can use the tool window to find an individual operation in my HTTP API rather than scrolling through a huge JSON file.<\/p>\n With such a vibrant community, it’s common for open-source contributors to extend the ASP.NET framework with their own inventions, or even to push web API into new and exciting directions. Two recent projects are great examples of how the community is taking ASP.NET and web API in new directions.<\/p>\n Steve Smith has started working on an exciting project known as API Endpoints<\/a> that builds on top of ASP.NET Core web API. The project has a mission of abstracting away the need for a developer to think about the concept of a controller to build their HTTP API. Steve wrote about API Endpoints on his blog<\/a>, describing his aspirations and the direction of the project. Essentially, API Endpoints abstracts the controller away so you’re left with a bit less code to author, whilst still being able to use the full feature-set provided by ASP.NET Core MVC Action Result classes.<\/p>\n Since API Endpoint sits atop web API, you can use Swashbuckle or NSwag, or any other web API extension along with API Endpoints and reap the benefits of the wider web API stack, but taking a more modular approach rather than one based on MVC.<\/p>\nNSwag<\/h3>\n
\n
Swashbuckle<\/h3>\n
--no-openapi<\/code> option with the .NET CLI’s dotnet new webapi<\/code> command).<\/p>\n![\"OpenAPI](\"\/aspnet\/wp-content\/uploads\/sites\/16\/2021\/02\/openapi-checkbox.png\")
<\/p>\ndotnet publish<\/code> commands. The sample project<\/a> has an example C# project file<\/a> showing how to use the Swashbuckle CLI during a build process.<\/p>\nMicrosoft.OpenAPI<\/h3>\n
\n
Microsoft.OpenAPI<\/code>. It will ease much of the burden of parsing or writing OpenAPI documents and descriptions.<\/p>\nASP.NET API Versioning<\/h3>\n
[ApiVersion(\"1.0\")]\n[ApiVersion(\"1.1\")]\npublic class ShopController : ControllerBase\n{\n}\n<\/code><\/pre>\nGetProducts<\/code> method and the GetProductsPage<\/code> method, added in version 1.1 of the API.<\/p>\n[HttpGet(\"\/products\", Name = nameof(GetProducts))]\npublic async Task<ActionResult<IEnumerable<Product>>> GetProducts()\n{\n return await Task.FromResult(Ok(StoreServices.GetProducts()));\n}\n\n[HttpGet(\"\/products\/page\/{page}\", Name = nameof(GetProductsPage))]\n[MapToApiVersion(\"1.1\")]\npublic async Task<ActionResult<IEnumerable<Product>>> GetProductsPage([FromRoute] int page = 0)\n{\n var pageSize = 5;\n var productsPage = StoreServices.GetProducts().Skip(page * pageSize).Take(pageSize);\n return await Task.FromResult(Ok(productsPage));\n}\n<\/code><\/pre>\nStartup.cs<\/code> and by using a few infrastructure classes to iterate over the various API versions in your project, you can enlist API Versioning to help you draw out independent Swagger UI pages for multiple versions of your APIs. This changes the Swagger UI to show a drop-down menu containing the API versions in your project.<\/p>\n![\"Swagger](\"\/aspnet\/wp-content\/uploads\/sites\/16\/2021\/02\/swagger-ui-10.png\")
<\/p>\nShop<\/code> operations\u2014there are 3 in the 1.0<\/code> version of the API. But once we change the version menu to see the 1.1<\/code>, the new GetProductsPage<\/code> operation only available in the 1.1<\/code> API version appears.<\/p>\n![\"Swagger](\"\/aspnet\/wp-content\/uploads\/sites\/16\/2021\/02\/swagger-ui-11.png\")
<\/p>\napi-version<\/code> querystring that the API will expect now. When using API Versioning, the generated code adds a parameter to capture the API version string, too. This can be defaulted so that API Versioning will automatically pick the intended version, but in this case I’m implying a more opinionated approach with my client.<\/p>\n\/\/ create a product\napiClient.CreateProductAsync(\"1.1\", \n new CreateProductRequest\n {\n Id = 1000,\n InventoryCount = 0,\n Name = \"Mild Salsa\"\n });\n\n\/\/ update a product's inventory\napiClient.UpdateProductInventoryAsync(1000, \"1.1\", \n new InventoryUpdateRequest\n {\n CountToAdd = 50,\n ProductId = 1000\n });\n<\/code><\/pre>\nRefit<\/h3>\n
IContosoOnlineOrdersApiClient<\/code> example interface below, which would expose method signatures for calling a few of the API methods.<\/p>\npublic interface IContosoOnlineOrdersApiClient\n{\n [Get(\"\/products\")]\n Task<IEnumerable<Product>> GetProducts();\n\n [Post(\"\/products\")]\n Task CreateProduct([Body] CreateProductRequest request);\n}\n<\/code><\/pre>\nRestService<\/code> class generates an implementation of IContosoOnlineOrdersApiClient<\/code> that uses HttpClient<\/code> to make its calls. In the example solution, there’s a Refit client project demonstrating how to use a Refit client to access a back-end HTTP API.<\/p>\nvar client = RestService.For<IContosoOnlineOrdersApiClient>(\"http:\/\/localhost:5000\");\nvar products = await client.GetProducts();\nawait client.CreateProduct(new CreateProductRequest\n{\n Id = 1001,\n InventoryCount = 10,\n Name = \"Taco Shells\"\n});\nproducts = await client.GetProducts();\n<\/code><\/pre>\nHttpClient<\/code> semantics.<\/p>\nTools and extensions for designing and testing HTTP APIs<\/h2>\n
The HttpRepl<\/h3>\n
httprepl -o <openapi-url><\/code> to connect to any OpenAPI-described web API project and explore it using familiar commands like ls<\/code> or dir<\/code> and navigating the API’s structure much like a directory tree.<\/p>\n![\"HttpRepl\"](\"\/aspnet\/wp-content\/uploads\/sites\/16\/2021\/02\/httprepl-e1613077133483.png\")
<\/p>\nREST Client for Visual Studio Code<\/h3>\n
.http<\/code> files into which you write your own request tests, you can trigger REST Client to activate “Send Request” links above each HTTP request you intend on testing.<\/p>\n![\"REST](\"\/aspnet\/wp-content\/uploads\/sites\/16\/2021\/02\/restclient.png\")
<\/p>\nNetwork Console<\/h3>\n
![\"Edge](\"\/aspnet\/wp-content\/uploads\/sites\/16\/2021\/02\/enable-nc-e1613077173259.png\")
<\/p>\n![\"Edit](\"\/aspnet\/wp-content\/uploads\/sites\/16\/2021\/02\/edit-and-resend.png\")
<\/p>\n![\"Network](\"\/aspnet\/wp-content\/uploads\/sites\/16\/2021\/02\/network-console.png\")
<\/p>\nOpenAPI Editor<\/h3>\n
\n
![\"OpenAPI](\"\/aspnet\/wp-content\/uploads\/sites\/16\/2021\/02\/42crunch-openapi.png\")
<\/p>\nFrameworks built atop ASP.NET Core or Web API<\/h3>\n
API Endpoints<\/h3>\n
[HttpPost(\"\/authors\")]\n[SwaggerOperation(\n Summary = \"Creates a new Author\",\n Description = \"Creates a new Author\",\n OperationId = \"Author.Create\",\n Tags = new[] { \"AuthorEndpoint\" })\n]\npublic override async Task<ActionResult<CreateAuthorResult>> HandleAsync([FromBody]CreateAuthorCommand request)\n{\n var author = new Author();\n _mapper.Map(request, author);\n await _repository.AddAsync(author);\n\n var result = _mapper.Map<CreateAuthorResult>(author);\n return Ok(result);\n}\n<\/code><\/pre>\nThe Carter Project<\/h3>\n