API Theory

Duy Văn | 07/02/2025

Giới thiệu

API - Application Programming Interface - hay còn gọi là giao diện lập trình ứng dụng, là tập hợp các quy tắc và cơ chế để các thành phần của một ứng dụng hay hệ thống có thể tương tác và trao đổi dữ liệu.

Cách hoạt động của API

API hoạt động bằng cách chia sẻ dữ liệu giữa các ứng dụng, hệ thống và thiết bị. Nó hoạt động thông qua vòng lặp gửi yêu cầu và trả phản hồi. Yêu cầu - request được gửi đến API, API xử lý yêu cầu, thu nhặt data và trả về người dùng thông qua phản hồi - response

API client

API client là một ứng dụng hoặc dịch vụ nhằm mục đích khởi đầu cho việc giao tiếp với API, nó bắt đầu với việc gửi request tới cho API Server.

Việc gửi request có thể được thực hiện bằng nhiều cách, ví dụ như ấn một nút. Với ứng dụng web, việc lập trình các nút ấn để trigger một request là cách phổ biến

Ví dụ với một trang web e-commerce khi người dùng ấn nút “Thêm vào giỏ hàng”, trang web sẽ gửi request tới server để thêm sản phẩm vào giỏ hàng của cá nhân đang đăng nhập, và vì nó đã được thêm vào ở database, người dùng khi di chuyển giữa các thiết bị khác nhau vẫn có thể thấy sản phẩm đó trong giỏ hàng.

API Request

Tuỳ thuộc vào loại API mà một API có thể nhìn và vận hành khác, nhưng cơ bản là có các thành phần sau:

  • Endpoint: Đây là URL mà gửi request tới, nó cung cấp khả năng truy cập cụ thể vào một tài nguyên nào đó. Ví dụ nút “Thêm vào giỏ hàng” có thể gửi request tới https://api.example.com/cart/add và nó cung cấp truy cập vào tài nguyên giỏ hàng của mỗi người dùng
  • Method: Đây là phương thức mà request sẽ được gửi đi, phổ biến nhất là GET, POST, PUT, DELETE - Đây là các HTTP methods, cho phép API client thực hiện các thao tác tạo, đọc, ghi, xoá (CRUD - Create, Read, Update, Delete) lên tài nguyên của một API
    • GET: Lấy dữ liệu từ server. API Client có thể dùng GET để truy cập vào tất cả tài nguyên theo loại hoặc cụ thể một tài nguyên. Ví dụ, GET lên endpoint /fares của Vietnam Airline sẽ trả về danh sách các hạng giá vé cùng một vài thông tin cơ bản, còn /fares/economy sẽ trả về thông tin chi tiết về hạng vé Economy. Thông thường, GET sẽ không có request body vì nó chỉ lấy dữ liệu từ server, tuy nhiên thật ra cũng có thể có tuỳ theo cách cấu trúc API, ví dụ như cấu trúc API ở bên trên có thể cấu trúc lại, thay vì cụ thể đi vào endpoint /fares/economy thì có thể gửi request GET với query parameter {"type" : "economy",} nằm trong request body
    • POST - Dùng để tạo tài nguyên mới. Ví dụ, POST trên endpoint /cart/add của trang web e-commerce sẽ thêm một sản phẩm vào giỏ hàng của người dùng. Và vì chúng ta đang tạo tài nguyên nên sẽ luôn cần cung cấp cho request một body chứa các thông tin cần thiết để tạo tài nguyên mới. Ví dụ
      {
      "product_id": "123",
      "quantity": 1,
      "shipping_adress": "123 ABC Street"
  }
    • PUT - Dùng để thay thế tài nguyên đang có với tài nguyên mới. Ví dụ, PUT lên endpoint /cart/update của trang web e-commerce sẽ cập nhật số lượng sản phẩm trong giỏ hàng của người dùng khi người dùng ấn dấu + để tăng số lượng đơn vị hàng mua và đổi địa chỉ. Ví dụ
      {
      "product_id": "123",
      "quantity": 2,
      "shipping_adress": "125 ABC Street"
  }
    • PATCH - mở rộng của PUT, dùng để cập nhật một phần của tài nguyên. Ví dụ, PATCH lên endpoint /cart/update của trang web e-commerce sẽ chỉ cập nhật số lượng sản phẩm trong giỏ hàng của người dùng khi người dùng ấn dấu + để tăng số lượng đơn vị hàng mua. Ví dụ
      {
      "quantity": 2
  }
    • DELETE - Dùng để xoá tài nguyên. Ví dụ, DELETE lên endpoint /cart/delete của trang web e-commerce sẽ xoá sản phẩm khỏi giỏ hàng của người dùng. Vì DELETE mang tính chất xoá bỏ dữ liệu nên request DELETE thường cần được gia cố các tầng bảo mật nằm trong header, tuy nhiên nếu trên góc độ một website e-commerce thì đây là điều hiển nhiên có ở mọi method. Ví dụ chúng ta khi ấn dấu - ở giỏ hàng, nó sẽ không trừ số lượng về 0 mà đơn giản là loại bỏ món hàng ra khỏi giỏ
      {
      "product_id": "123"
  }
  • Parameters - Đây là các thông số cần thiết để thực hiện request, nó có thể là query parameter, path parameter, header, body, cookie, … Ví dụ, khi gửi request POST lên endpoint /cart/add của trang web e-commerce, cần cung cấp các thông số như product_id, quantity, shipping_adress để thêm sản phẩm vào giỏ hàng của người dùng
  • Headers - Đây về cơ bản cũng là một dạng của parameters, nhưng thường mang tính chất bảo mật hơn, nó chứa các thông tin như Authorization, Content-Type, Token, Access Key, … Ví dụ, khi gửi request POST lên endpoint /cart/add của trang web e-commerce, cần cung cấp header Authorization hoặc Access Key đi kèm để xác minh là người dùng đang gửi request là đúng và có quyền
  • Body - Đây là nơi chứa dữ liệu cần thiết để thực hiện request, nó thường là JSON, chứa data cụ thể để phục vụ cho việc tạo, đọc, ghi, xoá tài nguyên.

API Server

API Server là nơi chứa tài nguyên và cả cơ chế xử lý request từ API Client. Nó nhận request từ API Client, xử lý request, truy cập vào database, thực hiện các thao tác cần thiết và trả về response cho API Client.

API Response

API Response là phản hồi từ API Server sau khi xử lý request từ API Client. Nó chứa thông tin cần thiết để API Client hiểu được kết quả của request, thông thường nó sẽ chứa các thông tin như:

  • Status code: HTTP sttus code theo tiêu chuẩn có 3 chữ số, thể hiện kết quả của một API Request. Nó tuỳ thuộc hoàn toàn vào cách API được tạo ra, thông thường sẽ có code 200 - OK, 201 - Created, 204 - No Content, 400 - Bad Request, 401 - Unauthorized, 403 - Forbidden, 404 - Not Found, 500 - Internal Server Error, …
  • Headers: Chứa các thông tin bổ sung như Content-Type, Content-Length, Date, Server, … để API Client hiểu được thông tin về response
  • Body: Chứa dữ liệu trả về từ API Server, thông thường là JSON, XML, HTML, … hoặc chứa thông báo lỗi nếu có

Các loại API

Có nhiều cách để phân loại API, nhìn từ góc độ phân quyền truy cập thì có 3 loại API phổ biến:

  • Public API: Là API mà bất kỳ ai cũng có thể truy cập và sử dụng, không cần phải xác thực. Ví dụ như API của Facebook, Twitter, Google, …
  • Private API: Là API mà chỉ một số người được phép truy cập và sử dụng, cần phải xác thực. Ví dụ như API của một số công ty, tổ chức, …
  • Partner API: Là API mà chỉ một số đối tác được phép truy cập và sử dụng, cần phải xác thực. Ví dụ như API của một số dịch vụ, ứng dụng, … Khi hợp tác và kết nối với nhau

Một số cấu trúc API phổ biến:

  • REST API: Là một kiến trúc API dựa trên HTTP, nó sử dụng các phương thức HTTP như GET, POST, PUT, DELETE để thực hiện các thao tác tạo, đọc, ghi, xoá tài nguyên. REST API thường sử dụng JSON để truyền dữ liệu giữa API Client và API Server
  • SOAP - Simple Object Access Protocol: Là một giao thức truyền tải dữ liệu giữa các ứng dụng, nó sử dụng XML để truyền dữ liệu giữa API Client và API Server
  • GraphQL: Là một ngôn ngữ truy vấn dữ liệu, nó cho phép API Client truy vấn dữ liệu cụ thể mà nó cần, không cần phải truy cập vào tất cả tài nguyên như REST API. GraphQL thường sử dụng JSON để truyền dữ liệu giữa API Client và API Server
  • Webhooks - Là một cơ chế mà API Server có thể gửi thông báo tới API Client khi có sự kiện xảy ra, không cần phải API Client gửi request tới API Server. Ví dụ, khi có người dùng đăng ký tài khoản, API Server sẽ gửi thông báo tới API Client để thông báo rằng có người dùng mới đăng ký. Webhook thường được sử dụng như cơ chế feedback loop giữa API Client và API Server.