Nhà phát triển & API

Bắt đầu

Mọi điểm cuối công khai đều là yêu cầu HTTPS GET trả về JSON. Không cần khóa. Hãy thử lấy trạng thái hệ thống:

curl -s "https://status.yucts.com/api/v2/status?locale=en"

# Conditional request — 304 Not Modified when nothing changed
curl -s -i "https://status.yucts.com/api/v2/services?locale=ja" -H 'If-None-Match: "<etag from the previous response>"'

Các phiên bản API

• v1 (/api/*) là API 1.x ổn định mà các ứng dụng và tiện ích hiện có đang dùng. Đặc tả đã được cố định: các trường không bao giờ bị xóa hay đổi tên.
• v2 (/api/v2/*) là API hiện hành: cấu trúc phản hồi thống nhất, mã lỗi, mã yêu cầu, ETag, phân trang bằng con trỏ và bảy ngôn ngữ.

Chính sách ngừng hỗ trợ

Các thay đổi không tương thích chỉ được phát hành dưới đường dẫn phiên bản mới. Phiên bản sắp ngừng hỗ trợ vẫn khả dụng ít nhất 12 tháng và được thông báo bằng tiêu đề Deprecation và Sunset trước khi bị gỡ bỏ.

Xác thực

Mọi endpoint trên trang này đều công khai và chỉ đọc, không cần xác thực. Các endpoint quản trị không nằm trong tài liệu này; quản trị viên đã đăng nhập xem tại mục “Tài liệu API” trong trang quản trị. Không bao giờ đặt thông tin xác thực vào URL.

Điểm cuối

Tài liệu tham chiếu đầy đủ được tạo từ chính mã nguồn phục vụ API, ở định dạng OpenAPI 3.1. /openapi.json

Lỗi

Lỗi của v2 có chung một định dạng. Hãy dùng code (không phải message) trong logic của bạn và gửi kèm mã yêu cầu khi báo cáo sự cố.

{
  "error": {
    "code": "not_found",
    "message": "Incident not found.",
    "status": 404,
    "request_id": "c0ffee00-…"
  }
}

Giới hạn tần suất

Các yêu cầu không trúng bộ nhớ đệm biên được giới hạn theo IP của máy khách (mặc định 600 yêu cầu mỗi phút). Khi bị giới hạn, bạn nhận được HTTP 429 kèm tiêu đề Retry-After.

Bộ nhớ đệm

Phản hồi công khai có thể được lưu đệm 30 giây (v1: 60 giây) và có ETag — gửi lại trong If-None-Match để nhận 304 Not Modified khi không có thay đổi. Phản hồi cá nhân như nhận diện ngôn ngữ không bao giờ được lưu đệm.

Ngôn ngữ

Truyền locale=zh-TW, zh-HK, zh-CN, en, ja, ko hoặc vi. Khi thiếu bản dịch sẽ dùng tiếng Nhật; mỗi trường văn bản cho biết ngôn ngữ thực tế được trả về trong trường *_locale tương ứng.

Webhook

Quản trị viên có thể gửi sự kiện sự cố và bảo trì tới các điểm cuối HTTPS (JSON chung, Discord hoặc Slack). Mọi yêu cầu đều được ký:

X-Yucts-Signature: t=1767225600,v1=5f2c…
X-Yucts-Event: incident.created
X-Yucts-Delivery: 42

Tính HMAC-SHA256 trên "<t>.<nội dung gốc>" bằng khóa bí mật của webhook và so sánh với v1 theo thời gian hằng định. Từ chối dấu thời gian cũ hơn năm phút và loại bỏ trùng lặp theo X-Yucts-Delivery.

import { createHmac, timingSafeEqual } from 'node:crypto';

// header = X-Yucts-Signature, rawBody = the exact request body string
export function verifyYuctsSignature(rawBody, header, secret) {
  const m = /^t=(\d+),v1=([0-9a-f]{64})$/.exec(header ?? '');
  if (!m) return false;
  const [, t, sig] = m;
  if (Math.abs(Date.now() / 1000 - Number(t)) > 300) return false; // replay window
  const expected = createHmac('sha256', secret).update(`${t}.${rawBody}`).digest();
  return timingSafeEqual(Buffer.from(sig, 'hex'), expected);
}

Ví dụ mã

const res = await fetch('https://status.yucts.com/api/v2/status?locale=en');
if (!res.ok) throw new Error(`HTTP ${res.status}`);
const { data } = await res.json();
console.log(data.status);             // "operational" | "degraded" | "partial_outage" | ...
console.log(data.active_incidents);   // ongoing incidents with their latest update

type ServiceStatus = 'operational' | 'degraded' | 'down' | 'maintenance' | 'unknown';
interface ServiceSummary {
  id: number;
  name: string;
  status: ServiceStatus;
  uptime: { h24: number | null; d30: number | null; d90: number | null }; // null = no data
}

async function services(locale = 'ja'): Promise<ServiceSummary[]> {
  const res = await fetch(`https://status.yucts.com/api/v2/services?locale=${locale}`);
  if (!res.ok) {
    const { error } = await res.json(); // { code, message, status, request_id }
    throw new Error(`${error.code} (${error.request_id})`);
  }
  return (await res.json()).data;
}

struct Envelope<T: Decodable>: Decodable { let data: T }
struct SystemStatus: Decodable {
    let status: String
    let counts: Counts
    struct Counts: Decodable { let total, operational, degraded, down, maintenance, unknown: Int }
}

func fetchStatus(locale: String = "zh-TW") async throws -> SystemStatus {
    var url = URLComponents(string: "https://status.yucts.com/api/v2/status")!
    url.queryItems = [URLQueryItem(name: "locale", value: locale)]
    let (data, response) = try await URLSession.shared.data(from: url.url!)
    guard (response as? HTTPURLResponse)?.statusCode == 200 else { throw URLError(.badServerResponse) }
    return try JSONDecoder().decode(Envelope<SystemStatus>.self, from: data).data
}

<?php
// WordPress: cache the status for 60 seconds with a transient.
function yucts_status() {
    $cached = get_transient('yucts_status');
    if ($cached !== false) return $cached;
    $res = wp_remote_get('https://status.yucts.com/api/v2/status?locale=en', ['timeout' => 5]);
    if (is_wp_error($res) || wp_remote_retrieve_response_code($res) !== 200) return null;
    $body = json_decode(wp_remote_retrieve_body($res), true);
    set_transient('yucts_status', $body['data'], 60);
    return $body['data'];
}

Hướng dẫn từng bước cho Swift/SwiftUI, JavaScript/TypeScript, WordPress và XenForo có trong tài liệu của kho mã.

Tiện ích nhúng

Hiển thị trạng thái trực tiếp trên bất kỳ trang nào (XenForo, WordPress, HTML thuần). Tiện ích 1.x vẫn hoạt động như cũ; tiện ích v2 có thiết kế mới, tách biệt với kiểu dáng của trang và hỗ trợ bảy ngôn ngữ.

<!-- 2.0 widget: same attributes, Shadow DOM isolation, 7 languages -->
<div class="yucts-status" data-view="overview" data-locale="zh-TW"></div>
<script src="https://status.yucts.com/embed/v2.js" defer></script>

<!-- 1.x widget (unchanged) -->
<div id="yucts-status"></div>
<script src="https://status.yucts.com/embed.js" defer></script>

Nhật ký thay đổi

• 2.0 — API v2, OpenAPI 3.1, tiếng Việt cho toàn bộ nội dung, tiện ích nhúng v2, huy hiệu, nguồn cấp dữ liệu, iCalendar, xuất dữ liệu, OpenMetrics (mỗi tính năng có công tắc riêng).
• 1.x — /api/overview, /api/status, /api/incidents, /api/slo, /api/maintenance, /api/geo, embed.js.