Giải ngố API – Phần 2: Web APIs hoạt động ra sao?

Tiếp theo nội dung Giải ngố API – Phần 1: Web Application Basics kiểu “tàu nhanh” (hiệp 2), kỳ này tôi sẽ đi vào chi tiết các vấn đề sau của Web API bao gồm:

  • Phương thức hoạt động của Web APIs thông qua quá trình tương tác của API consumerAPI provider;
  • Các thể loại Web API phổ biến bao gồm RESTful APIsGraphQL;

#1. Quá trình giao lưu phối hợp của API consumer và API provider

Tôi sẽ sử dụng lại với cái kiến trúc API Gateway service đề cập trong kỳ trước để minh họa cho tiện.

API Gateway service
API Gateway service

Nguồn: The API gateway pattern versus the direct client-to-microservice communication | Microsoft Learn

Lúc này, quá trình API consumer – tức là các ông client như Client mobile app hay Tranditional Web App (sau đây tôi chỉ gọi tắt là API consumer cho nhanh) chạy request đến API endpoints (ví dụ như https://dummytip.com/api/v1/users/) để yêu cầu thông tin và API provider – tức là ông server (sau đây tôi chỉ gọi tắt là API provider cho nhanh) phản hồi thông tin/cung cấp dữ liệu cho request đến API endpoint tương ứng sẽ diễn ra như sau:

  • API consumer gửi request đến yêu cầu API provider cung cấp thông tin/tài nguyên tương ứng;
  • Request chạy qua API Gateway;
  • API gateway thanh lọc đám request vớ vẩn và dẫn đường cho đám request chuẩn đến service/microservice phù hợp (API gateway có thể kiêm nhiệm phụ trách luôn các vấn đề về security controls như authentication, authorization, encryption in transit using SSL, rate limiting and load balacing).

Lưu ý: Microservice architecture là kiểu phân tách cái web app ra thành nhiều module. Mỗi module xử lý một chức năng cụ thể. Đối lập với Microservice architecture là kiểu Monolithic architecture, khi đó toàn bộ services đều nằm gọn trong cái application.

API consumer sẽ không nắm thông tin về backend design – thiết kế cụ thể của phía API provider (mà cũng không cần biết làm chi cho mệt người). Thứ API consumer cần là API endpoints để có thể tương tác với API provider và hốt về cái tài nguyên cần thiết. Thông thường, thông tin này sẽ được thể hiện trong API documentation với các chi tiết bao gồm:

  • Cách thức sử dụng API và phương thức mà API sẽ phản hồi;
  • Mô tả các yêu cầu xác thực (nếu có);
  • Thông tin về các mức độ phân quyền cho users;
  • Các API endpoints để API consumer có thể tương tác.
  • Các parameters cần thiết phải có cho các request gửi đến API endpoints.

Về cơ bản, việc tương tác với API cũng sẽ bao gồm các hành động CRUD (Create – tạo, Read – Đọc, Update – Cập nhật và Delete – Xóa) và các phương thức tương ứng như sau (tất nhiên với yêu cầu phân quyền tương ứng):

  • Create: Sử dụng phương thức POST;
  • Read: Sử dụng phương thức GET;
  • Update: Sử dụng phương thức POST hoặc PUT;
  • Delete: Sử dụng phương thức POST hoặc DELETE.

#2. Các thể loại Web API phổ biến

Hai dạng Web API phổ biến tôi giới thiệu trong nội dung kỳ này là RESTful APIGraphQL API. Ngoài 2 ông này, bạn còn có thể gặp các nhân vật có thâm niên cao hơn ví dụ như Simple Object Access Protocol – SOAP (bạn có thể tự tra cứu thêm thông tin về các đối tượng này nếu cần).

#2.1 Tượng đài RESTful API

#2.1.1 RESTful contrains – Các ràng buộc của kiểu RESTful API

Trước hết REST là viết tắt của Representational State Transfer, một dạng kiến trúc để thiết kế application.Và tôi thấy có thể tạm hiểu rằng:

  • Representation hàm ý các tài nguyên hệ thống có thể được thể hiện ở các định dạng khác nhau như JSON hay XML tùy thuộc yêu cầu cụ thể;
  • State hàm ý tình trạng hiện hành của tài nguyên hệ thống;
  • Transfer hàm ý việc truyền tải tài nguyên hệ thống (ở các dạng thức thể hiện khác nhau) giữa client và server.

Với REST, HTTP protocol (được client/server sử dụng để tương tác với nhau) và URL format cũng sẽ tuân thủ theo REST architectual stype (REST-type URL sẽ chứa parameters ngay trong URL file path, chứ không đặt trong query string).

Tóm lại, RESTset of architectural constraints (tức là kiểu một bộ các quy tắc ràng buộc về mặt kiến trúc thiết kế) mà theo đó ứng dụng sẽ giao tiếp với nhau thông qua việc sử dụng HTTP methods. Và như vậy, các APIs sử dụng REST constrainst sẽ được gọi là RESTful hay chỉ đơn giản là REST APIs.

Cụ thể về set of architectural constraints, RESTful design sẽ có các ràng buộc cơ bản như sau:

  1. Uniform interface: Tất cả các thiết bị có thể truy cập server theo cùng một cách thức;
  2. Client/server: Client là API consumer sẽ gửi yêu cầu lấy thông tin và server là API provider sẽ cung cấp thông tin được yêu cầu;
  3. Stateless: API consumer sẽ cần cung cấp các thông tin cần thiết (ví dụ các token) trong mỗi request để API provider kiểm tra xử lý tương ứng vì phía server sẽ không quản lý session theo kiểu stateful;
  4. Cacheable: Các dữ liệu được phía client thường xuyên yêu cầu sẽ được lưu trữ trên cache server (sẽ có response header tương ứng thể hiện thời điểm đám thông tin liên quan hết hạn được lưu cache). Theo đó, với mỗi request yêu cầu thông tin, quá trình xử lý đại khái sẽ như sau:
    • Client kiểm tra local storage phía client xem có thông tin yêu cầu hay không;
    • Nếu không có thông tin tương ứng, request sẽ được chuyển tới cache server để kiểm tra xem thông tin được yêu cầu có trong local storage phía server phụ cách lưu cache hay không;
    • Nếu vẫn không có dữ liệu, request sẽ được đẩy đến các server khác ví dụ như DB server để trích xuất thông tin cần thiết.
  5. Layered system: API client có thể yêu cầu dữ từ từ một endpoint mà không cần biết server architecture (tức là kiến trúc phía server);
  6. Code on demand (tùy chọn): Cho phép gửi code đến phía client để thực thi.

#2.1.2 Các REST APIs headers phổ biến

Các REST APIs headers phổ biến bao gồm:

  • Authorization: Ông này được dùng để chuyển token/credentials cho API provider the định dạng Authorization: <type> <token/credentials> (Ví dụ kiểu Authorization: Bearer Abcxyztoken. Các Authorization header types phổ biến bao gồm:
    • Basic: Base64-encoded credential;
    • Bearer: API token;
    • AWS-HMAC-SHA256: AWS authorization type sử dụng access key và secret key.

Lưu ý: Đây là nội dung quan trọng, tôi sẽ quay trở lại bàn kỹ hơn về đối tượng này sau.

  • Content-Type: Ông này được dùng để thông báo media type đang được sử dụng để truyền tải thông tin. Cần lưu ý rằng Content-Type headers là kiểu “chuyện đã xảy ra rồi, tôi chỉ muốn báo cho các ông biết thôi, còn việc các ông có thích hay không thì …kệ các ông!” nên sẽ khác với Accept headers vốn được dùng để thông báo media type mà chủ xị đang mong muốn nhận được. Các Content-Type headers phổ biến bao gồm:
    • application/json: JavaScript Object Notation – JSONmedia type phổ biến nhất của REST APIs;
    • application/xml: Dạng này có thể sử dụng với REST API tuy nhiên đây là dạng sử dụng chủ yếu với SOAP API tôi đã đề cập ở trên;
    • application/x-www-form-urlencoded: Với dạng này, thông tin gửi đi sẽ được encoded (chuyển đổi). Trong đó, key – value pair được tách biệt bằng ký tự ampersand&” và equal=“.
  • Midddleware (X) Headers: X-<anything> header có thể được dùng để phục vụ nhiều mục đích ví dụ như:
    • X-Response-Time: Được dùng để cho biết mất bao lâu để xử lý một response;
    • X-API-Key: Có thể được dùng như authorizatoin header cho API keys;
    • X-Powered-By: Được dùng để cung cấp thông tin bổ sung về backend services;
    • X-Rate-Limit: Được dùng để cho phía client biết còn được gửi bao nhiêu request trước khi vi phạm rate-limit enforcement và bị xử lý (ví dụ như bị banned/blocked).

#2.1.3 REST API Specification

Trước hết, specifications là các kiểu các “thông số kỹ thuật” của một sản phẩm cụ thể (trong trường hợp này là REST API). Và theo đó, OpenAPI Specification 3.0 – OAS (hay còn được gọi là Swagger) là một dạng specifications chính của RESTful APIs có thể được sử dụng để tạo API documentation với định dạng JSON hoặc YAML.

OpenAPI Specification 3.0 - OAS
OpenAPI Specification 3.0 – OAS

Nguồn: OpenAPI Specification – Version 3.0.3 | Swagger

Ngoài ra, tôi cũng có thể sử dụng một phương án khác để tạo API documentationRESTful API Modeling Language – RAML (chủ yếu sử dụng định dạng YAML).

RESTful API Modeling Language - RAML
RESTful API Modeling Language – RAML

Nguồn: raml-org/raml-spec: RAML Specification (github.com)

#2.2 Và ngôi sao đang lên – GraphQL

Đối tượng thứ 2 được đề cập trong phần này là GraphQL – nhân vật được thiên hạ cho rằng sẽ thay thế REST API sự thống trị của trong tương lai gần.

GraphQL
GraphQL

Nguồn: GraphQL | A query language for your API

Graph Query Language – GraphQL là loại API đặc biệt cho phép client có thể định nghĩa cấu trúc của dữ liệu mà client muốn server gửi về.

Về cơ bản, GraphQL cũng là RESTful (tức là tuân thủ 6 constrains – ràng buộc của REST API trình bày ở trên) nhưng được thiết kế với định hướng thiên về kiểu query (truy vấn) – nghĩa là đối tượng này được cấu trúc để hoạt động theo kiểu DB query language ví dụ như SQL. Cụ thể:

  • GraphQL sử dụng schemas – collections of data (đại khái là bộ dữ liệu);
  • GraphQL lưu trữ tài nguyên vào graph data structures (cấu trúc dữ liệu dạng graph).

GraphQL cải tiến hơn so với REST APIs trong các vấn đề:

  • Có thể chỉ cần sử dụng 1 request để lấy đúng chính xác các dữ liệu cần thiết vốn có thể phải chạy bằng nhiều REST API request;
  • Có thể sử dụng HTTP nhưng chỉ cần một entry point URL với POST method;
  • Có thể sử dụng CRUD với POST request dựa vào 3 operationquery, mutationsubscription.

Câu chuyện về GraphQL rất thú vị (và dài) nên tôi xin phép quay trở lại giới thiệu trong một series riêng sau. Trong các kỳ tiếp theo, tôi sẽ tập trung bàn tiếp về các vấn đề khác của đám API nói chung cho xong.

1 thought on “Giải ngố API – Phần 2: Web APIs hoạt động ra sao?”

Leave a Reply

Your email address will not be published. Required fields are marked *