APIs & How To Create Your Own With .NET Minimal API

Programming & Tech

APIs & How To Create Your Own With .NET Minimal API

When you start your development journey there are certain words that stick with you from start to finish. Algorithm, Data Structure … etc.

These words start loosing their relevance once you get more advanced. But there is a word that becomes even more relevant at this stage and that’s API.

API this, API that, is all you hear when working on a professional job environment.

And for anyone that does any programming, Working with APIs or even knowing how they work so they can create ones is a great skill.

Today we are going to see what an API is and how to create one using .NET Minimal APIs.


Join our newsletter for more cool posts like this


Content Table

  • What is An API ?
  • How Does it work ?
  • Why Use APIs ?
  • REST vs SOAP
  • API Authentication
  • Make An API in .NET using Minimal APIs

What is An API ?

API or Application Programming Interface, in general terms is a way to connect computer programs. It is basically a software that provides services, connect different software. APIs are not intended to be used directly by end-users.

An API is generally used to unify the way software interacts with other software, and to unify the way that software gets its data and hides internal implementation details. As these days no software really works directly with a database and everything goes through an API.

How Does An API Work ?

How the API works | ESET MSP Administrator 2 API Guide | ESET Online Help
Source : ESET Online

There are two main components : the API and the client. When the client needs data, or needs to use a function of the API he does a call. Most of the calls these days are sent to REST APIs so they first specify the Request Type ( Get, Post ….) And Then add parameters, data or whatever the API needs to fulfill the request.

The Request is sent then to the API, where it is processed and the result status is sent back with/without data depending on the functionality.

There are multiple result status From 2xx To indicate success, 3xx for redirection, 4xx client errors and 5xx for server errors.

Why Use APIs ?

APIs are all about integrating and synchronizing functionality and data between all related software. It simplifies the process of creating software for new platforms as it gives the developer the necessary data without the need for the developer to know what database it is using or what query to use.

APIs takes the DRY (Don’t Repeat Yourself) principle to the next level. you write the data access code or the functionality once and use it across multiple devices and multiple platforms.

As most businesses these days are data-driven, APIs can prove to be an essential tool to use for better productivity and integration between different business software.

REST vs SOAP

If you have ever seen an API you must’ve at least heard the word REST.

so REST and SOAP are ways to simplify API design, and they represent a set of Rules that the software has to follow.

SOAP : Simple Object Access Protocol a way to allow client software to receive data regardless of what platform they are using, it mostly uses XML to send results back.

Webservice xrpc.png
Source Wikipedia

REST : REpresentational State Transfer it offers the client a way to interact with the API using different command requests the four most used are : GET, POST, PUT, DELETE. Client can also send data or query parameters and the API will process them according to the type of request. The goal of REST is to increase performance, scalability, simplicity, modifiability, visibility, portability, and reliability.

What is REST API | PHPenthusiast
Source : phpenthusiast.com

Generally these days most of APIs use the REST Standard.

API Authentication

As you know, not all APIs are free there are more paid options than free and people make millions from APIs.

To Secure you API you use Authentication, it is very similar to Login in a normal website.

There are multiple ways to Authenticate The user. the most used are either using An API Key or using a Token.

API Key : the client has an API key that he sends with each request, these APIs are only generated once.

JWT Token : it is a token that is generated by a request by the client and used on the following requests for a certain time until the token has expired.

There is also OAuth, but that’s a whole other thing.

Creating Your Own API using .NET Minimal API

The API that we are going to create is to just give you a general idea on how APIs work.

For this API we are going to take a string parameter and split it by a certain character that is given by the user as a parameter also, And finally return the List result.

There will be a second endpoint where we are going to use authentication to

To create our simple API we are going to open visual studio 2022 And click on create new project.

We search for API and select ASP.NET Core Web API.

Visual Studio Create a new project

Name your project and then UnSelect the Use Controllers checkbox to allow for minimal APIs

Additional information

Unlike your usual .net core API Project this one doesn’t have much C# only one file. I only recommend this project type when the project is a proof of concept.

You only have one file to work with in the beginning and that’s Program.cs.

Delete all the unnecessary files until the file resembles something like this.

So Let’s Explain this line by line.

var builder = WebApplication.CreateBuilder(args);

is used to create an instance of the WebApplication class, which basically means we create the web application with a port to listen to and all the necessary basic things.

builder.Services.AddEndpointsApiExplorer();
builder.Services.AddSwaggerGen();

var app = builder.Build();

We configure the Swagger service that adds automatic documentation for the API. the last line tells the App to build these service and get them ready for use.

To see what port you can check Properties > launchSettings.json

if (app.Environment.IsDevelopment())
{
    app.UseSwagger();
    app.UseSwaggerUI();
}

We activate swagger if the Environment is for development.

app.UseHttpsRedirection();

This is used to accept pages redirecting the client towards Endpoints in the API.

Then you will find the API Endpoints and lastly :

app.Run();

which starts the app on the designated port.

Endpoint With No Authorization :

So Let’s create our first endpoint. put this code before the app.run line.

we want this endpoint to take a string as an input and return the string split using a character that the user entered.

so we start by defining the endpoint :

app.MapGet("/SplitString", () =>
{
    return "hello world";
});

MapGet is to create a route that uses the method GET (using REST standard). the first argument it takes is the route to the endpoint, the second argument is basically the code that the endpoint executes or the service it provides.

inside the anonymous function we return the result of the API endpoint in this case it is a simple Hello world as always.

Now click on the green arrow at the top test the API. i recommend you change it from iis Express to the name of your project.

Ignore the error and go to the page

This is the swagger documentation page where you can test all your endpoints without leaving your app.

There you go we have our hello world. now let’s get inputs from the client as parameters. And let’s split the input using the Client defined character.

app.MapGet("/SplitString", (string inp, char splitter) =>
{
    return inp.Split(splitter);
});

Now let’s try our API again. Now when you enter you will notice that the parameters were added

Let’s fill these field with data and test the Endpoint.

We get the following result.

Then now let’s do something more interesting Let’s add an endpoint that saves a list of character that we post to it locally and displays them when we we get them from another endpoint.

// Create The List 
List<string> elements = new();

// Create The Endpoint 
app.MapPost("/SaveToList", (string input) =>
{
    elements.Add(inp);
    return ;
});

// Return The List Of Saved Elements
app.MapGet("/ShowList", () =>
{
    return elements;
});

This was easy, now let’s add some basic authorization so that we can finish this starter tutorial.

as i said previously about basic authentication, usually the API key is sent as a paramter so let’s add a parameter called API key. and check if it is valid.


List<string> elements = new();
string[] Keys = new string[2] { "ABCDE", "DEFGH" };

app.MapPost("/SaveToList", (string APIKey, string input) =>
{
    if(Keys.Contains(APIKey))
        elements.Add(input);
    return ;
});

app.MapGet("/ShowList", (string APIKey) =>
{
    if (Keys.Contains(APIKey))
        return elements;
    return null;
});

Now we have a basic API endpoint and some other Endpoints with basic authorization.

if you want a longer tutorial comment down bellow.

For a cooler tutorial check https://docs.microsoft.com/en-us/aspnet/core/tutorials/min-web-api?view=aspnetcore-6.0&tabs=visual-studio

Resources :

API – Wikipedia : https://en.wikipedia.org/wiki/API

Understanding APIs – Red hat : https://www.redhat.com/en/topics/api

What is an API ? – Cleo : https://www.cleo.com/blog/knowledge-base-what-is-an-api

Tags: , , , , ,

Leave a Reply