API vs REST: The Ultimate Guide
The Restaurant Traffic Controller
Imagine a busy restaurant.
The Waiter (The API) is the person who takes your order and brings you food. The waiter is the bridge between you and the kitchen. The waiter can work without any rules—just running around doing whatever they want. But that would be chaos!
The Traffic Controller (REST) is the manager who sets the strict rules. The manager says: "Waiter, you must always use a tray. You must always walk on the right side of the hallway. You must use table numbers, never customer names."
So, API is the waiter doing the work. REST is the manager's rulebook that makes the waiter's work organized, predictable, and safe for everyone.
Where does REST actually work inside the API?
REST doesn't "work on" the API like a magical tool. REST is the Design Pattern (The Architecture). It dictates exactly how your C# code should look, how your URLs should be named, and how data should be formatted.
Example 1: A Normal API (NOT RESTful)
In older times, developers built APIs without rules. They put the action (verb) inside the URL. This is called RPC (Remote Procedure Call).
// URLs containing actions (Verbs)
// URL: /getAllBooks
// URL: /getBookById?id=5
// URL: /deleteBook?id=5
[ApiController]
public class BookController : ControllerBase
{
// Using POST to get data? Messy!
[HttpPost("getBookById")]
public IActionResult GetBook(int id)
{
return Ok("Here is your book");
}
}// URLs containing NOUNS only (Things)
// URL: GET /books
// URL: GET /books/5
// URL: DELETE /books/5
[ApiController]
[Route("api/[controller]")] // Noun: "books"
public class BooksController : ControllerBase
{
[HttpGet]
public IActionResult GetAllBooks() {
return Ok("All books");
}
[HttpGet("{id}")]
public IActionResult GetBook(int id) {
return Ok($"Book {id}");
}
}The Big Secret
In a REST API, the URL /api/books never changes. If you want to read a book, you use the GET method on that URL. If you want to delete it, you use the DELETE method on the exact same URL. REST uses the standard HTTP methods to tell the API what to do.
The Journey: How REST Rules Your API
Let's follow a request step-by-step to see exactly how REST works inside an ASP.NET Core API:
Step 1: The Client (Browser/App)
The user clicks a button. The browser sends a request: GET https://api.myapp.com/api/books/5
Step 2: REST Routing (The Rulebook)
ASP.NET Core reads the URL. REST rules say: "The noun is books, the ID is 5, and the verb is GET." It looks for a Controller named BooksController and a method with [HttpGet("{id}")].
Step 3: The C# Code Executes
Your C# method runs: public IActionResult GetBook(int id). It fetches the data from the database.
Step 4: REST Serialization
You return a C# object (e.g., return Ok(myBookObject);). REST rules say: "Convert this C# object into JSON text before sending it back!"
Summary: The Core Differences
| Feature | API (Application Programming Interface) | REST (Representational State Transfer) |
|---|---|---|
| Core Concept | The general concept of two programs talking (The Waiter). | A specific set of rules for building the API (The Manager). |
| Standardization | No standard. You can make up your own rules. | Strict standards. Follows web standards (HTTP). |
| URL Structure | Can be anything (e.g., /getData, /runProcess). |
Must be Nouns (e.g., /users, /products). |
| Actions (Verbs) | Hidden inside the URL (e.g., /deleteUser). |
Defined by HTTP Methods (DELETE /users). |
| Data Format | Can be anything (XML, HTML, Text). | Almost strictly JSON. |
Mini-Project: Build a RESTful Books API
Let's prove you understand REST by building a real API in Visual Studio right now! No database needed.
Create the Project
Open Visual Studio and create a new project.
BooksRestApi. Click Next, keep the default settings (Framework: .NET 8.0), and click Create.
Create the Book Model
We need a C# class to represent our data.
Book.cs. Paste this inside:
namespace BooksRestApi
{
public class Book
{
public int Id { get; set; }
public string Title { get; set; } = string.Empty;
public string Author { get; set; } = string.Empty;
}
}Create the RESTful Controller
This is where the magic happens. Notice how we use Nouns in the route and standard HTTP verbs for the actions.
BooksController.cs. Replace all the code with this:
using Microsoft.AspNetCore.Mvc;
namespace BooksRestApi.Controllers
{
[Route("api/[controller]")] // REST RULE: Noun in URL ("books")
[ApiController]
public class BooksController : ControllerBase
{
// Our temporary database
private static List<Book> _books = new List<Book>
{
new Book { Id = 1, Title = "Clean Code", Author = "Robert Martin" },
new Book { Id = 2, Title = "The Pragmatic Programmer", Author = "Andrew Hunt" }
};
// GET: api/books
[HttpGet]
public IActionResult GetBooks()
{
return Ok(_books);
}
// GET: api/books/1
[HttpGet("{id}")]
public IActionResult GetBook(int id)
{
var book = _books.FirstOrDefault(b => b.Id == id);
if (book == null) return NotFound("Book not found.");
return Ok(book);
}
// POST: api/books
[HttpPost]
public IActionResult CreateBook(Book newBook)
{
newBook.Id = _books.Count + 1;
_books.Add(newBook);
return CreatedAtAction(nameof(GetBook), new { id = newBook.Id }, newBook);
}
// DELETE: api/books/1
[HttpDelete("{id}")]
public IActionResult DeleteBook(int id)
{
var book = _books.FirstOrDefault(b => b.Id == id);
if (book == null) return NotFound("Book not found.");
_books.Remove(book);
return NoContent(); // 204 Success
}
}
}Run and Test It!
Press F5 in Visual Studio. A browser window will open with Swagger UI.
- Expand GET /api/books → Click Try it out → Execute. You will see the JSON list of books!
- Try adding a new book using POST /api/books. Notice how the URL is still
/api/books—the POST method tells the API to create, not read!