Tự sinh client

~2 phút đọc

Nếu ngôn ngữ của bạn không có SDK chính thức, bạn vẫn có một client có kiểu đầy đủ bằng cách sinh nó từ đặc tả OpenAPI công khai. Đặc tả là hợp đồng của API: route, tham số và kiểu dữ liệu đều lấy từ đó, nên client sinh ra khớp với API.

Lấy đặc tả

Địa chỉ	Nội dung
`https://api.dongtien.pro/v1/openapi.json`	OpenAPI 3.1, chỉ gồm route công khai. Dùng bản này nếu trình sinh mã của bạn đọc được 3.1.
`https://api.dongtien.pro/v1/openapi-3.0.json`	Bản hạ cấp 3.0 của cùng đặc tả, cho trình sinh mã chưa đọc được 3.1.

Hai địa chỉ không cần khoá API. Trường info.version là ngày phiên bản API mà đặc tả mô tả.

curl -sS https://api.dongtien.pro/v1/openapi.json -o dongtien.v1.json

Sinh mã

Dùng bất kỳ trình sinh mã OpenAPI nào bạn quen; OpenAPI Generator là một công cụ phổ biến hỗ trợ nhiều ngôn ngữ, và nó là công cụ của bên thứ ba, không phải SDK của Dòng Tiền Pro.

npx @openapitools/openapi-generator-cli generate \
  -i dongtien.v1.json \
  -g <tên-trình-sinh> \
  -o ./dongtien-client

Một số lưu ý khi cấu hình:

Đặt tên phương thức theo operationId (tiếng Anh, ổn định, ví dụ listTransactions). Tên thẻ (tags) là tiếng Việt có dấu và nhiều trình sinh mã biến chúng thành tên không đẹp hoặc không hợp lệ.
Trường có thể rỗng được khai báo bằng anyOf với null ở bản 3.1 và bằng nullable ở bản 3.0.
Tiền là số nguyên VND, id là chuỗi có tiền tố, thời gian là chuỗi RFC 3339 UTC. Dùng kiểu số nguyên 64 bit khi ngôn ngữ của bạn có.
Chạy lại bước sinh mã khi API ra phiên bản mới. Thêm trường hoặc mã lỗi là thay đổi không phá vỡ, nên client cũ vẫn chạy được nếu bỏ qua trường lạ.

Những gì bạn tự cài

Trình sinh mã chỉ tạo kiểu và lời gọi. Bốn hành vi sau là phần viết tay mà SDK chính thức làm sẵn; hãy tự cài chúng ở lớp bọc quanh client sinh ra:

Header chung: Authorization: Bearer $DT_API_KEY và, nếu cần ghim, DongTien-Version.
Idempotency: route ghi cần Idempotency-Key được tạo một lần cho mỗi hành động và gửi lại nguyên khoá ở mọi lần thử. Xem Idempotency.
Thử lại: tối đa vài lần, lùi theo cấp số nhân có độ trễ ngẫu nhiên; 429 theo Retry-After; 5xx và lỗi mạng chỉ với yêu cầu đọc hoặc có khoá idempotency; không thử lại 4xx khác 429.
Lỗi và phân trang: đọc application/problem+json (code, request_id, errors[]) như ở trang Lỗi, và đi qua các trang bằng next_cursor cho tới khi has_more là false như ở trang Phân trang.