{"id":5030,"date":"2024-02-21T20:08:41","date_gmt":"2024-02-21T20:08:41","guid":{"rendered":"https:\/\/reviewnprep.com\/blog\/?p=5030"},"modified":"2025-09-09T01:29:53","modified_gmt":"2025-09-09T01:29:53","slug":"a-comprehensive-guide-on-creating-apis-in-c","status":"publish","type":"post","link":"https:\/\/reviewnprep.com\/blog\/a-comprehensive-guide-on-creating-apis-in-c\/","title":{"rendered":"A Comprehensive Guide on Creating APIs in C#"},"content":{"rendered":"\n

In the realm of modern software development, creating APIs (Application Programming Interfaces) is essential for facilitating communication between different software systems. In this blog post, we’ll delve into the process of creating APIs in C# using the ASP.NET framework. <\/p>\n\n\n\n

We’ll cover the basics of API development, including the implementation of HTTP methods such as GET, POST, PUT, and DELETE. Additionally, we’ll explore the distinctions between APIs and web services, and provide a practical example that can be tested using Postman. <\/p>\n\n\n\n

Let’s dive in!<\/p>\n\n\n\n

APIs (Application Programming Interfaces) allow different software systems to communicate with each other. APIs work by exposing endpoints that can be called by other programs. In this post, we’ll look at how to create a basic API using C# and ASP.NET Core. <\/p>\n\n\n\n

What is an API?<\/h2>\n\n\n\n

An API is a set of definitions and protocols for building and integrating application software<\/a>. APIs let your product or service communicate with other products and services without having to know how they’re implemented. This allows you to open up data and functionality to other developers and to other systems.<\/p>\n\n\n\n

APIs allow you to securely expose certain parts of your application logic to the outside world in a controlled manner. For example, the Twitter API allows other developers to integrate Twitter data into their own applications, under certain conditions. APIs are the backbone of the interconnected web services we use every day.<\/p>\n\n\n\n

Understanding APIs and Web Services<\/h2>\n\n\n\n

Before we delve into the technical aspects of API development, it’s crucial to grasp the distinction between APIs and web services. While both enable communication between software systems, they differ in their implementation and scope.<\/p>\n\n\n\n

APIs<\/strong> serve as interfaces that allow different software applications to interact with each other. They define the methods and protocols that developers can use to access the functionalities of a software system.<\/p>\n\n\n\n

Web services<\/strong>, on the other hand, are a specific type of API that operates over the web using standard protocols such as HTTP. They typically follow the principles of REST (Representational State Transfer) or SOAP (Simple Object Access Protocol).<\/p>\n\n\n\n

Setting up the Development Environment<\/h2>\n\n\n\n

To create APIs in C#, you’ll need the following prerequisites:<\/p>\n\n\n\n

    \n
  1. Visual Studio Code IDE<\/strong>: To code any software you need an IDE. One of the most popular integrated development environment (IDE) for building .NET applications is Visual Studio Code. You can install the application by going to the official VS Code link from Microsoft<\/a>. <\/li>\n\n\n\n
  2. ASP.NET Core SDK<\/strong>: Ensure that you have the ASP.NET Core SDK installed, as it provides the necessary tools for developing web applications with C#. You can download it from the official .NET link from Microsoft<\/a>.<\/li>\n\n\n\n
  3. Postman<\/strong>: Finally, download and install Postman, a popular API development and testing tool. You’d need Postman to call the various endpoints that we will code in this tutorial. You can download Postman from the official link<\/a>.<\/li>\n\n\n\n
  4. Basic knowledge of C# and .NET Framework is needed.<\/li>\n<\/ol>\n\n\n\n

    It is important to note that VS Code doesn’t include a traditional File<\/strong> > New Project<\/strong> dialog or pre-installed project templates. You’ll need to add additional components<\/a> and scaffolders depending on your development interests. <\/p>\n\n\n\n

    \n

    Pro-Tip: You can install the C# Dev Kit<\/a> within VS Studio Code to test your code with integrated unit test discovery and execution<\/p>\n<\/blockquote>\n\n\n\n

    Creating the API Project<\/h2>\n\n\n\n

    Let’s start by creating a new ASP.NET Web Application project in Visual Studio Code:<\/p>\n\n\n\n

      \n
    1. Create a New Folder<\/strong>: Create a new folder for your C# project using Visual Studio Code’s file explorer or in your terminal\/command prompt.<\/li>\n\n\n\n
    2. Initialize a new C# Project<\/strong>: Open the terminal in Visual Studio Code (press `Ctrl+“) and navigate to your project folder. You can also navigate to Terminal option on the top ribbon of your VS code and click on New Terminal. Run the following command to initialize a new C# project:<\/li>\n<\/ol>\n\n\n\n
      <\/circle><\/circle><\/circle><\/g><\/svg><\/span><\/path><\/path><\/svg><\/span>
      dotnet<\/span> <\/span>new<\/span> <\/span>webapi<\/span> <\/span>-n<\/span> <\/span>MyApiProject<\/span><\/span><\/code><\/pre><\/div>\n\n\n\n
      This will create a new project with the required references and packages needed to build a basic Web API. The folder structure should look something like below: <\/p>\n\n\n\n
      \"\"<\/figure>\n\n\n\n
      Adding a Model<\/h3>\n\n\n\n
      Under the project folder, create a new Models<\/code> folder and add a Product.cs<\/code> class:<\/p>\n\n\n\n
      Now let’s add a simple Product<\/code> model that we will use in our API:<\/p>\n\n\n\n
      <\/circle><\/circle><\/circle><\/g><\/svg><\/span><\/path><\/path><\/svg><\/span>
      namespace<\/span> <\/span>MyApiProject<\/span>.<\/span>Models<\/span><\/span>\n{<\/span><\/span>\n    <\/span>public<\/span> <\/span>class<\/span> <\/span>Product<\/span><\/span>\n    {<\/span><\/span>\n          <\/span>public<\/span> <\/span>Product<\/span>() <\/span><\/span>\n            {<\/span><\/span>\n                Name <\/span>=<\/span> <\/span>""<\/span>; <\/span><\/span>\n            }<\/span><\/span>\n<\/span>\n        <\/span>public<\/span> <\/span>int<\/span> <\/span>Id<\/span> { <\/span>get<\/span>; <\/span>set<\/span>; }<\/span><\/span>\n        <\/span>public<\/span> <\/span>string<\/span> <\/span>Name<\/span> { <\/span>get<\/span>; <\/span>set<\/span>; }<\/span><\/span>\n        <\/span>public<\/span> <\/span>decimal<\/span> <\/span>Price<\/span> { <\/span>get<\/span>; <\/span>set<\/span>; }<\/span><\/span>\n    }<\/span><\/span>\n}<\/span><\/span><\/code><\/pre><\/div>\n\n\n\n
      This Product<\/code> class will act as our data model that we will perform CRUD operations on.<\/p>\n\n\n\n
      Creating the Controller<\/h3>\n\n\n\n
      The main logic of our API will reside in the controller. Let’s add a ProductsController<\/code> under the Controllers folder:<\/p>\n\n\n\n
      <\/circle><\/circle><\/circle><\/g><\/svg><\/span><\/path><\/path><\/svg><\/span>
      using<\/span> <\/span>Microsoft<\/span>.<\/span>AspNetCore<\/span>.<\/span>Mvc<\/span>;<\/span><\/span>\nusing<\/span> <\/span>MyApiProject<\/span>.<\/span>Models<\/span>;<\/span><\/span>\n<\/span>\nnamespace<\/span> <\/span>MyApiProject<\/span>.<\/span>Controllers<\/span><\/span>\n{<\/span><\/span>\n    [<\/span>Route<\/span>(<\/span>"api\/[controller]"<\/span>)]<\/span><\/span>\n    [<\/span>ApiController<\/span>]<\/span><\/span>\n    <\/span>public<\/span> <\/span>class<\/span> <\/span>ProductsController<\/span> : <\/span>ControllerBase<\/span><\/span>\n    {<\/span><\/span>\n        \/\/ Controller methods (We will add the CRUD Logic here)<\/span><\/span>\n    }<\/span><\/span>\n}<\/span><\/span><\/code><\/pre><\/div>\n\n\n\n
      We decorate the class with [Route]<\/code> and [ApiController]<\/code> attributes to mark it as a controller that will handle API requests.<\/p>\n\n\n\n
      Adding CRUD Methods<\/h2>\n\n\n\n
      Now let’s add methods for CRUD operations:<\/p>\n\n\n\n
      Get All Products<\/h3>\n\n\n\n
      GET Method<\/strong> – The GET method in API is used to request data from a specified resource. When a client sends a GET request to a server, it is asking for information from the server. This method is used for retrieving data and should not have any other effect on the data or server state. <\/p>\n\n\n\n
      GET requests are typically used for operations such as reading or fetching data, and they do not have a request body. In RESTful APIs, GET requests are often used to retrieve resource representations, such as retrieving a list of items or fetching a specific item by its unique identifier. <\/p>\n\n\n\n
      Let’s continue with the example of adding a simple GET method to get Products<\/p>\n\n\n\n
      <\/circle><\/circle><\/circle><\/g><\/svg><\/span><\/path><\/path><\/svg><\/span>
      \/\/ GET: api\/products<\/span><\/span>\n[<\/span>HttpGet<\/span>]<\/span><\/span>\npublic<\/span> <\/span>IActionResult<\/span> <\/span>GetProducts<\/span>()<\/span><\/span>\n{<\/span><\/span>\n    \/\/ Return list of products (dummy data)<\/span><\/span>\n    <\/span>return<\/span> <\/span>Ok<\/span>(<\/span>new<\/span> <\/span>List<\/span><<\/span>Product<\/span>><\/span><\/span>\n    {<\/span><\/span>\n        <\/span>new<\/span> <\/span>Product<\/span> { Id <\/span>=<\/span> <\/span>1<\/span>, Name <\/span>=<\/span> <\/span>"Apple"<\/span>, Price <\/span>=<\/span> <\/span>1.99M<\/span> },<\/span><\/span>\n        <\/span>new<\/span> <\/span>Product<\/span> { Id <\/span>=<\/span> <\/span>2<\/span>, Name <\/span>=<\/span> <\/span>"Orange"<\/span>, Price <\/span>=<\/span> <\/span>2.99M<\/span> }, <\/span><\/span>\n    });<\/span><\/span>\n}<\/span><\/span><\/code><\/pre><\/div>\n\n\n\n
      This method handles GET request to \/api\/products<\/code> and returns a list of products.<\/p>\n\n\n\n
      Get Single Product<\/h3>\n\n\n\n
      <\/circle><\/circle><\/circle><\/g><\/svg><\/span><\/path><\/path><\/svg><\/span>
      \/\/ GET: api\/products\/5<\/span><\/span>\n[<\/span>HttpGet<\/span>(<\/span>"{id}"<\/span>)]<\/span><\/span>\npublic<\/span> <\/span>IActionResult<\/span> <\/span>GetProduct<\/span>(<\/span>int<\/span> <\/span>id<\/span>)<\/span><\/span>\n{<\/span><\/span>\n    \/\/ Return single product (dummy data)<\/span><\/span>\n    <\/span>var<\/span> <\/span>product<\/span> <\/span>=<\/span> <\/span>new<\/span> <\/span>Product<\/span> { Id <\/span>=<\/span> id, Name <\/span>=<\/span> <\/span>"Tomato"<\/span>, Price <\/span>=<\/span> <\/span>3.99M<\/span> };<\/span><\/span>\n    <\/span><\/span>\n    <\/span>return<\/span> <\/span>Ok<\/span>(product);<\/span><\/span>\n}<\/span><\/span><\/code><\/pre><\/div>\n\n\n\n
      This method takes an id<\/code> parameter from route and returns a single product object.<\/p>\n\n\n\n
      Create Product<\/h3>\n\n\n\n
      Post<\/strong> Method<\/strong> – The POST method is used to submit data to be processed to a specified resource. When a client sends a POST request to a server, it is requesting the server to accept and store the enclosed entity, usually as a new resource or as an update to an existing resource.<\/p>\n\n\n\n
      POST requests often include a request body containing data that the server needs to process. Common use cases for POST requests include creating new resources, submitting form data, and performing actions that result in state changes on the server.<\/p>\n\n\n\n
      <\/circle><\/circle><\/circle><\/g><\/svg><\/span><\/path><\/path><\/svg><\/span>
      \/\/ POST: api\/products<\/span><\/span>\n[<\/span>HttpPost<\/span>]<\/span><\/span>\npublic<\/span> <\/span>IActionResult<\/span> <\/span>CreateProduct<\/span>([<\/span>FromBody<\/span>] <\/span>Product<\/span> <\/span>product<\/span>)<\/span><\/span>\n{<\/span><\/span>\n    \/\/ Create product logic here<\/span><\/span>\n    <\/span><\/span>\n    <\/span>return<\/span> <\/span>CreatedAtAction<\/span>(<\/span>nameof<\/span>(GetProduct), <\/span>new<\/span> { id <\/span>=<\/span> product.Id }, product); <\/span><\/span>\n}<\/span><\/span><\/code><\/pre><\/div>\n\n\n\n
      Here we handle POST request, take Product<\/code> object from request body, create product and return 201 response.<\/p>\n\n\n\n
      Update Product<\/h3>\n\n\n\n
      Put Method: <\/strong>The PUT method is used to update or replace a resource identified by a specific URI (Uniform Resource Identifier). When a client sends a PUT request to a server, it is requesting the server to update the resource at the given URI with the enclosed entity in the request body.<\/p>\n\n\n\n
      PUT requests are idempotent, meaning that multiple identical requests should have the same effect as a single request. PUT requests are commonly used for updating existing resources with new data provided in the request body.<\/p>\n\n\n\n
      <\/circle><\/circle><\/circle><\/g><\/svg><\/span><\/path><\/path><\/svg><\/span>
      \/\/ PUT: api\/products\/5<\/span><\/span>\n[<\/span>HttpPut<\/span>(<\/span>"{id}"<\/span>)]<\/span><\/span>\npublic<\/span> <\/span>IActionResult<\/span> <\/span>UpdateProduct<\/span>(<\/span>int<\/span> <\/span>id<\/span>, [<\/span>FromBody<\/span>] <\/span>Product<\/span> <\/span>product<\/span>)<\/span><\/span>\n{<\/span><\/span>\n    \/\/ Update product logic here<\/span><\/span>\n    <\/span><\/span>\n    <\/span>return<\/span> <\/span>NoContent<\/span>();<\/span><\/span>\n}<\/span><\/span><\/code><\/pre><\/div>\n\n\n\n
      This method handles PUT request, takes id<\/code> from route and updated Product<\/code> object from body and updates the product.<\/p>\n\n\n\n
      Delete Product<\/h3>\n\n\n\n
      DELETE Method: <\/strong>The DELETE method is used to request the removal of a specific resource from the server. When a client sends a DELETE request to a server, it is asking the server to delete the resource identified by the specified URI.<\/p>\n\n\n\n
      DELETE requests are idempotent, meaning that making the same request multiple times should have the same effect as a single request. DELETE requests are typically used to delete resources that are no longer needed or to perform cleanup operations.<\/p>\n\n\n\n
      <\/circle><\/circle><\/circle><\/g><\/svg><\/span><\/path><\/path><\/svg><\/span>
      \/\/ DELETE: api\/products\/5 <\/span><\/span>\n[<\/span>HttpDelete<\/span>(<\/span>"{id}"<\/span>)]<\/span><\/span>\npublic<\/span> <\/span>IActionResult<\/span> <\/span>DeleteProduct<\/span>(<\/span>int<\/span> <\/span>id<\/span>)<\/span><\/span>\n{<\/span><\/span>\n    \/\/ Delete product logic here<\/span><\/span>\n    <\/span><\/span>\n    <\/span>return<\/span> <\/span>NoContent<\/span>();<\/span><\/span>\n}<\/span><\/span><\/code><\/pre><\/div>\n\n\n\n
      This method handles DELETE request, takes id<\/code> from route and deletes the product.<\/p>\n\n\n\n
      That completes the basic CRUD methods for our API!<\/p>\n\n\n\n
      Here is the complete code for ProductsController.cs with some sample data<\/p>\n\n\n\n
      <\/circle><\/circle><\/circle><\/g><\/svg><\/span><\/path><\/path><\/svg><\/span>
      using<\/span> <\/span>Microsoft<\/span>.<\/span>AspNetCore<\/span>.<\/span>Mvc<\/span>;<\/span><\/span>\nusing<\/span> <\/span>MyApiProject<\/span>.<\/span>Models<\/span>;<\/span><\/span>\n<\/span>\nnamespace<\/span> <\/span>MyApiProject<\/span>.<\/span>Controllers<\/span><\/span>\n{<\/span><\/span>\n  [<\/span>Route<\/span>(<\/span>"api\/[controller]"<\/span>)]<\/span><\/span>\n  [<\/span>ApiController<\/span>]<\/span><\/span>\n  <\/span>public<\/span> <\/span>class<\/span> <\/span>ProductsController<\/span> : <\/span>ControllerBase<\/span><\/span>\n  {<\/span><\/span>\n    \/\/ GET All <\/span><\/span>\n    [<\/span>HttpGet<\/span>]<\/span><\/span>\n    <\/span>public<\/span> <\/span>IActionResult<\/span> <\/span>GetProducts<\/span>()<\/span><\/span>\n    {<\/span><\/span>\n      <\/span>return<\/span> <\/span>Ok<\/span>(<\/span>GetSampleProducts<\/span>());<\/span><\/span>\n    }<\/span><\/span>\n<\/span>\n    \/\/ GET by Id<\/span><\/span>\n    [<\/span>HttpGet<\/span>(<\/span>"{id}"<\/span>)]<\/span><\/span>\n    <\/span>public<\/span> <\/span>IActionResult<\/span> <\/span>GetProduct<\/span>(<\/span>int<\/span> <\/span>id<\/span>)<\/span><\/span>\n    {<\/span><\/span>\n      <\/span>return<\/span> <\/span>Ok<\/span>(<\/span>GetSampleProducts<\/span>().<\/span>FirstOrDefault<\/span>(<\/span>x<\/span> <\/span>=><\/span> x.Id <\/span>==<\/span> id));<\/span><\/span>\n    }<\/span><\/span>\n<\/span>\n    \/\/ POST<\/span><\/span>\n    [<\/span>HttpPost<\/span>]<\/span><\/span>\n    <\/span>public<\/span> <\/span>IActionResult<\/span> <\/span>CreateProduct<\/span>([<\/span>FromBody<\/span>] <\/span>Product<\/span> <\/span>product<\/span>)<\/span><\/span>\n    {<\/span><\/span>\n      \/\/ Save product<\/span><\/span>\n      <\/span>return<\/span> <\/span>CreatedAtAction<\/span>(<\/span>nameof<\/span>(GetProduct), <\/span>new<\/span> { id <\/span>=<\/span> product.Id }, product);<\/span><\/span>\n    }<\/span><\/span>\n<\/span>\n    \/\/ PUT<\/span><\/span>\n    [<\/span>HttpPut<\/span>(<\/span>"{id}"<\/span>)]<\/span><\/span>\n    <\/span>public<\/span> <\/span>IActionResult<\/span> <\/span>UpdateProduct<\/span>(<\/span>int<\/span> <\/span>id<\/span>, [<\/span>FromBody<\/span>] <\/span>Product<\/span> <\/span>product<\/span>)<\/span><\/span>\n    {<\/span><\/span>\n      \/\/ Update product <\/span><\/span>\n      <\/span>return<\/span> <\/span>NoContent<\/span>();<\/span><\/span>\n    }<\/span><\/span>\n<\/span>\n    \/\/ DELETE<\/span><\/span>\n    [<\/span>HttpDelete<\/span>(<\/span>"{id}"<\/span>)]<\/span><\/span>\n    <\/span>public<\/span> <\/span>IActionResult<\/span> <\/span>DeleteProduct<\/span>(<\/span>int<\/span> <\/span>id<\/span>)<\/span><\/span>\n    {<\/span><\/span>\n      \/\/ Delete product<\/span><\/span>\n      <\/span>return<\/span> <\/span>NoContent<\/span>(); <\/span><\/span>\n    }<\/span><\/span>\n<\/span>\n    \/\/ Sample data<\/span><\/span>\n    <\/span>List<\/span><<\/span>Product<\/span>> <\/span>GetSampleProducts<\/span>()<\/span><\/span>\n    {<\/span><\/span>\n      <\/span>return<\/span> <\/span>new<\/span> <\/span>List<\/span><<\/span>Product<\/span>>()<\/span><\/span>\n      {<\/span><\/span>\n        <\/span>new<\/span> <\/span>Product<\/span>() { Id <\/span>=<\/span> <\/span>1<\/span>, Name <\/span>=<\/span> <\/span>"Apple"<\/span>, Price <\/span>=<\/span> <\/span>1.50M<\/span> },<\/span><\/span>\n        <\/span>new<\/span> <\/span>Product<\/span>() { Id <\/span>=<\/span> <\/span>2<\/span>, Name <\/span>=<\/span> <\/span>"Orange"<\/span>, Price <\/span>=<\/span> <\/span>2.50M<\/span> },<\/span><\/span>\n      };<\/span><\/span>\n    }<\/span><\/span>\n  }<\/span><\/span>\n}<\/span><\/span><\/code><\/pre><\/div>\n\n\n\n
      Changes to Program.cs<\/h3>\n\n\n\n
      Finally, add code to set up the web host and map the Controllers for routing.<\/p>\n\n\n\n
      <\/circle><\/circle><\/circle><\/g><\/svg><\/span><\/path><\/path><\/svg><\/span>
      using<\/span> <\/span>Microsoft.AspNetCore.Mvc<\/span>;<\/span><\/span>\nusing<\/span> <\/span>MyApiProject.Models<\/span>;<\/span><\/span>\n<\/span>\nvar<\/span> <\/span>builder<\/span> <\/span>=<\/span> <\/span>WebApplication.CreateBuilder<\/span>(<\/span>args<\/span>);<\/span><\/span>\n<\/span>\n\/\/<\/span> <\/span>Add<\/span> <\/span>services<\/span> <\/span>to<\/span> <\/span>the<\/span> <\/span>container.<\/span><\/span>\nbuilder.Services.AddControllers<\/span>(); <\/span><\/span>\n<\/span>\nvar<\/span> <\/span>app<\/span> <\/span>=<\/span> <\/span>builder.Build<\/span>();<\/span><\/span>\n<\/span>\n\/\/<\/span> <\/span>Configure<\/span> <\/span>the<\/span> <\/span>HTTP<\/span> <\/span>request<\/span> <\/span>pipeline.<\/span><\/span>\napp.UseHttpsRedirection<\/span>();<\/span><\/span>\n<\/span>\napp.UseAuthorization<\/span>();<\/span><\/span>\n<\/span>\napp.MapControllers<\/span>(); <\/span><\/span>\n<\/span>\napp.Run<\/span>();<\/span><\/span><\/code><\/pre><\/div>\n\n\n\n
      Build and Run<\/h2>\n\n\n\n
      Before we test the API, let’s do a build and run. Build compiles the code and checks for the errors, run command starts the localhost server. <\/p>\n\n\n\n