org_roam/Career Concepts/20260305132058-restful_api.org

RESTful APIs

• What is a RESTful API?
• Core HTTP Methods
• Example Resource: User
• Creating a REST API in C# (ASP.NET Core)
• Defining a Model
• Creating a Controller
• Getting a Single Resource
• Creating a Resource (POST)
• Updating a Resource (PUT)
• Deleting a Resource
• REST Principles
  • 1. Statelessness
  • 2. Resource-Based URLs
  • 3. Standard HTTP Status Codes
• Example Full API Structure
• Testing the API
• Summary

What is a RESTful API?

A RESTful API is a web service that follows the principles of REST (Representational State Transfer). REST is an architectural style used for designing networked applications.

In a RESTful system:

• Everything is treated as a resource
• Resources are identified using URLs
• Standard HTTP methods are used to interact with resources
• Communication is usually done using JSON

Example resource:

/users
/users/1
/users/1/orders

These represent data stored on the server.

Core HTTP Methods

REST APIs rely heavily on HTTP verbs.

Method	Purpose	Example Endpoint
GET	Retrieve data	GET /users
POST	Create a new resource	POST /users
PUT	Update an existing resource	PUT /users/1
DELETE	Remove a resource	DELETE /users/1

Example Resource: User

Assume we have a simple User resource:

{
  "id": 1,
  "name": "Alice",
  "email": "alice@email.com"
}

The API allows clients to create, read, update, and delete users.

Creating a REST API in C# (ASP.NET Core)

In C#, REST APIs are commonly built using ASP.NET Core Web API.

Example project creation:

dotnet new webapi -n UserApi
cd UserApi
dotnet run

This creates a ready-to-run REST API project.

Defining a Model

First, define the resource model.

File: Models/User.cs

namespace UserApi.Models
{
    public class User
    {
        public int Id { get; set; }

        public string Name { get; set; }

        public string Email { get; set; }
    }
}

This represents the data stored and returned by the API.

Creating a Controller

Controllers handle HTTP requests.

File: Controllers/UserController.cs

using Microsoft.AspNetCore.Mvc;
using UserApi.Models;

namespace UserApi.Controllers
{
    [ApiController]
    [Route("api/[controller]")]
    public class UserController : ControllerBase
    {
        private static List<User> users = new List<User>()
        {
            new User { Id = 1, Name = "Alice", Email = "alice@email.com" },
            new User { Id = 2, Name = "Bob", Email = "bob@email.com" }
        };

        [HttpGet]
        public ActionResult<List<User>> GetUsers()
        {
            return Ok(users);
        }
    }
}

Endpoint created:

GET /api/user

Response:

[
  { "id": 1, "name": "Alice", "email": "alice@email.com" },
  { "id": 2, "name": "Bob", "email": "bob@email.com" }
]

Getting a Single Resource

Add an endpoint to retrieve a specific user.

[HttpGet("{id}")]
public ActionResult<User> GetUser(int id)
{
    var user = users.FirstOrDefault(u => u.Id == id);

    if (user == null)
    {
        return NotFound();
    }

    return Ok(user);
}

Endpoint:

GET /api/user/1

Creating a Resource (POST)

Clients send JSON data to create a new user.

[HttpPost]
public ActionResult<User> CreateUser(User newUser)
{
    newUser.Id = users.Max(u => u.Id) + 1;
    users.Add(newUser);

    return CreatedAtAction(nameof(GetUser), new { id = newUser.Id }, newUser);
}

Example request:

POST /api/user

{
  "name": "Charlie",
  "email": "charlie@email.com"
}

Updating a Resource (PUT)

[HttpPut("{id}")]
public IActionResult UpdateUser(int id, User updatedUser)
{
    var user = users.FirstOrDefault(u => u.Id == id);

    if (user == null)
    {
        return NotFound();
    }

    user.Name = updatedUser.Name;
    user.Email = updatedUser.Email;

    return NoContent();
}

Endpoint:

PUT /api/user/1

Deleting a Resource

[HttpDelete("{id}")]
public IActionResult DeleteUser(int id)
{
    var user = users.FirstOrDefault(u => u.Id == id);

    if (user == null)
    {
        return NotFound();
    }

    users.Remove(user);

    return NoContent();
}

Endpoint:

DELETE /api/user/1

REST Principles

A good REST API should follow these key ideas:

1. Statelessness

Each request contains all information needed.

The server does not store client session state.

2. Resource-Based URLs

Endpoints should represent nouns, not verbs.

Good:

GET /users
POST /users
GET /users/1

Bad:

GET /getUsers
POST /createUser

3. Standard HTTP Status Codes

Code	Meaning
200	OK
201	Created
204	No Content
400	Bad Request
404	Not Found
500	Server Error

Example Full API Structure

UserApi/
├── Controllers/
│   └── UserController.cs
├── Models/
│   └── User.cs
├── Program.cs
└── appsettings.json

Testing the API

You can test APIs using tools like:

• curl
• Postman
• Swagger UI (included with ASP.NET)

Example curl request:

curl http://localhost:5000/api/user

Summary

A RESTful API:

• Exposes resources via URLs
• Uses HTTP methods (GET, POST, PUT, DELETE)
• Communicates typically using JSON
• Is stateless
• Returns standard HTTP status codes

In C#, ASP.NET Core Web API makes building REST APIs straightforward using:

• Models
• Controllers
• Routing
• Built-in JSON serialization