API Design 101 - I

What is an API?

What is an API?

API (Application Programming Interface) là tập hợp các quy tắc và giao thức cho phép các ứng dụng, phần mềm giao tiếp với nhau để trao đổi dữ liệu, tính năng và chức năng.

Hãy tưởng tượng bạn vào nhà hàng. Bạn không vào bếp tự nấu — bạn nhìn menu, gọi món, và nhận đồ ăn. Menu chính là API: nó cho bạn biết có thể gọi gì (endpoints), cần thông tin gì (parameters), và sẽ nhận lại gì (response).

API hoạt động tại tầng Application Layer (tầng ứng dụng) là tầng cao nhất, nơi các ứng dụng phần mềm giao tiếp trực tiếp với người dùng hoặc các hệ thống khác trong các mô hình mạng như OSI và TCP/IP.

Types of API Architectures

API trong thực tế được chia thành nhiều loại, với mỗi loại có đặc điểm, kiến trúc và tính phù hợp với các hệ thống khác nhau.

REST/RESTful API (Representational State Transfer)

REST (Representational State Transfer) xem mọi thứ như resources (tài nguyên). user là resource, order là resource, product là resource. Mỗi resource có địa chỉ riêng (URL), và dùng HTTP methods để thao tác, dữ liệu thường là JSON/XML. Client gửi request đến URL cố định (như /users/123), server trả response đầy đủ.

Resource: Users
├── GET    /users        → Lấy danh sách users
├── GET    /users/123    → Lấy user có id 123
├── POST   /users        → Tạo user mới
├── PUT    /users/123    → Cập nhật toàn bộ user 123
├── PATCH  /users/123    → Cập nhật một phần user 123
└── DELETE /users/123    → Xóa user 123

Đối với REST API server không nhớ gì về client giữa các request. Mỗi request phải chứa đủ thông tin để server xử lý. Điều này nghe có vẻ bất tiện, nhưng chính là lý do REST scale tốt — bạn có thể thêm bao nhiêu server cũng được vì không có chia sẻ state.

Tuy nhiên, REST tồn tại những nhược điểm nhất định:

• Over-fetching: Vì mỗi endpoint trả về một cấu trúc dữ liệu cố định (fixed structure) nên sẽ có những trường hợp client nhận về nhiều dữ liệu hơn những gì thực sự cần. Điều này gây dư thừa dữ liệu, lãng phí băng thông.

• Under-fetching: xảy ra khi client không nhận đủ dữ liệu cần thiết trong một request, buộc phải gọi thêm nhiều request khác. Do trong một số trường hợp dữ liệu liên quan nằm ở các endpoint khác nhau.

REST API phù hợp với public API, web/mobile apps cơ bản, hệ thống cần tích hợp nhanh (ví dụ: API của Twitter/X, Amazon S3). Lý tưởng cho hệ thống CRUD (Create, Read, Update, Delete) đơn giản, nơi dữ liệu không quá phức tạp.

Bạn có thể đọc rõ hơn về RestfulAPI tại đây.

SOAP (Simple Object Access Protocol)

SOAP hoạt động dựa trên giao thức messaging nghiêm ngặt, sử dụng XML để đóng gói thông điệp trong cấu trúc “Envelope” (phong bì) gồm Header (thông tin phụ như bảo mật) và Body (nội dung yêu cầu). Client gửi thông điệp SOAP qua HTTP/HTTPS (hoặc các giao thức khác), server xử lý và trả về thông điệp SOAP tương tự với kết quả hoặc lỗi.

<?xml version="1.0"?>
<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope">
  <soap:Header>
    <!-- Security tokens, transaction IDs -->
  </soap:Header>
  <soap:Body>
    <GetUserRequest>
      <UserId>123</UserId>
    </GetUserRequest>
  </soap:Body>
</soap:Envelope>

SOAP có những thứ REST không có tích hợp sẵn:

• WS-Security: Message SOAP (end-to-end security). Dữ liệu được mã hóa, ký số, và xác thực ngay trong message XML, ngay cả khi đi qua nhiều proxy hoặc hệ thống trung gia (không chỉ transport level như HTTPS)

• WS-AtomicTransaction: (dùng cùng WS-Coordination) cung cấp ACID (Atomicity, Consistency, Isolation, Durability) cho giao dịch phân tán qua nhiều service

• WS-ReliableMessaging: Đảm bảo message được gửi đúng một lần (exactly-once), theo thứ tự (in-order), ngay cả khi mạng lỗi, server tạm dừng, hoặc có proxy trung gian.

SOAP tồn tại những nhược điểm như nặng nề (XML dài dòng, tốn bandwidth), phức tạp hơn để triển khai, hiệu suất thấp hơn so với REST/JSON, ít linh hoạt cho web/mobile hiện đại.

SOAP phù hợp với hệ thống enterprise lớn cần bảo mật nghiêm ngặt và giao dịch đáng tin cậy (ví dụ: dịch vụ ngân hàng, tài chính, bảo hiểm hoặc SAP/Oracle integrations). Thường dùng trong môi trường nội bộ doanh nghiệp hoặc legacy systems nơi độ tin cậy quan trọng hơn tốc độ.

GraphQL

Hoạt động dựa trên client gửi một query duy nhất (dạng text mô tả chính xác dữ liệu cần) đến một endpoint cố định (thường là /graphql). Server phân tích query, lấy dữ liệu từ các nguồn và trả về đúng những gì client yêu cầu dưới dạng JSON, tránh over-fetching/under-fetching.

Với những đặc tính trên, GraphQL phù hợp với các hệ thống có nhiều client cần dữ liệu khác nhau cho cùng một tài nguyên (ví dụ: mobile chỉ cần vài field, web cần nhiều field hơn). GraphQL cho phép mỗi client yêu cầu chính xác dữ liệu cần, tránh over-fetching/under-fetching → tiết kiệm băng thông, pin, thời gian tải.

GraphQL cũng phù hợp cho các hệ thống có dữ liệu liên kết nhiều lớp do GraphQL cho phép lấy toàn bộ cây dữ liệu trong một request duy nhất, thay vì nhiều request như REST (giải quyết vấn đề N+1). Lý tưởng cho hệ thống frontend-heavy hoặc microservices với schema thống nhất..

Tuy nhiên không phải lúc nào GraphQL cũng hoàn hảo. Trong thực tế nó cũng tiềm ẩn nhiều vấn đề:

• Khối lượng công việc nặng hơn cho phía server, client có thể gửi query lồng nhau cực sâu, làm sập server.

• Mỗi query là unique, không thể cache ở CDN như REST. Cần dùng client-side caching (Apollo, Relay) hoặc persisted queries

• Cần có các công cụ bảo vệ như depth limiting, timeout cho queries

gRPC (Google Remote Procedure Call)

gRPC là RPC (Remote Procedure Call) framework của Googl. Hoạt động dựa trên HTTP/2 và Protocol Buffers (dữ liệu binary gọn nhẹ), client gọi method như hàm local (RPC). Hỗ trợ 4 kiểu communication: unary, server streaming, client streaming, bidirectional. Server định nghĩa service trong file .proto, tự động generate code cho nhiều ngôn ngữ.

gRPC có nhiều ưu điểm mạnh mẽ như hiệu suất cao (low-latency, ít overhead), hỗ trợ streaming hai chiều, đa ngôn ngữ mạnh mẽ, tự động code generation. Từ đó gRPC rất phù hợp đối với microservices nội bộ, hệ thống hiệu suất cao, real-time streaming, và môi trường cloud-native. Đặc biệt đối với các hệ thống là internal API, service-to-service, high-throughput → gRPC là lựa chọn hàng đầu.

gRPC cũng tồn tại những nhược điểm như ít hỗ trợ browser trực tiếp (cần grpc-web), khó debug (binary), không thân thiện với human-readable như JSON.

Các Loại API Theo Đối Tượng Sử Dụng (Accessibility)

Ngoài việc phân loại theo kiến trúc (REST, GraphQL,...), API còn được chia theo đối tượng được phép sử dụng. Điều này quyết định mức độ mở, bảo mật và cách quản lý API.

Public API (Open API)

API mở cho mọi người sử dụng, thường miễn phí hoặc trả phí theo lượt gọi.

Đăc diểm:

• Dễ tiếp cận API Documentation công khai, chi tiết.

• Rate limiting để tránh lạm dụng.

• API Versioning rõ ràng, có cộng đồng hỗ trợ.

• Thường dùng REST API + JSON

Ví dụ: Các API được cung cấp bởi Google Maps, Stripe, Twilio, OpenAI

Public API tồn tại những đánh đổi cho nhà cung cấp như chi phí documentation và support cao. Mỗi thay đổi cần có chiến lược API version để support những version cũ hơn. Dễ bị lợi dụng, cần có cơ chế rate limit chặt chẽ.

Private API (Internal API)

Private API chỉ dùng nội bộ công ty, không công khai ra ngoài. Thường nằm sau firewall/VPC, không expose ra internet, chỉ các service nội bộ gọi lẫn nhau. Chính vì đó nên có tính bảo mật cao, hiệu suất tốt (không cần kiểm tra public), dễ thay đổi mà không ảnh hưởng bên ngoài.

Private API lý tưởng cho kiến trúc microservices lớn, nơi các service nội bộ giao tiếp (ví dụ: Netflix dùng private API để các module streaming, recommendation nói chuyện với nhau; Amazon dùng internal API cho hệ thống kho hàng).

Partner API

API chia sẻ có chọn lọc với đối tác kinh doanh cụ thể (không mở hoàn toàn như public). Cần ký hợp đồng, cấp API key riêng, thường có SLA (Service Level Agreement) về uptime, support. Chính vì vậy nên quản lý phức tạp hơn (hợp đồng, hỗ trợ riêng), ít linh hoạt. Phù hợp cho mô hình B2B (business-to-business), ví dụ: Ngân hàng chia sẻ API với fintech như Momo/Grab để chuyển tiền; Spotify chia sẻ API với hãng xe hơi để tích hợp nhạc vào ô tô; Salesforce chia sẻ dữ liệu với đối tác CRM.

Ưu điểm của API

• Tích hợp dễ dàng và tái sử dụng code: Cho phép các ứng dụng khác nhau kết nối nhanh chóng mà không cần viết lại từ đầu.

• Mở rộng hệ sinh thái và tạo doanh thu: Public API thu hút developer bên ngoài, tăng người dùng.

• Tăng tốc độ đổi mới và linh hoạt: Dễ cập nhật tính năng riêng lẻ mà không ảnh hưởng toàn hệ thống

Nhược điểm của API

• Vấn đề bảo mật: API có thể là “cửa ngõ” cho hacker nếu không bảo vệ tốt (API attacks như DDoS, injection).

• Phụ thuộc vào bên thứ ba: Nếu API external downtime hoặc thay đổi, app của bạn có thể “chết”.

• Hiệu suất và độ phức tạp: Quá nhiều gọi API có thể gây chậm (latency), hoặc over-fetching dữ liệu thừa.

Ngày nay API quá phổ biết trong ngành phần mềm. Trong bài viết này chúng ta đã cùng nhau tìm hiểu được trọn vẹn API là gì, API phân loại như thế nào. Trong bài sau hãy cùng tôi tìm hiểu API hoạt động như thế nào.