.NET Core — WebApi tips

Photo by Nick Fewings on Unsplash

Building Api with good practices and proper documentation is important for the development life span of API service.

Today, I will walk you through a sample of an API(that can be improved upon). we will build upon that API example and add a couple of features Like Swagger, Async calls to the Database, and so on.

Let Get Started!!.

1-Cloning the existing Repo.

  • You can find the Repo link here

2-Making our Database calls Asynchronous.

As you can see below the methods in the Interface aren’t Async.
we will go ahead and change that to be Async.

a-Making the Interface methods Asynchronous.

  • Making the methods Asynchronous improves the response time where you can run multiple calls simultaneously and, save time instead of waiting for each call individually.
  • Old version
public interface IBaseRepo<T>    
List<T> GetAll();
T Get(int id);
int Save(T item);
int Delete(T item);
  • Updated
public interface IBaseRepo<T>{  Task<List<T>> GetAll();  Task<T> Get(int id);  Task<int> Save(T item);  Task<int> Delete(T item);}

b-Updating the Repo class methods implementation to be Asynchronous

  • Old version
public class ProductRepo : IProductRepo
private readonly ProductContext _context; public ProductRepo(ProductContext context)
_context = context;
public Product Get(int id)
var product = _context.Products.FirstOrDefault
(i => i.ID == id);
return product;
public List<Product> GetAll()
var products = _context.Products.ToList();
return products;
public int Save(Product item)
if(item.ID == 0)
return _context.SaveChanges();
public int Delete(Product item)
return _context.SaveChanges();
  • Updated
public class ProductRepo : IProductRepo{   private readonly ProductContext _context;  public ProductRepo(ProductContext context)  {      _context = context;   }  public async Task<Product> Get(int id)  {       var product = _context.Products.FirstOrDefaultAsync
(i => i.ID == id);
return await product; } public async Task<List<Product>> GetAll() { var products = _context.Products.ToListAsync(); return await products; } public async Task<int> Save(Product item) { if(item.ID == 0) { _context.Products.Add(item); } else { _context.Products.Update(item); } return await _context.SaveChangesAsync(); } public async Task<int> Delete(Product item) { _context.Remove(item); return await _context.SaveChangesAsync(); }}

3- Updating the controller

In the product Controller, we will make the methods return types strongly typed by specifying the object returned in the ActionResult. This will make sure that we are not returning the wrong data by making the method strongly typed.

  • Updated

4- Adding Swagger for API documentation

a-Downloading the required packages for Swagger.

below are the packages that are required for Swagger and the whole application.

b-applying changes in Startup.cs

In Startup.cs we will need to add the required configuration to enable Swagger and its related dependencies.

  • ConfigureServices
public void ConfigureServices(IServiceCollection services){services.AddScoped<IProductRepo, ProductRepo>();services.AddDbContext<ProductContext>(options => options.UseSqlServer(Configuration.GetConnectionString("DefaultConnection")));var apiInfo = Configuration.GetSection("SwaggerApiInfo").Get<OpenApiInfo>();services.AddSwaggerGen(c =>{c.SwaggerDoc("v1", apiInfo);var xmlFile = $"{Assembly.GetExecutingAssembly().GetName().Name}.xml";var xmlPath = Path.Combine(AppContext.BaseDirectory, xmlFile);c.IncludeXmlComments(xmlPath);});//Ignore Circular relationships.services.AddControllers().AddNewtonsoftJson(options =>options.SerializerSettings.ReferenceLoopHandling =Newtonsoft.Json.ReferenceLoopHandling.Ignore);}
  • Configure
public void Configure(IApplicationBuilder app, IWebHostEnvironment env){if (env.IsDevelopment()){app.UseDeveloperExceptionPage();}app.UseHttpsRedirection();app.UseRouting();app.UseAuthorization();app.UseSwagger();app.UseSwaggerUI(c =>{c.SwaggerEndpoint("/swagger/v1/swagger.json", "My API V1");c.RoutePrefix = string.Empty;});app.UseEndpoints(endpoints =>{endpoints.MapControllers();});}

5-Adding our Swagger Information Object in appSettings.json

We’re adding the information related to the API page in appSettings.json and then we are serializing it to an OpenApiInfo object in ConfigureServices method.

"SwaggerApiInfo": {"title": "Products API - Demo","description": "API demo in .NET Core","version": "V1","Contact": {"name": "Your Name - API","email": "intorToApi@mail.com","url": "example.com"},"Licesne": {"name": "Your name - License","url": "license@example.com"}}

6-Modifying the Project properties to insert XML comments to provide extra information in the UI.

I have applied the below changes to the Project properties in the Build section to enable XML documentation.

7-Redirecting to Swagger UI page upon launching the project

To allow the application to redirect to the API documentation page we need to modify the LaunchURL.

8-Checking the API page

Launch the application you should see this page below.

As you can see we were able to launch the page and all the information we have put in the comments above every method in the controller is reflecting on the page.
There are many more features you can enable in Swagger for more info check the official documentation here


Photo by Sincerely Media on Unsplash

In this example, we’ve managed to improve upon our API documentation and also the API internal structure by adding strongly typed return types in the methods and also making the database calls Asynchgronus. Eventually, we wrapped it up with quick and neat documentation of our simple API service by taking advantage of Swagger.

Hope you’ve liked this piece of content.

Catch you on the next one!!

Full solution REPO




Software developer | Programming and Blockchain enthusiast

Love podcasts or audiobooks? Learn on the go with our new app.

Recommended from Medium

How to teach things badly

Diagram of a chessboard with an en passant move highlighted

Developing an Infrastructure using Terraform with the help of EFS

Using the Unity Animation System

Tempo. How to Read it in Programing

What are Alexa Routines and How to Use Them?

Common Types of Data

Software developers are currently more valuable to companies than money

The positive aspects of Crodo tokenomics

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store
Ibrahim Jaber

Ibrahim Jaber

Software developer | Programming and Blockchain enthusiast

More from Medium

Quick tip — Local environment configuration for Asp.Net Core apps

Build an ASP.NET Core Web API 5.0 with CURD operations using Entity Framework DB first approach.

NET5 Request-Response Logging

Blazor with Auth0, using the Management API