vault/Career/API/Restful API.md

---
note type:
  - api
  - note
date: 2026-06-03
done: true
---
# 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:

``` json
{
  "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:

``` bash
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

``` csharp
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

``` csharp
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:

``` json
[
  { "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.

``` csharp
[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.

``` csharp
[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:

``` json
POST /api/user

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

# Updating a Resource (PUT)

``` csharp
[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

``` csharp
[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:

``` bash
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