REST API

What is a REST API?

A REST API (Representational State Transfer Application Programming Interface) is an architectural style for designing networked applications. It enables communication between software systems over the internet using standard HTTP methods like GET, POST, PUT, PATCH, and DELETE.

---

What Does a REST API Include?

1. Resources

• Definition: Resources are the entities APIs work with, such as books, users, or orders.

• Identification: Each resource is accessed via a URL (Uniform Resource Locator).

  • Example: /books/{id} to retrieve a specific book.

2. HTTP Methods

REST APIs rely on HTTP methods to define actions on resources.

Method	Purpose	Example Use Case
GET	Retrieve data from the server.	Fetch a list of books or a book’s details.
POST	Create a new resource.	Add a new book to the database.
PUT	Update an entire resource or create it if it doesn’t exist.	Replace all details of a book.
PATCH	Update part of an existing resource.	Update only a book's price.
DELETE	Remove a resource from the server.	Delete a specific book.

3. Stateless Communication

• Every client request must contain all the information the server needs to process it.

• The server does not store any session or state about the client.

4. Client-Server Architecture

• Client: Handles the user interface and makes API calls.

• Server: Handles the business logic, data storage, and responses.

5. Representation of Resources

• Resources are usually represented in JSON or XML.

• JSON is preferred due to its simplicity and compatibility with JavaScript.

6. HATEOAS (Hypermedia as the Engine of Application State)

• REST APIs may provide links in responses to guide the client on available actions.

---

What Are REST APIs Used For?

REST APIs are versatile and widely used for:

1. Web Services: Communication between web applications.

2. Mobile Apps: Backend data interaction for mobile apps.

3. Microservices: Coordination among different services in distributed systems.

4. IoT Devices: Interaction between devices and servers.

---

Best Practices for REST APIs

1. Meaningful Resource Names: Use nouns (e.g., /users, /orders). Avoid verbs in endpoints.

2. Versioning: Include version numbers in URLs (e.g., /v1/orders) to handle changes without breaking older clients.

3. HTTP Status Codes: Use appropriate codes:

   • 200 OK: Successful request.

   • 404 Not Found: Resource doesn’t exist.

   • 500 Internal Server Error: Server-side failure.

4. Pagination and Filtering: For large datasets, implement pagination (/books?page=1&limit=10) or filtering (/books?genre=fiction).

5. Security: Use authentication (OAuth, API keys) and HTTPS.

6. Documentation: Provide clear details with examples, formats, and endpoint usage.

---

Explaining REST API Using a Restaurant Analogy

Imagine a restaurant scenario to illustrate REST concepts:

Role	API Concept
Customer	Represents the client (e.g., a mobile/web app).
Waiter	Acts as the API, facilitating communication.
Chef	Represents the server (e.g., database, backend logic).

Scenario Walkthrough

1. Retrieve a Menu (GET)

   • Customer: "Can I see the menu?"

   • API: Sends the request to the server.

   • Server: Returns the menu data.

   • API: Delivers the menu to the customer.

2. Place an Order (POST)

   • Customer: "I’d like to order a pizza."

   • API: Sends the order details to the server.

   • Server: Processes and confirms the order.

3. Update an Order Fully (PUT)

   • Customer: "Replace my pizza with pasta."

   • API: Sends the update request.

   • Server: Replaces the pizza order with pasta.

4. Modify an Order Partially (PATCH)

   • Customer: "Add extra cheese to my pizza."

   • API: Sends a partial update request.

   • Server: Adds cheese to the existing pizza.

5. Cancel an Order (DELETE)

   • Customer: "Cancel my dessert order."

   • API: Sends a cancellation request.

   • Server: Removes the dessert order.

---

Code Examples in C#

1. GET Request: Fetch Menu

HttpClient client = new HttpClient();
var response = await client.GetAsync("https://restaurant-api.com/menu");
var menu = await response.Content.ReadAsStringAsync();
Console.WriteLine("Menu: " + menu);

2. POST Request: Place an Order

var order = new { Item = "Pizza", Quantity = 1 };
var content = new StringContent(JsonSerializer.Serialize(order), Encoding.UTF8, "application/json");

var response = await client.PostAsync("https://restaurant-api.com/orders", content);
Console.WriteLine("Order Response: " + response.StatusCode);

3. PUT Request: Replace an Order

var updatedOrder = new { Item = "Pasta", Quantity = 1 };
var updateContent = new StringContent(JsonSerializer.Serialize(updatedOrder), Encoding.UTF8, "application/json");

var response = await client.PutAsync("https://restaurant-api.com/orders/1", updateContent);
Console.WriteLine("Update Response: " + response.StatusCode);

4. PATCH Request: Modify an Order Partially

var patchData = new { AddOn = "Extra Cheese" };
var patchContent = new StringContent(JsonSerializer.Serialize(patchData), Encoding.UTF8, "application/json");

var response = await client.PatchAsync("https://restaurant-api.com/orders/1", patchContent);
Console.WriteLine("Patch Response: " + response.StatusCode);

5. DELETE Request: Cancel an Order

var response = await client.DeleteAsync("https://restaurant-api.com/orders/2");
Console.WriteLine("Cancel Response: " + response.StatusCode);

---

Summary

In REST APIs:

• Client (Customer) interacts with Server (Chef) through an API (Waiter).

• HTTP methods define actions:

  • GET: Fetch data.

  • POST: Create data.

  • PUT: Replace data.

  • PATCH: Partially update data.

  • DELETE: Remove data.

This architecture ensures scalability, stateless communication, and clarity while supporting modern application development.