{"id":87963,"date":"2020-08-26T01:17:22","date_gmt":"2020-08-26T01:17:22","guid":{"rendered":"https:\/\/www.red-gate.com\/simple-talk\/?p=87963"},"modified":"2022-04-24T21:32:44","modified_gmt":"2022-04-24T21:32:44","slug":"build-a-rest-api-in-net-core","status":"publish","type":"post","link":"https:\/\/www.red-gate.com\/simple-talk\/development\/dotnet-development\/build-a-rest-api-in-net-core\/","title":{"rendered":"Build a REST API in .NET Core"},"content":{"rendered":"

One way to scale large complex solutions is to break them out into REST microservices. Microservices unlock testability and reusability of business logic that sits behind an API boundary. This allows organizations to share software modules because REST APIs can be reused by multiple clients. Clients can then call as many APIs from mobile, web, or even static assets via a single-page app.<\/p>\n

In this take, I will show you what it takes to build a REST API in .NET Core. I will hit this with real-world demands such as versioning, search, and logging, to name a few. REST is often employed with verbs like POST<\/code>, PUT<\/code>, or PATCH<\/code>, so I plan to cover them all. What I hope you see is a nice, effective way to deliver value with the tools available.<\/p>\n

This article assumes a working grasp of ASP.NET, C#, and REST APIs so I will not cover any basics. I recommend the latest .NET Core LTS release<\/a> at the time of this writing to follow along. If you would like to start with working code, the sample code can be downloaded from GitHub<\/a>.<\/p>\n

You can begin by creating a new folder like BuildRestApiNetCore<\/em> and firing this up in a shell:<\/p>\n

dotnet new sln\r\ndotnet new webapi --no-https\r\ndotnet sln add .<\/pre>\n
This project is based on a Web API template with HTTPS disabled to make it easier for local development. Double-clicking the solution file brings it up in Visual Studio if you have it installed. For .NET Core 3.1 support, be sure to have the 2019 version of the IDE.<\/p>\n
APIs put a layer of separation between clients and the database, so the data is an excellent place to start. To keep data access trivial, Entity Framework has an in-memory alternative so that I can focus on the API itself.<\/p>\n
An in-memory database provider comes via NuGet:<\/p>\n
dotnet add package Microsoft.EntityFrameworkCore.InMemory<\/pre>\n
Then, create the following data model. I put this in the Models folder to indicate this namespace houses raw data. To use the data annotations, add System.ComponentModel.DataAnnotations<\/code> in a using statement.<\/p>\n
public class Product\r\n{\r\n  [Key]\r\n  [Required]\r\n  [Display(Name = \"productNumber\")]\r\n  public string ProductNumber { get; set; }\r\n\r\n  [Required]\r\n  [Display(Name = \"name\")]\r\n  public string Name { get; set; }\r\n\r\n  [Required]\r\n  [Range(10, 90)]\r\n  [Display(Name = \"price\")]\r\n  public double? Price { get; set; }\r\n\r\n  [Required]\r\n  [Display(Name = \"department\")]\r\n  public string Department { get; set; }\r\n}<\/pre>\n
In a real solution, this may go in a separate project depending on the team\u2019s needs. Pay attention to the attributes assigned to this model like Required<\/code>, Display<\/code>, and Range<\/code>. These are data annotations in ASP.NET to validate the Product during model binding. Because I use an in-memory database, Entity Framework requires a unique Key<\/em>. These attributes assign validation rules like price range or whether the property is required.<\/p>\n
From a business perspective, this is an e-commerce site with a product number, name, and price. Each product is also assigned a department to make searches by department easier.<\/p>\n
Next, set the Entity Framework DbContext<\/code> in the Models namespace:<\/p>\n
public class ProductContext : DbContext\r\n{\r\n  public ProductContext(DbContextOptions<ProductContext> options) : base(options)\r\n  {\r\n  }\r\n\r\n  public DbSet<Product> Products { get; set; }\r\n}<\/pre>\n
This database context is the dependency injected in the controller to query or update data. To enable Dependency Injection in ASP.NET Core, crack open the Startup<\/code> class and add this in ConfigureServices<\/code>:<\/p>\n
services\r\n  .AddDbContext<ProductContext>(opt => \r\n              opt.UseInMemoryDatabase(\"Products\"));<\/pre>\n
This code completes the in-memory database. Be sure to add Microsoft.EntityFrameworkCore<\/code> to both classes in a using statement. Because a blank back end is no fun, this needs seed data.<\/p>\n
Create this extension method to help iterate through seed items. This can go in an Extensions<\/em> namespace or folder:<\/p>\n
public  static class EnumerableExtensions\r\n{\r\n  public static IEnumerable<T> Times<T>(this int count, Func<int, T> func)\r\n  {\r\n    for (var i = 1; i <= count; i++) yield return func.Invoke(i);\r\n  }\r\n}<\/pre>\n
The initial seed goes in Models<\/em> via a static class:<\/p>\n
public static class ProductSeed\r\n{\r\n  public static void InitData(ProductContext context)\r\n  {\r\n    var rnd = new Random();\r\n\r\n    var adjectives = new [] { \"Small\", \"Ergonomic\", \"Rustic\", \r\n                                        \"Smart\", \"Sleek\" };\r\n    var materials = new [] { \"Steel\", \"Wooden\", \"Concrete\", \"Plastic\",\r\n                                       \"Granite\", \"Rubber\" };\r\n    var names = new [] { \"Chair\", \"Car\", \"Computer\", \"Pants\", \"Shoes\" };\r\n    var departments = new [] { \"Books\", \"Movies\", \"Music\", \r\n                                       \"Games\", \"Electronics\" };\r\n\r\n    context.Products.AddRange(900.Times(x =>\r\n    {\r\n      var adjective = adjectives[rnd.Next(0, 5)];\r\n      var material = materials[rnd.Next(0, 5)];\r\n      var name = names[rnd.Next(0, 5)];\r\n      var department = departments[rnd.Next(0, 5)];\r\n      var productId = $\"{x, -3:000}\";\r\n\r\n      return new Product\r\n      {\r\n        ProductNumber = \r\n           $\"{department.First()}{name.First()}{productId}\",\r\n        Name = $\"{adjective} {material} {name}\",\r\n        Price = (double) rnd.Next(1000, 9000) \/ 100,\r\n        Department = department\r\n      };\r\n    }));\r\n\r\n    context.SaveChanges();\r\n  }\r\n}<\/pre>\n
This code loops through a list of 900 items to create this many products. The names are picked at random with a department and price. Each product gets a \u201csmart\u201d key as the primary key which comes from department, name, and product id.<\/p>\n
Once this seed runs, you may get products such as \u201cSmart Wooden Pants\u201d in the Electronics department for a nominal price.<\/p>\n
As a preliminary step to start building endpoints, it is a good idea to set up versioning. This allows client apps to upgrade API functionality at their leisure without tight coupling.<\/p>\n
API versioning comes in a NuGet package:<\/p>\n
dotnet add package Microsoft.AspNetCore.Mvc.Versioning<\/pre>\n
Go back to the Startup<\/code> class and add this to ConfigureServices<\/code>:<\/p>\n
services.AddApiVersioning(opt => opt.ReportApiVersions = true);<\/pre>\n
I opted to include available versions in the API response, so clients know when upgrades are available. I recommend using Semantic Versioning<\/a> to communicate breaking changes in the API. Letting clients know what to expect between upgrades helps everyone stay on the latest features.<\/p>\n
Search endpoint in a REST API<\/h2>\n
To build an endpoint, spin up a Controller in ASP.NET which goes in the Controllers<\/em> folder.<\/p>\n
Create a ProductsController<\/code> with the following, making sure to add the namespace Microsoft.AspNetCore.Mvc<\/code> with a using statement:<\/p>\n
[ApiController]\r\n[ApiVersion(\"1.0\")]\r\n[Route(\"v{version:apiVersion}\/[controller]\")]\r\n[Produces(\"application\/json\")]\r\npublic class ProductsController : ControllerBase\r\n{\r\n  private readonly ProductContext _context;\r\n\r\n  public ProductsController(ProductContext context)\r\n  {\r\n    _context = context;\r\n\r\n    if (_context.Products.Any()) return;\r\n\r\n    ProductSeed.InitData(context);\r\n  }\r\n}<\/pre>\n
Note InitData<\/code> runs the initial seed when there aren\u2019t any products in the database. I set a Route<\/code> that uses versioning which is set via ApiVersion<\/code>. The data context ProductContext<\/code> gets injected in the constructor with Dependency Injection. The first endpoint is GET<\/em> which returns a list of Products in the Controller:<\/p>\n
[HttpGet]\r\n[Route(\"\")]\r\n[ProducesResponseType(StatusCodes.Status200OK)]\r\npublic ActionResult<IQueryable<Product>> GetProducts()\r\n{\r\n  var result = _context.Products as IQueryable<Product>;\r\n\r\n  return Ok(result\r\n    .OrderBy(p => p.ProductNumber));\r\n}<\/pre>\n
Be sure to add Microsoft.AspNetCore.Http<\/code> in a using statement to set status codes in the response type.<\/p>\n
I opted to order products by product number to make it easier to show the results. In a production system, check this sort matches the clustered index, so the database doesn\u2019t work as hard. Always review execution plans and statistics IO to confirm good performance.<\/p>\n
This project is ready to go for a test drive! Inside of a CLI type:<\/p>\n
dotnet watch run<\/pre>\n
Hit the endpoint with curl:<\/p>\n
curl -i -X GET \"http:\/\/localhost:5000\/v1\/products\" -H \"accept: application\/json\"<\/pre>\n
I run both commands in separate consoles. One runs the file watcher that automatically refreshes when I make changes. The other terminal is where I keep curl results. Postman is also useful, but curl gets the job done and comes with Windows 10.<\/p>\n
Below are the results:<\/p>\n
<\/p>\n
This request returns all products in the database, but it\u2019s not scalable. As the product list grows, clients will get slammed with unbound data, putting more pressure on SQL and network traffic.<\/p>\n
A better approach is to introduce limit and offset request parameters in a model:<\/p>\n
public class ProductRequest\r\n{\r\n  [FromQuery(Name = \"limit\")]\r\n  public int Limit { get; set; } = 15;\r\n\r\n  [FromQuery(Name = \"offset\")]\r\n  public int Offset { get; set; }\r\n}\r\n<\/pre>\n
Wire this request parameter to the GetProducts<\/strong> endpoint:<\/p>\n
\n
public ActionResult<IQueryable<Product>>\r\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0 GetProducts([FromQuery] ProductRequest request)\r\n{\r\n\u00a0\u00a0\/\/ ...\r\n\r\n\u00a0\u00a0Response.Headers[\"x-total-count\"] = result.Count().ToString();\r\n\r\n\u00a0\u00a0return Ok(result\r\n\u00a0\u00a0\u00a0\u00a0.OrderBy(p => p.ProductNumber)\r\n\u00a0\u00a0\u00a0\u00a0.Skip(request.Offset)\r\n\u00a0\u00a0\u00a0\u00a0.Take(request.Limit));\r\n}<\/pre>\n
Note I set an HTTP header x-total-count<\/code> with the Count<\/code>. This helps clients that may want to page through the entire result set. When requests parameters are not specified then the API defaults to the first 15 items.<\/p>\n<\/div>\n
Next, add a search parameter to filter products by department:<\/p>\n
public ActionResult<IQueryable<Product>> GetProducts([FromQuery] \r\n             string department, [FromQuery] ProductRequest request)\r\n{\r\n  \/\/ ...\r\n\r\n  if (!string.IsNullOrEmpty(department))\r\n  {\r\n    result = result.Where(p => p.Department.StartsWith(department, \r\n                 StringComparison.InvariantCultureIgnoreCase));\r\n  }\r\n\r\n  \/\/ ..\r\n}<\/pre>\n
Search can go inside a conditional block that alters the query. Note I use StartsWith<\/code> and InvariantCultureIgnoreCase<\/code> to make it easier to filter products. In actual SQL, the LIKE<\/code> operator is useful, and case insensitivity can be set via collation.<\/p>\n
To test out paging and this new filter in curl:<\/p>\n
curl -i -X GET http:\/\/localhost:5000\/v1\/products?offset=15&department=electronics\r\n  -H \"accept: application\/json\"<\/pre>\n
Be sure to check out HTTP headers which include total count and supported versions:<\/p>\n
HTTP\/1.1 200 OK\r\nDate: Sat, 11 Jul 2020 18:35:07 GMT\r\nContent-Type: application\/json; charset=utf-8\r\nServer: Kestrel\r\nContent-Length: 1459\r\nx-total-count: 194\r\napi-supported-versions: 1.0<\/pre>\n
Logging and API Documentation<\/h2>\n
With the API taking shape, how can I communicate endpoints to other developers? It is beneficial for teams to know what the API exposes without having to bust open code. Swagger is the tool of choice here; by using reflection, it is capable of documenting what\u2019s available.<\/p>\n
What if I told you everything swagger needs is already set in this API? Go ahead, take a second look:<\/p>\n
[Produces(\"application\/json\")]\r\n[ProducesResponseType(StatusCodes.Status200OK)]\r\nActionResult<IQueryable<Product>> GetProducts([FromQuery] \r\n               string department, [FromQuery] ProductRequest request)<\/pre>\n
ASP.NET attributes are useful for documenting endpoints. Swagger also picks up return types from controller methods to figure out what responses look like and picks up request parameters in each controller method via reflection. It produces \u201cliving documentation\u201d because it sucks up everything from working code, which reduces mishaps.<\/p>\n
The one dependency lacking is a NuGet:<\/p>\n
dotnet add package Swashbuckle.AspNetCore<\/pre>\n
And wire this up in ConfigureServices<\/code>:<\/p>\n
services.AddSwaggerGen(c => c.SwaggerDoc(\"v1\", new OpenApiInfo\r\n{\r\n  Title = \"Products\",\r\n  Description = \"The ultimate e-commerce store for all your needs\",\r\n  Version = \"v1\"\r\n}));<\/pre>\n
Then, enable this in Configure<\/code>:<\/p>\n
app.UseSwagger();\r\napp.UseSwaggerUI(opt => opt.SwaggerEndpoint(\"\/swagger\/v1\/swagger.json\", \"Products v1\"));<\/pre>\n
Note OpenApiInfo<\/code> comes from the Microsoft.OpenApi.Models<\/code> namespace. With this, navigate to http:\/\/localhost:5000\/swagger<\/em> in the browser to check out the swagger doc.<\/p>\n
The page should look like this:<\/p>\n
<\/p>\n
From the swagger doc, feel free to poke around and fire requests to the API from this tool. Fellow developers from across the organization might even buy you a cup of coffee for making their lives easier.<\/p>\n
Note how expanding GET \/Products picks up C# data types from the method in the controller:<\/p>\n
<\/p>\n
The next stop is the logger. I will use NLog<\/code> to store logs in the back end. This enables the API to save logs for further analysis. In a real environment, logs are useful for troubleshooting outages. They also aid in gathering telemetry to help understand how the API is utilized in the wild.<\/p>\n
To set up the logger, I am going to need the following:<\/p>\n