ASP.NET Core  

Understanding API in .NET Core — A Beginner-Friendly Guide with Real-Life Example

api

Introduction

APIs are everywhere in software development. Every time you use a mobile app, a website, or even smart devices, APIs help different systems communicate. In .NET Core, APIs let you create web services that send and receive data. This is especially useful in real-world applications like:

  • Employee management portals

  • Job boards

  • Flight booking systems

In this article, we will

  • Understand what an API is

  • Learn about endpoints

  • Create a simple API in .NET Core

  • See a real-life developer example

We will keep it simple and beginner-friendly, with clear explanations and code comments.

What is an API?

API stands for Application Programming Interface.

It helps two applications talk to each other — for example, your frontend app (React, Angular) and backend (database, server logic).

Think of it like a restaurant

  • You (frontend) tell the waiter (API) what you want.

  • The waiter (API) takes the order to the kitchen (backend).

  • The kitchen prepares the food (data).

  • The waiter brings it back to you.

Developer Example
Imagine a job portal. The frontend React app needs the list of jobs from the backend. The API delivers the data to display it on the web page — just like the waiter bringing your food.

What is an API Endpoint?

An endpoint is a specific URL where your API provides a service. It’s like a doorway through which the client (frontend) can ask the server (backend) for information or send data. Each endpoint usually performs a single action, such as retrieving a list of developers, fetching details of one developer, or adding a new developer.

Example

GET /api/developer       => get all developers
GET /api/developer/1      => get developer with ID 1
POST /api/developer       => add a new developer

Developer Scenario

In a job portal, endpoints like GET /api/jobs or POST /api/jobs allow the frontend to show all jobs or add a new job posting. Without endpoints, the frontend and backend cannot communicate in a structured way.

Developer Example: Real-World Job Portal

Imagine you are building a job portal where users can browse and apply for jobs. Each action in the portal - like fetching jobs, adding a new job, or viewing job details - is handled by a specific endpoint in your API.

Example Endpoints

GET /api/jobs        => Fetch all available jobs
POST /api/jobs       => Add a new job posting
GET /api/jobs/123    => Fetch details of a specific job (ID = 123)

How it works

  1. GET /api/jobs

    • The frontend (React or Angular app) calls this endpoint to get a list of all jobs.

    • The API retrieves the jobs from the backend (database or storage) and sends them to the frontend.

    • Users see all the jobs listed in the portal.

  2. POST /api/jobs

    • When an HR manager adds a new job, the frontend sends the job details to this endpoint.

    • The API saves the job in the backend and confirms success.

    • The new job now appears in the portal automatically.

  3. GET /api/jobs/123

    • When a user clicks on a specific job to view details, this endpoint fetches only that job’s information.

    • The API returns the data, and the frontend displays it accurately to the user.

Why this matters:
Endpoints like these simplify communication between the frontend and backend. Each endpoint performs a single action, making your code clean, organized, and easy to maintain.

Create a Simple Web API in .NET Core

We’ll use .NET 6 or later.

Step 1. Create a New Project

In Visual Studio:
File => New => Project => ASP .NET Core Web API => Next => Create

You’ll see a default controller WeatherForecastController.cs. We will create our own DeveloperController.

Create Developer Controller with Comments

using Microsoft.AspNetCore.Mvc;

namespace MyFirstApi.Controllers
{
    // This attribute tells .NET Core that this class is an API controller
    [ApiController]
    // Base route for this controller: api/developer
    [Route("api/[controller]")]
    public class DeveloperController : ControllerBase
    {
        // Static list to store developer names (temporary in-memory storage)
        private static List<string> developers = new List<string> { "Rudra", "Abhinav", "Sham" };

        // GET: api/developer
        // Returns all developers in the list
        [HttpGet]
        public IActionResult GetAllDevelopers()
        {
            return Ok(developers); // 200 OK with the list of developers
        }

        // GET: api/developer/{id}
        // Returns a developer by index (id)
        [HttpGet("{id}")]
        public IActionResult GetDeveloperById(int id)
        {
            // Check if id is valid
            if (id < 0 || id >= developers.Count)
                return NotFound("Developer not found"); // 404 if invalid
            
            return Ok(developers[id]); // 200 OK with developer name
        }

        // POST: api/developer
        // Adds a new developer to the list
        [HttpPost]
        public IActionResult AddDeveloper([FromBody] string name)
        {
            developers.Add(name); // Add new developer
            return Ok($"Developer '{name}' added successfully!"); // Confirm success
        }
    }
}

Concept Behind the Code

  1. Controller: Handles API requests. Each method corresponds to an endpoint.

  2. List of developers: Temporary storage for demonstration. In real projects, data comes from a database.

  3. HttpGet / HttpPost: Attributes define which HTTP request each method handles.

  4. Return types (Ok / NotFound): Standard HTTP responses that tell the client what happened.

What’s Happening Inside the Code

Let’s break down the DeveloperController and see what each part does:

  1. Controller (DeveloperController)

    • This is the class that handles API requests.

    • In .NET Core, each controller group contains related endpoints.

    • Example: DeveloperController handles requests about developers.

  2. List of developers (private static List<string> developers)

    • This is a temporary in-memory storage for demonstration purposes.

    • In a real application, this would usually be data from a database.

    • The list stores the names of developers and can be updated or retrieved.

  3. [HttpGet] and [HttpPost] Attributes

    • These define the type of HTTP request the method will respond to.

    • [HttpGet] => used when the client wants to retrieve data.

    • [HttpPost]=> used when the client wants to send data to the server.

  4. Endpoints (Methods inside the controller)

    • GetAllDevelopers()=> Returns all developers in the list.

      • Concept: A client calls this endpoint to get all data (read operation).

    • GetDeveloperById(int id)=> Returns a specific developer by index.

      • Concept: Fetches single item using an identifier (read operation).

      • Checks if the ID is valid. If not, returns NotFound() (404).

    • AddDeveloper([FromBody] string name)=> Adds a new developer.

      • Concept: Accepts input from the client (JSON or plain text) and adds it to the list (create operation).

  5. Return types (Ok(), NotFound())

    • Ok()=> Returns HTTP 200 with the requested data.

    • NotFound()=> Returns HTTP 404 if the requested data doesn’t exist.

    • Concept: HTTP responses communicate status to the client so the frontend knows what happened.

Developer Example in Action

In a real employee portal, the same API logic would work like this:

  • Show all employees (GET /api/developer)

    • Frontend calls this endpoint => server returns the list => users see all employees.

  • Add a new employee (POST /api/developer)

    • HR manager submits new employee data => server adds it => frontend displays the new employee automatically.

  • Show details of a specific employee (GET /api/developer/{id})

    • User clicks on a profile => frontend calls the endpoint with ID => server returns specific employee details => displayed to the user.

Concept Summary

  • Controller = handles related API requests

  • Methods/Endpoints = each does one specific job

  • Attributes = tell which HTTP request type is supported

  • Return types = communicate status back to frontend

  • Data storage = temporary list in demo; database in real apps

This explanation links the code to the concept, making it easy for beginners to understand what each line is doing and why it matters.

Run and Test in Swagger

When you run your .NET Core Web API project (press F5 in Visual Studio), it automatically opens Swagger UI in your browser.

What is Swagger in API

  • Swagger is a tool that generates interactive documentation for your API.

  • It shows all your endpoints, the HTTP methods they support (GET, POST, etc.), and allows you to test them directly without writing frontend code.

What is happening behind the scenes

  1. Swagger reads your API code — looks at controllers, routes, and attributes ([HttpGet], [HttpPost]).

  2. It generates a UI showing all endpoints, expected input, and possible responses.

  3. When you click “Execute”, Swagger sends a request to your API, just like a frontend application would.

  4. The API processes the request and returns a response — you can see data returned, status codes (200, 404, etc.), and any error messages directly in Swagger.

Run and Test in Swagger

  1. GET /api/developer

    • Click “Try it out” => “Execute”

    • API returns the list of developers => Swagger shows 200 OK and the data

  2. POST /api/developer

    • Click “Try it out” => enter "John" in the request body => Execute

    • API adds John to the list => Swagger shows confirmation message

  3. GET /api/developer/1

    • Fetch a specific developer by ID => API returns the developer name => Swagger shows the response

Why Swagger is important

  • You don’t need to write frontend code to test your API.

  • You can see exactly what data your API expects and returns.

  • Helps debug API endpoints quickly during development.

  • Makes it easier to explain your API to team members or clients.

Tip for beginners:
Always use Swagger to test your endpoints while coding. It helps you understand the flow of requests and responses, and makes learning APIs much faster.

What’s Next?

In the next step, we’ll connect this API to a SQL Server database using Entity Framework Core. This will replace the temporary static list with real, persistent data, making your API fully functional and ready for real-world applications.

✍️ Final Thoughts

APIs in .NET Core act as messengers between the frontend and backend.
Once you understand controllers, routes, and endpoints, you can seamlessly connect web apps, mobile apps, or third-party tools.

Thank you for reading! I hope this guide helps you build your first .NET Core API with confidence.

Take the next step: create your first API, test it in Swagger, and share your results with the developer community on C# Corner!

Learn how to create a beginner-friendly .NET Core Web API with clear code comments, real-world examples, and step-by-step explanations.

Membership not found