REST API
REST API làm được mọi việc mà các trang làm được, thông qua cùng các service của ứng dụng. Trang này trình bày các quy ước và liệt kê mọi endpoint; mỗi hướng dẫn được liên kết bên dưới mô tả đầy đủ body và hành vi của các endpoint thuộc về nó.
Phiên đăng nhập và CSRF
REST client dùng cùng chính sách phiên đăng nhập và CSRF như các trang do server dựng. Mọi thao
tác ghi đều cần CSRF token, và bảo vệ CSRF không bao giờ bị tắt: những đường dẫn duy nhất được
miễn là các endpoint webhook có chữ ký dưới /webhooks/, vốn không mang cookie và thay vào đó tự
chứng minh bằng một HMAC trên request. Xem ADR-0023.
Không có API token: một script đăng nhập với tư cách một người, bằng email và mật khẩu của người đó, rồi giữ cookie phiên đăng nhập.
- Gọi
GET /api/csrfvà giữ cookie phiên đăng nhập mà nó đặt. Nó trả về{"headerName": "X-CSRF-TOKEN", "parameterName": "_csrf", "token"}. - Gửi token trong header đó kèm mọi
POST,PUTvàDELETE, ví dụPOST /api/registrations. - Đăng nhập qua
POST /loginvới các trường biểu mẫuemail,passwordvà token. Nó trả về một redirect, không bao giờ là JSON: tới/khi thành công, và tới/login?errorkhi thất bại. - Lấy token mới. Đăng nhập thay phiên đăng nhập và token của nó, nên token ở bước 1
giờ bị từ chối với
403 access_denied. - Đọc danh tính đang đăng nhập từ
GET /api/session.
Với curl và jq:
BASE=http://localhost:8080
JAR=$(mktemp)
csrf() { curl -s -c "$JAR" -b "$JAR" "$BASE/api/csrf" | jq -r .token; }
curl -s -c "$JAR" -b "$JAR" -o /dev/null -w '%{redirect_url}\n' \
-H "X-CSRF-TOKEN: $(csrf)" \
--data-urlencode "email=$RELEASEFLOW_EMAIL" \
--data-urlencode "password=$RELEASEFLOW_PASSWORD" \
"$BASE/login" # prints $BASE/ when it worked, $BASE/login?error otherwise
TOKEN=$(csrf) # the signed-in session's token
curl -s -b "$JAR" "$BASE/api/session"
curl -s -b "$JAR" -c "$JAR" -H "X-CSRF-TOKEN: $TOKEN" \
-H 'Content-Type: application/json' -d '{"name": "Website"}' "$BASE/api/projects"

Một phiên đăng nhập kết thúc sau 30 phút không có request nào, khi ứng dụng khởi động lại, và
ở request tiếp theo khi vai trò của người đó thay đổi hoặc họ bị
xoá; sau đó, mọi lời gọi trả về 401 authentication_required cho tới khi script đăng nhập lại.
POST /logout kết thúc phiên ngay lập tức. Đặt RELEASEFLOW_SESSION_COOKIE_SECURE=true mỗi
khi ứng dụng được phục vụ qua HTTPS.
Organization luôn lấy từ người đang đăng nhập, không bao giờ từ body của request. Tài nguyên của Organization khác được báo là không tìm thấy, không bao giờ là bị cấm.
Lỗi
Mọi lỗi dưới /api đều là application/problem+json với một code cố định:
{
"title": "Release not found",
"status": 404,
"detail": "…",
"code": "release_not_found"
}
title và detail được viết bằng ngôn ngữ giao diện của
người đọc; code không bao giờ thay đổi, nên bên gọi cần so khớp theo nó. Lỗi kiểm tra dữ liệu có
thêm errors, một map từ tên trường tới thông báo.
| Trạng thái | Mã có thể đến từ bất kỳ endpoint nào |
|---|---|
400 | validation_failed (thiếu trường hoặc giá trị nằm ngoài khoảng cho phép), malformed_request (không đọc được body), invalid_parameter (một tham số trên đường dẫn hoặc query bị thiếu hoặc không chuyển đổi được, chẳng hạn một ID không phải UUID) |
401 | authentication_required (chưa có phiên đăng nhập) |
403 | access_denied (endpoint dành cho quản trị viên, hoặc CSRF token thiếu hay đã cũ) |
404 | not_found (không có địa chỉ đó) |
405 | method_not_allowed (địa chỉ không nhận phương thức đó) |
415 | unsupported_media_type (địa chỉ không đọc body thuộc kiểu đó) |
500 | internal_error (một lỗi ReleaseFlow không lường trước; body không bao giờ chứa exception gây ra nó) |
Một trạng thái mà không endpoint nào tự trả, chẳng hạn một 4xx từ servlet container, là
request_failed.
Độ ổn định
ReleaseFlow chưa phát hành phiên bản nào. Phiên bản tuân theo Semantic Versioning, và một thay
đổi không tương thích ở một endpoint được ghi là BREAKING CHANGE, làm tăng phiên bản major
(xem Releasing). code của một lỗi không bao giờ thay đổi. Một
bản phát hành minor chỉ thêm vào phản hồi: trường mới nằm bên cạnh trường mà bên gọi đang đọc
chứ không đổi hình dạng của nó. Ví dụ, một thay đổi vẫn giữ audienceNarratives là map từ mã
audience tới nội dung narrative, còn audienceNarrativeDetails bên cạnh cho biết relevance,
headline và body của từng narrative (Mỗi audience đọc gì);
Sửa tóm tắt nhận cả hai dạng trong narratives. Tương tự, một release có thêm glossaries, và
mỗi note có thêm glossaryStatus và glossaryReason, bên cạnh các trường vốn có
(Bảng thuật ngữ). Một thay đổi có thêm security, một release có
thêm upgradeGuideUrl, previousReleaseId và previousVersion, và một audience có thêm
footerTemplateBody và footerTemplateVariants; request bỏ các trường mới này vẫn chạy như trước
(Phần cuối). API không có tiền tố phiên bản và không có tài liệu OpenAPI; trang này và các hướng dẫn chính là
phần mô tả của nó. Chỉ GET /api/automation/runs có phân trang; mọi danh sách khác, kể cả
Change Inbox, trả về toàn bộ trong một lần.
Endpoint
Vai trò: công khai không cần phiên đăng nhập; thành viên cần một người bất kỳ đã đăng nhập; quản trị viên cần một quản trị viên.
Tài khoản và Organization — Workspace
| Phương thức và đường dẫn | Vai trò |
|---|---|
GET /api/status | công khai |
GET /api/csrf | công khai |
POST /api/registrations | công khai |
GET /api/session | thành viên |
GET /api/me/ui-locale, PUT /api/me/ui-locale | thành viên |
GET /api/organization/output-language | thành viên |
PUT /api/organization/output-language | quản trị viên |
GET /api/organization/slug | thành viên |
PUT /api/organization/slug | quản trị viên |
GET /api/members, GET /api/members/changes | quản trị viên |
PUT /api/members/{memberId}/role, DELETE /api/members/{memberId} | quản trị viên |
GET /api/invitations, POST /api/invitations | quản trị viên |
POST /api/invitations/{invitationId}/reissue | quản trị viên |
DELETE /api/invitations/{invitationId} | quản trị viên |
POST /api/public/invitations/inspect, POST /api/public/invitations/accept | công khai |
Project và nguồn — Nguồn
Thay đổi — Thay đổi và review
Release và release note — Release note
Automation — Automation
| Phương thức và đường dẫn | Vai trò |
|---|---|
GET /api/automation/rules, POST /api/automation/rules | quản trị viên |
GET, PUT, DELETE /api/automation/rules/{ruleId} | quản trị viên |
POST /api/automation/rules/{ruleId}/enable, POST /api/automation/rules/{ruleId}/disable | quản trị viên |
POST /api/automation/rules/{ruleId}/execute | quản trị viên |
POST /api/automation/rules/{ruleId}/webhook-secret/rotate | quản trị viên |
POST /api/automation/rules/cron-preview | quản trị viên |
GET /api/automation/runs, GET /api/automation/runs/{runId} | quản trị viên |
POST /api/automation/runs/{runId}/retry, POST /api/automation/runs/{runId}/cancel | quản trị viên |
Một action của lần chạy bị bỏ qua có trạng thái SKIPPED, và errorCode của nó nói lý do:
audience_retired hoặc nothing_for_audience. Bỏ qua không phải là lỗi và không có Problem
Details; xem Lần chạy.
Webhook có chữ ký
Các endpoint này không cần phiên đăng nhập hay CSRF token; mỗi endpoint tự chứng minh bằng secret
của riêng nó. Mọi thứ khác dưới /webhooks/ đều bị từ chối.
| Phương thức và đường dẫn | Bằng chứng | Hướng dẫn |
|---|---|---|
POST /webhooks/github/{webhookId} | X-Hub-Signature-256 | Nguồn |
POST /webhooks/gitlab/{webhookId} | Header Standard Webhooks hoặc X-Gitlab-Token | Nguồn |
POST /webhooks/linear/{webhookId} | Linear-Signature, delivery, dấu thời gian và workspace | Nguồn |
POST /webhooks/automation/{webhookId} | X-ReleaseFlow-Signature-256 | Automation |
GET /webhooks/automation/{webhookId}/runs/{runId} | X-ReleaseFlow-Signature-256 | Automation |
Changelog công khai
Ẩn danh, chỉ GET, và không bao giờ được cấp phiên đăng nhập: /changelog/{slug},
/changelog/{slug}/releases/{entryId} và /changelog/{slug}/rss.xml. Xem
Changelog công khai.
Mã lỗi theo khu vực
| Khu vực | Trạng thái | Mã |
|---|---|---|
| Tài khoản | 400 | output_language_invalid, ui_locale_invalid, invitation_invalid, organization_slug_invalid |
| Tài khoản | 404 | invitation_not_found, member_not_found |
| Tài khoản | 409 | email_already_registered, invitation_already_pending, invitation_email_unavailable, organization_slug_taken, member_last_administrator |
| Nguồn | 400 | gitlab_base_url_invalid, gitlab_host_not_allowed, jira_site_invalid, github_token_rejected, gitlab_token_rejected, linear_token_rejected, jira_token_rejected, source_credential_required, source_signing_token_invalid |
| Nguồn | 404 | project_not_found, source_not_found |
| Nguồn | 409 | github_repository_already_connected, gitlab_project_already_connected, linear_team_already_connected, jira_project_already_connected, source_token_missing, source_sync_in_progress, source_import_not_supported, source_import_not_resumable, source_disconnected, source_not_disconnected, source_reconnect_required, source_has_no_webhook, source_secret_generated, source_secret_pasted |
| Nguồn | 503 | github_unavailable, gitlab_unavailable, jira_unavailable |
| Webhook | 400 | webhook_payload_malformed |
| Webhook | 401 | webhook_signature_invalid |
| Webhook | 413 | webhook_payload_too_large |
| Webhook | 422 | webhook_repository_mismatch |
| Thay đổi | 400 | invalid_change_filter, invalid_change_review, invalid_sensitive_paths |
| Thay đổi | 404 | change_not_found, duplicate_candidate_not_found |
| Thay đổi | 409 | change_processing, change_not_eligible_for_ai, duplicate_candidate_decided, change_excluded, change_in_release |
| Thay đổi | 502 | ai_classification_failed |
| Thay đổi | 503 | ai_classification_unavailable |
| Category | 404 | category_not_found, category_suggestion_not_found |
| Category | 409 | category_code_taken, category_system, category_suggestion_decided |
| Audience | 400 | template_invalid, template_narratives_path, template_language_not_targeted, invalid_release_languages |
| Audience | 404 | audience_not_found |
| Audience | 409 | audience_code_taken, audience_limit, audience_last, audience_last_active, audience_already_retired, audience_not_retired, audience_in_use, audience_not_preset |
| Bảng thuật ngữ | 404 | glossary_term_not_found |
| Bảng thuật ngữ | 409 | glossary_term_taken, glossary_limit |
| Release | 400 | invalid_release_schedule, invalid_upgrade_guide_url, invalid_previous_release, invalid_fold_decision |
| Release | 404 | release_not_found, release_note_not_found, folding_suggestion_not_found, linked_issue_not_found |
| Release | 409 | release_status_conflict, release_published, release_empty, release_review_incomplete, change_summary_required, release_version_taken, classification_changed, change_not_releasable, change_excluded, release_note_render_failed, release_notes_missing, translations_not_ready, linked_issue_status_changed |
| Automation | 400, 404, 409 | Xem Automation |