# Hợp đồng API sống lâu hơn demo, nên đọc API Design Patterns theo thứ tự này

> Bắt đầu từ resource chứ không phải endpoint, rồi dồn sức vào ba chỗ tích hợp của khách hay vỡ nhất: tác vụ chạy lâu, retry và versioning.

Bản gốc: https://fdetimes.net/vi/sach-khoa-hoc/sach-api-design-patterns-jj-geewax/

Khi một FDE rời khỏi khách hàng, thứ ở lại lâu nhất thường không phải demo hay slide. Đó là hợp đồng API: tên các resource, cách gọi, cách báo lỗi. Đội của khách sẽ còn viết code dựa vào những thứ đó trong nhiều năm.

Vì thế một cuốn sách ra từ 2021 vẫn đáng nằm trên bàn bạn. *API Design Patterns* của JJ Geewax do Manning phát hành năm 2021. Nhà xuất bản mô tả sách là một bộ nguyên tắc thiết kế cho cả API nội bộ và API công khai.

Manning nói sách viết cho lập trình viên xây API web và API nội bộ, bằng bất kỳ ngôn ngữ nào. FDE vừa phải nối hệ thống của mình vào hệ thống của khách, vừa phải thiết kế endpoint cho họ, nên đó gần như là mô tả công việc của bạn. Câu hỏi thực tế là nên đọc phần nào trước buổi họp tích hợp đầu tiên.

## Bắt đầu từ resource, không phải từ endpoint

Chương 1, "Introduction to APIs", định nghĩa API là cách các hệ thống máy tính tương tác với nhau. Chương này đi vào những điều cơ bản và lý do chúng quan trọng: interface, cách tổ chức API quanh resource, và điều gì làm nên một API tốt.

Nghe có vẻ sơ đẳng, nhưng đây là tầng quyết định hợp đồng. Thử hình dung API nội bộ của khách có `getOrder`, `fetch_customer` và `LoadInvoiceData` cùng tồn tại.

API ấy vẫn chạy, nhưng người gọi không đoán được endpoint tiếp theo sẽ tên gì. Nghĩ theo resource trước (đơn hàng, khách hàng, hóa đơn) giúp bạn chỉ ra vấn đề mà không biến cuộc trao đổi thành chuyện khẩu vị.

Bản tóm tắt sách trên System Design Space mở đầu bằng một nhóm ý họ gọi là "API như sản phẩm và hợp đồng". Đó là cách nhóm của người tóm tắt, không phải mục lục của Manning, nhưng nó gói đúng tinh thần: sai ở tầng resource thì mọi pattern phía sau đều phải vá.

## Tác vụ chạy lâu là chỗ tích hợp vỡ đầu tiên

Bài review của Nicolas Fränkel trên DEV Community xác nhận sách có một pattern cho những phương thức không trả kết quả tức thì. Bản tóm tắt của System Design Space mô tả pattern này là tách việc khởi động tác vụ khỏi việc lấy kết quả, với ngữ nghĩa trạng thái rõ ràng.

Thử hình dung bạn deploy một pipeline xử lý tài liệu cho một công ty bảo hiểm. Mỗi lô mất vài phút, trong khi gateway của khách cắt kết nối sau 30 giây. Nếu endpoint đợi xử lý xong mới trả lời, khách sẽ thấy lỗi dù việc vẫn đang chạy.

Cách làm theo pattern là trả về ngay một operation có trạng thái để khách hỏi lại theo chu kỳ. Khách không còn nhận một lỗi khó hiểu, mà nhận một thứ có thể theo dõi được.

## Retry và versioning nên được hỏi ngay từ đầu

Fränkel cũng xác nhận một chương tên "Request retrial", về các thuật toán để retry request an toàn. Bản tóm tắt khuyên dùng request identifier và idempotency key cho những lệnh ghi quan trọng, kèm một định dạng lỗi có cấu trúc dùng chung.

Lấy một ví dụ giả định: ERP của khách gửi 1.000 lệnh tạo đơn hàng. 20 lệnh bị timeout trên đường mạng dù server đã ghi xong, và ERP gửi lại cả 20.

Không có idempotency, khách có 1.020 đơn, trong đó 20 đơn trùng, và người phát hiện ra là phòng kế toán chứ không phải bạn. Có idempotency key, lần gọi thứ hai chỉ nhận lại kết quả của lần đầu.

Chủ đề cuối là chương "Versioning and compatibility", định nghĩa thế nào là tương thích và các chiến lược versioning. Bản tóm tắt nêu thay đổi tương thích ngược là chiến lược mặc định. Thêm một trường tùy chọn thì client cũ vẫn chạy; đổi một trường thành bắt buộc thì mọi script đội khách đã viết có thể gãy cùng lúc.

**Điểm mấu chốt:** Hợp đồng API bạn để lại ở khách sẽ sống lâu hơn cả engagement của bạn.

## Thứ tự đọc cho người đang có dự án

Nếu tuần sau bạn có buổi tích hợp, hãy đọc chương 1 trước, rồi đến tác vụ chạy lâu, retry an toàn và cuối cùng là versioning. Tên chương ở trên lấy từ một bài review và một bản tóm tắt, nên hãy tra mục lục cuốn sách bạn đang cầm để tìm đúng phần tương ứng. Phần còn lại để dành cho lúc rảnh hơn.

Fränkel giới thiệu sách cho mọi lập trình viên mới bắt đầu làm việc với API, nhưng cũng nhận xét nó chưa tốt khi dùng làm sách tra cứu. Với FDE, điều đó có nghĩa là đừng chờ đến lúc gặp sự cố mới mở sách tìm câu trả lời. Đọc trước các phần trên, rồi tự ghi lại một danh sách câu hỏi để mang theo đến khách.

## Hai cách đọc dễ làm phí cuốn sách

Lỗi đầu tiên là nhảy thẳng vào retry hay tác vụ chạy lâu mà bỏ qua chương 1. Các pattern đó đều dựng trên resource. Nếu resource đặt tên lộn xộn, pattern hay đến mấy cũng chỉ làm hợp đồng rối thêm.

Lỗi thứ hai là mang pattern trong sách áp ngược lên một API đang chạy của khách. Bản tóm tắt của System Design Space coi thay đổi tương thích ngược là chiến lược versioning mặc định, và theo tinh thần đó, đổi tên hàng loạt endpoint đang có người dùng là tự tạo ra sự cố.

Hãy dùng pattern cho những gì bạn sắp thêm, không phải để đập lại những gì đã chạy.

## Chứng minh điều đó trong CV

Trong CV, đừng ghi tên cuốn sách. Hãy ghi hợp đồng bạn để lại và nó đứng vững ra sao, ví dụ "thiết kế API tích hợp có idempotency key, không phát sinh đơn trùng khi khách bật retry". Khi tin tuyển dụng nhắc đến "design APIs" hay "build integrations", đó là câu chuyện bạn nên kể trong phỏng vấn.

Mục tiêu của việc đọc không phải thuộc lòng pattern. Mục tiêu là ở buổi họp tiếp theo, bạn là người đầu tiên hỏi: "Nếu lệnh này bị gọi hai lần thì sao?"

**Thử ngay tuần này:**

- Đọc chương 1 trên bản livebook của Manning, rồi viết ra danh sách resource của API bạn đang tích hợp: tên gì, thuộc về resource nào.
- Chọn một endpoint ghi dữ liệu trong dự án hiện tại và tự hỏi: nếu hệ thống của khách gọi lại lần thứ hai sau timeout thì chuyện gì xảy ra? Ghi câu trả lời vào tài liệu thiết kế.
- Liệt kê mọi tác vụ có thể chạy lâu hơn timeout phía khách, rồi phác thảo cho mỗi tác vụ một cách trả về trạng thái để khách hỏi lại.

## Nguồn

- [API Design Patterns (Manning Publications)](https://www.manning.com/books/api-design-patterns)

- [API Design Patterns, Chapter 1: Introduction to APIs (Manning livebook)](https://livebook.manning.com/book/api-design-patterns/chapter-1)

- [API Design Patterns (short summary), System Design Space](https://system-design.space/en/chapter/api-design-patterns-book)

- [API Design Patterns (Nicolas Fränkel, DEV Community)](https://dev.to/nfrankel/api-design-patterns-5208)

- [API Design Patterns, 1st edition (Pearson)](https://www.pearson.com/store/en-gb/p/api-design-patterns/P200000004835/9781617295850)