Chuyển tới nội dung chính

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.

  1. Gọi GET /api/csrf và giữ cookie phiên đăng nhập mà nó đặt. Nó trả về {"headerName": "X-CSRF-TOKEN", "parameterName": "_csrf", "token"}.
  2. Gửi token trong header đó kèm mọi POST, PUT và DELETE, ví dụ POST /api/registrations.
  3. Đăng nhập qua POST /login với các trường biểu mẫu email, password và token. Nó trả về một redirect, không bao giờ là JSON: tới / khi thành công, và tới /login?error khi thất bại.
  4. 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.
  5. Đọc danh tính đang đăng nhập từ GET /api/session.

Với curl và jq:

bash
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"

Chạy các lệnh trên với một deployment: CSRF token, đăng nhập, session và một Project mới

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:

json
{
"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áiMã có thể đến từ bất kỳ endpoint nào
400validation_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)
401authentication_required (chưa có phiên đăng nhập)
403access_denied (endpoint dành cho quản trị viên, hoặc CSRF token thiếu hay đã cũ)
404not_found (không có địa chỉ đó)
405method_not_allowed (địa chỉ không nhận phương thức đó)
415unsupported_media_type (địa chỉ không đọc body thuộc kiểu đó)
500internal_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ẫnVai trò
GET /api/statuscông khai
GET /api/csrfcông khai
POST /api/registrationscông khai
GET /api/sessionthành viên
GET /api/me/ui-locale, PUT /api/me/ui-localethành viên
GET /api/organization/output-languagethành viên
PUT /api/organization/output-languagequản trị viên
GET /api/organization/slugthành viên
PUT /api/organization/slugquản trị viên
GET /api/members, GET /api/members/changesquản trị viên
PUT /api/members/{memberId}/role, DELETE /api/members/{memberId}quản trị viên
GET /api/invitations, POST /api/invitationsquản trị viên
POST /api/invitations/{invitationId}/reissuequản trị viên
DELETE /api/invitations/{invitationId}quản trị viên
POST /api/public/invitations/inspect, POST /api/public/invitations/acceptcông khai

Project và nguồn — Nguồn​

Phương thức và đường dẫnVai trò
GET /api/projects, POST /api/projectsthành viên
GET /api/projects/{projectId}/sources, GET /api/projects/{projectId}/sources/{sourceId}thành viên
POST /api/projects/{projectId}/sourcesquản trị viên
PUT /api/projects/{projectId}/sources/{sourceId}/tokenquản trị viên
POST /api/projects/{projectId}/sources/{sourceId}/webhook-secret, PUT /api/projects/{projectId}/sources/{sourceId}/webhook-secretquản trị viên
POST /api/projects/{projectId}/sources/{sourceId}/disconnect, POST /api/projects/{projectId}/sources/{sourceId}/reconnectquản trị viên
GET /api/projects/{projectId}/importsthành viên
POST /api/projects/{projectId}/sources/{sourceId}/importsquản trị viên
POST /api/projects/{projectId}/sources/{sourceId}/imports/resumequản trị viên

Thay đổi — Thay đổi và review​

Phương thức và đường dẫnVai trò
GET /api/projects/{projectId}/changesthành viên
POST /api/projects/{projectId}/changes/{changeId}/reviewthành viên
POST /api/projects/{projectId}/changes/{changeId}/exclusionquản trị viên
DELETE /api/projects/{projectId}/changes/{changeId}/exclusionquản trị viên
POST /api/projects/{projectId}/changes/{changeId}/ai-classificationthành viên
POST /api/projects/{projectId}/changes/{changeId}/missing-narrativesthành viên
GET /api/projects/{projectId}/duplicate-candidatesthành viên
POST /api/projects/{projectId}/duplicate-candidates/{candidateId}/decisionthành viên
GET /api/projects/{projectId}/sensitive-pathsthành viên
PUT /api/projects/{projectId}/sensitive-pathsquản trị viên
GET /api/projects/{projectId}/contextthành viên
PUT /api/projects/{projectId}/contextquản trị viên
GET /api/categoriesthành viên
POST /api/categoriesquản trị viên
PUT /api/categories/{categoryId}, DELETE /api/categories/{categoryId}quản trị viên
POST /api/categories/{categoryId}/unarchivequản trị viên
GET /api/category-suggestionsquản trị viên
POST /api/category-suggestions/{suggestionId}/decisionquản trị viên

Release và release note — Release note​

Phương thức và đường dẫnVai trò
GET /api/projects/{projectId}/releases, POST /api/projects/{projectId}/releasesthành viên
GET, PUT, DELETE /api/projects/{projectId}/releases/{releaseId}thành viên
PUT /api/projects/{projectId}/releases/{releaseId}/schedulethành viên
GET /api/projects/{projectId}/releases/{releaseId}/available-changesthành viên
POST /api/projects/{projectId}/releases/{releaseId}/changesthành viên
DELETE /api/projects/{projectId}/releases/{releaseId}/changes/{changeId}thành viên
POST /api/projects/{projectId}/releases/{releaseId}/request-reviewthành viên
POST /api/projects/{projectId}/releases/{releaseId}/linked-issues/acceptancethành viên
PUT /api/projects/{projectId}/releases/{releaseId}/folding-suggestions/{trackerChangeId}/decisionthành viên; EXCLUDE quản trị viên
PUT /api/projects/{projectId}/releases/{releaseId}/changes/{changeId}/decisionthành viên
PUT /api/projects/{projectId}/releases/{releaseId}/changes/{changeId}/summarythành viên
POST /api/projects/{projectId}/releases/{releaseId}/approvethành viên
POST /api/projects/{projectId}/releases/{releaseId}/return-to-draftthành viên
POST /api/projects/{projectId}/releases/{releaseId}/publishthành viên
POST /api/projects/{projectId}/releases/{releaseId}/translations/retrythành viên
GET /api/projects/{projectId}/releases/{releaseId}/note-previewsthành viên
GET /api/projects/{projectId}/releases/{releaseId}/notesthành viên
PUT /api/projects/{projectId}/releases/{releaseId}/notes/{noteId}thành viên
GET /api/projects/{projectId}/releases/{releaseId}/notes/{noteId}/downloadthành viên
GET /api/projects/{projectId}/release-assignmentsthành viên
GET /api/audiences, POST /api/audiencesquản trị viên
GET, PUT, DELETE /api/audiences/{audienceId}quản trị viên
PUT /api/audiences/{audienceId}/templates/{language}quản trị viên
POST /api/audiences/{audienceId}/retire, POST /api/audiences/{audienceId}/restorequản trị viên
POST /api/audiences/{audienceId}/reset-to-presetquản trị viên
POST /api/audiences/previewquản trị viên
GET /api/organization/release-languagesthành viên
PUT /api/organization/release-languagesquản trị viên
GET /api/glossary, GET /api/glossary/suggestionsthành viên
POST /api/glossary/kept-terms, DELETE /api/glossary/kept-terms/{termId}quản trị viên
POST /api/glossary/translations, DELETE /api/glossary/translations/{translationId}quản trị viên

Automation — Automation​

Phương thức và đường dẫnVai trò
GET /api/automation/rules, POST /api/automation/rulesquả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}/disablequản trị viên
POST /api/automation/rules/{ruleId}/executequản trị viên
POST /api/automation/rules/{ruleId}/webhook-secret/rotatequản trị viên
POST /api/automation/rules/cron-previewquả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}/cancelquả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ẫnBằng chứngHướng dẫn
POST /webhooks/github/{webhookId}X-Hub-Signature-256Nguồn
POST /webhooks/gitlab/{webhookId}Header Standard Webhooks hoặc X-Gitlab-TokenNguồn
POST /webhooks/linear/{webhookId}Linear-Signature, delivery, dấu thời gian và workspaceNguồn
POST /webhooks/automation/{webhookId}X-ReleaseFlow-Signature-256Automation
GET /webhooks/automation/{webhookId}/runs/{runId}X-ReleaseFlow-Signature-256Automation

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ựcTrạng tháiMã
Tài khoản400output_language_invalid, ui_locale_invalid, invitation_invalid, organization_slug_invalid
Tài khoản404invitation_not_found, member_not_found
Tài khoản409email_already_registered, invitation_already_pending, invitation_email_unavailable, organization_slug_taken, member_last_administrator
Nguồn400gitlab_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ồn404project_not_found, source_not_found
Nguồn409github_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ồn503github_unavailable, gitlab_unavailable, jira_unavailable
Webhook400webhook_payload_malformed
Webhook401webhook_signature_invalid
Webhook413webhook_payload_too_large
Webhook422webhook_repository_mismatch
Thay đổi400invalid_change_filter, invalid_change_review, invalid_sensitive_paths
Thay đổi404change_not_found, duplicate_candidate_not_found
Thay đổi409change_processing, change_not_eligible_for_ai, duplicate_candidate_decided, change_excluded, change_in_release
Thay đổi502ai_classification_failed
Thay đổi503ai_classification_unavailable
Category404category_not_found, category_suggestion_not_found
Category409category_code_taken, category_system, category_suggestion_decided
Audience400template_invalid, template_narratives_path, template_language_not_targeted, invalid_release_languages
Audience404audience_not_found
Audience409audience_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ữ404glossary_term_not_found
Bảng thuật ngữ409glossary_term_taken, glossary_limit
Release400invalid_release_schedule, invalid_upgrade_guide_url, invalid_previous_release, invalid_fold_decision
Release404release_not_found, release_note_not_found, folding_suggestion_not_found, linked_issue_not_found
Release409release_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
Automation400, 404, 409Xem Automation