(C# ASP.NET Core) Minimal GET WebApi with a Parameter of Numeric Type

The URL for a GET Api that accepts parameters

Let us first learn how to decide on the URL of an API that accepts parameters.

The technique is to add the parameter as a segment of the URL. For example, if the API is /doctor/fees/, and let us suppose the parameter is called amt, then the URL for the API would be /doctor/fees/{amt}. Note that curly braces are required to define the route parameters.

We can add some route constraints to this parameter. The first is that we can restrict its datatype to an int type so that only numeric parameters are matched. For this, a datatype constraint is specified in a template like this: /doctor/fees/{amt:int}

// data-type constraint on route parameter 

http://localhost:port/doctor/fees/{amt:int}

  

int is not the only possibility. We can specify various other data-types such as bool, datetime, decimal, double, float, guid, long and even regular expressions. You will have to refer msdn documentation for finer detail.

A range constraint can be added too. For example, we can specify a minimum value. A minimum value of zero can be specified thus: /doctor/fees/{amt:int:min(0)}

// range constraint on route parameter 

http://localhost:port/doctor/fees/{amt:int:min(0)}
  
  

A benefit of route constraints is that if a URL doesn't match the template, then the ASPNET Core Engine rejects that request before it reaches the API function, preventing disruptive exceptions from being thrown. It sends a 404 NotFound response.

Video Explanation (see it happen!)

Please watch the following youtube video:

Adding the WebApi to the Program.cs File

Next we add this, new, web api to our program.cs file. Open the solution explorer and locate the program.cs file. Double click and open it so that we can examine the code.

This is the program.cs file. Let us scroll towards the end where we have already added the new api.

// Program.cs file 
// . 
// . 
// . see this code  in previous tutorial 
// . or see the attached downloads of this course 

// API no param (see prev. tutorial) 
app.MapGet("/doctor/all", async (MyApiContext ctx) =>
  {
    return await ctx.Doctors.ToListAsync();

  }
);


// API with a route param 
app.MapGet(
  "/doctor/fees/{amt:int:min(0)}",
  async (MyApiContext ctx, int amt) =>
  {
    return await ctx.Doctors.Where(d => d.Fees > amt).ToListAsync();

  }
);

app.MapRazorPages();

app.Run();

As you can see this API now accepts a parameter called amt, and it must be an int type, and of minimum value of zero.

It returns all the records that have a fees value that exceeds the specified parameter.

Run the Project

We can now run the project and call the api by passing a parameter of value 100. The route now becomes: /doctor/fees/100

  
  /doctor/fees/100

  

Run the project and verify that only the matching records are returned, and therefore the API is working as expected (see the attached video).

Next let us try a URL that will fail the constraints. So we can try this URL: /doctor/fees/abc. And we verify that the request fails with a 404 error (see the attached video).

  
  /doctor/fees/abc

  

You can obtain the source code from the attached downloads. Thankyou!