Một API tốt là một API nhàm chán theo nghĩa tích cực nhất: URL dễ đoán, lỗi trung thực, schema nhỏ và ổn định, không có gì bất ngờ. Đây là những nguyên tắc định hình Noxyr Server API, được lấy từ các tiêu chuẩn ngành đứng sau Stripe, Resend, OpenAI và API chính thức của Discord.
1. URL có phiên bản
Mọi endpoint đều nằm dưới /api/v1/. Khi chúng tôi thêm thay đổi gây lỗi tương thích, các thay đổi đó sẽ nằm dưới /api/v2/: các tích hợp cũ vẫn tiếp tục hoạt động. Discord cũng làm như vậy với /api/v10/. Nếu API của bạn không có phiên bản, mỗi lần thay đổi schema sẽ trở thành một ticket hỗ trợ khách hàng.
2. Tài nguyên trước, hành động sau
Các endpoint của Noxyr được đặt tên theo danh từ: server, tickets, activity, invoices, reviews, giveaways. Tất cả đều chỉ đọc, đều dùng GET. Khi chúng tôi thêm các thao tác ghi, chúng sẽ là POST/PATCH/DELETE trên cùng những tài nguyên đó. Cách này khớp với quy ước REST và giữ mô hình tư duy rất gọn nhẹ.
3. Bearer token, một bí mật duy nhất
Xác thực dùng Authorization: Bearer nxr_.... Không có yêu cầu có chữ ký, cũng không có luồng OAuth cho dữ liệu máy chủ chỉ đọc. Các API hướng tới nhà phát triển hiện đại đều hội tụ về cách này vì nó hoạt động ở mọi nơi: curl, trình duyệt, Postman, các edge serverless. Discord cũng dùng bearer token cho người dùng được ủy quyền qua OAuth; mô hình này là phổ biến.
4. Chỉ lưu hash
Mọi khóa Noxyr đều được băm SHA-256 ở phía máy chủ. Giá trị gốc chỉ hiển thị một lần khi tạo và không bao giờ hiển thị lại. Nếu cơ sở dữ liệu của chúng tôi bị rò rỉ, không khóa nào có thể sử dụng được. Stripe, GitHub, Resend và mọi nhà cung cấp API được vận hành tốt đều làm như vậy; việc lưu khóa có thể đảo ngược là một dấu hiệu nguy hiểm.
5. Phạm vi chi tiết
Một khóa, sáu công tắc độc lập. Reviews là dữ liệu công khai; doanh thu là dữ liệu riêng tư. Tách chúng ra nghĩa là bạn có thể chia sẻ khóa chỉ dành cho reviews với đối tác marketing và giữ các con số doanh thu sau một công tắc khác. Thay đổi phạm vi có hiệu lực ngay lập tức (được kiểm tra ở mọi yêu cầu), nên việc thu hồi không cần phải xoay vòng khóa.
6. Phản hồi lỗi trung thực
Mọi lỗi đều là JSON với một mã máy ổn định và một thông báo dễ hiểu với con người:
{ "error": "scope_disabled", "message": "Phạm vi \"tickets\" đã bị tắt cho khóa này. Hãy bật nó trên trang API của dashboard." }Mã máy đọc được giúp việc thử lại và dashboard trở nên dễ dàng. Thông báo cho con người giúp gỡ lỗi nhanh hơn. Các lượt tìm kiếm "discord increased api errors" vào tháng 7 năm 2026 (Google Trends "tăng đột biến") cho thấy điều gì xảy ra khi lỗi không rõ ràng: người dùng phải đoán mò.
7. Chuỗi thời gian được điền đủ số 0
Endpoint /api/v1/activity trả về mọi ngày trong khoảng được yêu cầu, ngay cả khi số lượng bằng không. Frontend không phải tự điền các khoảng trống; biểu đồ không bị nhảy giữa các ngày rời rạc. Đây là một tiện ích nhỏ nhưng mang lại lợi ích lớn về chất lượng sử dụng.
8. Giới hạn tốc độ qua header
Mọi phản hồi đều có header RateLimit-* để client có thể lùi lại trước khi chạm lỗi 429. Đây là định dạng bản nháp IETF chuẩn hóa, cùng cấu trúc với GitHub và các API hiện đại khác, nên mọi thư viện client hiện có hỗ trợ định dạng này đều hoạt động ngay.
9. CORS cởi mở cho dữ liệu chỉ đọc
Các endpoint chỉ đọc gửi Access-Control-Allow-Origin: *. Vì khóa là thứ xác thực, chứ không phải nguồn gốc (origin), nên mở CORS không làm giảm bảo mật và cho phép các công cụ chạy trên trình duyệt gọi API trực tiếp, không cần proxy hay các cách vòng qua localhost.
10. Schema nhỏ, ổn định
Mọi phản hồi đều vừa một màn hình. Không có object lồng nhau không bắt buộc, không có trường chỉ xuất hiện khi bật một cờ tính năng. Schema nhỏ dễ cache, dễ kiểm thử và dễ khai báo kiểu trong TypeScript.
Xem trong thực tế: Hướng dẫn Server API. Và khi chính Discord gặp sự cố, hãy xem các lỗi API của Discord thực sự có nghĩa là gì.