130 lines
11 KiB
Markdown
130 lines
11 KiB
Markdown
---
|
|
title: RFC 7807 Problem Details for HTTP APIs
|
|
source_type: official-doc
|
|
url: https://datatracker.ietf.org/doc/html/rfc7807
|
|
archive_url:
|
|
status: reviewed
|
|
confidence: high
|
|
tags: [ca-error-envelope, rfc7807, problem-detail, rest-api, http]
|
|
related_projects: [ca-skeleton-operational-contract]
|
|
related_branches: [feature-operational-error-observability-foundation, feature-boundary-validation-mapping-contract, feature-business-rule-validation-contract]
|
|
created: 2026-05-22
|
|
last_reviewed: 2026-05-27
|
|
---
|
|
|
|
# RFC 7807 — Problem Details for HTTP APIs
|
|
|
|
> Layer: `raw/official-docs/` — IETF RFC 7807 의 HTTP API error envelope 표준. ca-tmpl 이 명시적으로 forbidden 으로 둔 표준 — 채택 안한 결정의 trade-off 평가 근거.
|
|
|
|
## Parent / 활용 branch (필수)
|
|
|
|
| Branch | 이 자료가 정당화하는 결정 |
|
|
|---|---|
|
|
| [[raw/branch-notes/feature-operational-error-observability-foundation]] | ca-tmpl custom envelope vs RFC 7807 ProblemDetail 채택 결정의 표준 reference |
|
|
| [[raw/branch-notes/feature-boundary-validation-mapping-contract]] | boundary validation error 시 응답 shape 결정 (RFC 7807 미채택 근거) |
|
|
| [[raw/branch-notes/feature-business-rule-validation-contract]] | business rule violation 응답 shape 결정 (RFC 7807 미채택 근거) |
|
|
| [[raw/project-notes/ca-skeleton-operational-contract]] | §3. Structured API Response Contract + §6. Operational Error Category — 미채택 표준 reference |
|
|
|
|
## 컨텍스트 / 왜 저장했는지
|
|
|
|
ca-tmpl 이 명시적으로 **forbidden** 으로 둔 표준. custom envelope (`{success, data, error.{code,category,message,retryable,details}, meta}`) 결정의 trade-off 를 평가하려면 표준의 정확한 shape, 확장 메커니즘, 한계를 먼저 알아야 함. RFC 7807 은 현재 RFC 9457 로 obsolete 되었으나 본 문서는 7807 기준 정리.
|
|
|
|
## 출처 / Source
|
|
|
|
- 원본 URL: https://datatracker.ietf.org/doc/html/rfc7807
|
|
- 후속 RFC (obsolete 시킴): RFC 9457 (Problem Details for HTTP APIs — 2023 revision)
|
|
- Media type: `application/problem+json`, `application/problem+xml`
|
|
- 아카이브 URL: (미수집)
|
|
- 저자 / 조직: IETF (Editors: M. Nottingham, E. Wilde)
|
|
- 발행일: RFC 7807 — March 2016
|
|
- 마지막 확인일: 2026-05-27 (WebFetch 재검증 성공 — 5개 quote 모두 verbatim 일치. strength `needs-confirmation` → `official-standard` 으로 upgrade. [2026-05-25 capture] verbatim 보존본 유지)
|
|
|
|
## 핵심 인용 / Key quotes (verbatim)
|
|
|
|
> [§3.1, captured 2026-05-22] "The canonical model for problem details is a JSON object. When serialized as a JSON document, that format is identified with the 'application/problem+json' media type."
|
|
|
|
> [§3.1, captured 2026-05-22] "Consumers MUST use the 'type' string as the primary identifier for the problem type; the 'title' string is advisory and included only for users who are not aware of the semantics of the URI."
|
|
|
|
> [§3.2 — Extension Members, captured 2026-05-22] "Problem type definitions MAY extend the problem details object with additional members... Clients consuming problem details MUST ignore any such extensions that they don't recognize."
|
|
|
|
> [§3.1 — status, captured 2026-05-22] "Generators MUST use the same status code in the actual HTTP response, to assure that generic HTTP software that does not understand this format still behaves correctly."
|
|
|
|
> [§3.1 — detail, captured 2026-05-22] "The 'detail' member, if present, ought to focus on helping the client correct the problem, rather than giving debugging information."
|
|
|
|
> **[2026-05-27 verified — WebFetch 재검증 성공]**: 본 5개 quote (RFC7807-C1 ~ C5) 모두 https://datatracker.ietf.org/doc/html/rfc7807 live 페이지에서 FOUND VERBATIM. §번호 확인: C1 = §3, C2/C4/C5 = §3.1, C3 = §3.2. strength `needs-confirmation` → `official-standard` (IETF RFC) 으로 upgrade. [2026-05-25 capture] verbatim 본문 유지. RFC 9457 (후속) 과의 차이는 별도 raw 작성 시 검증.
|
|
|
|
## Claims Extracted / 추출된 주장
|
|
|
|
| Claim ID | Claim (이 자료가 직접 말하는 것) | Evidence quote | Strength | Applies to | Does not prove |
|
|
|---|---|---|---|---|---|
|
|
| RFC7807-C1 | problem details 의 canonical model 은 JSON object 이며, `application/problem+json` media type 으로 식별 | [§3, captured 2026-05-22 + 2026-05-27 verified verbatim] "The canonical model for problem details is a JSON object. When serialized as a JSON document, that format is identified with the 'application/problem+json' media type." | `official-standard` [2026-05-27 verified, IETF RFC] | HTTP API 의 error 응답 shape | XML 응답 (`application/problem+xml`) 도 동등하게 정의되어 있으나 본 인용 범위 밖 |
|
|
| RFC7807-C2 | consumer 는 `type` string 을 problem type 의 primary identifier 로 사용해야 하며 (`MUST`), `title` 은 advisory | [§3.1, captured 2026-05-22 + 2026-05-27 verified verbatim] "Consumers MUST use the 'type' string as the primary identifier for the problem type; the 'title' string is advisory and included only for users who are not aware of the semantics of the URI." | `official-standard` [2026-05-27 verified, IETF RFC] | RFC 7807 consumer 구현 | `code` 같은 짧은 머신리더블 식별자가 표준에 1급 필드로 있다는 뜻은 아님 — `type` URI 가 식별자 역할 |
|
|
| RFC7807-C3 | problem type 정의는 추가 member 로 확장 가능 (`MAY`), client 는 알 수 없는 확장을 무시해야 함 (`MUST`) | [§3.2 — Extension Members, captured 2026-05-22 + 2026-05-27 verified verbatim] "Problem type definitions MAY extend the problem details object with additional members... Clients consuming problem details MUST ignore any such extensions that they don't recognize." | `official-standard` [2026-05-27 verified, IETF RFC] | RFC 7807 의 확장 메커니즘 (예: `balance`, `retryable` 등) | 어떤 확장 필드를 표준이 권장한다는 뜻은 아님 — `code`/`category`/`retryable` 모두 확장 영역 |
|
|
| RFC7807-C4 | generator 는 problem details body 의 `status` 필드와 실제 HTTP response 의 status code 를 동일하게 사용해야 함 (`MUST`) | [§3.1 — status, captured 2026-05-22 + 2026-05-27 verified verbatim] "Generators MUST use the same status code in the actual HTTP response, to assure that generic HTTP software that does not understand this format still behaves correctly." | `official-standard` [2026-05-27 verified, IETF RFC] | RFC 7807 generator 구현 | HTTP status code 의 정확한 mapping (404 vs 422 등) 은 별도 표준. 본 인용은 일치 요구만 |
|
|
| RFC7807-C5 | `detail` member 는 client 가 문제를 정정하는 데 도움을 주는 데 초점을 두어야 하며, debugging 정보 제공이 아닌 (`ought to`) | [§3.1 — detail, captured 2026-05-22 + 2026-05-27 verified verbatim] "The 'detail' member, if present, ought to focus on helping the client correct the problem, rather than giving debugging information." | `official-standard` [2026-05-27 verified, IETF RFC] | `detail` 필드의 의도된 용도 | i18n / localization 표준은 별도 — `detail` 의 언어 정책은 본 인용 범위 밖. `ought to` 는 `SHOULD` 보다 약한 어조 |
|
|
| RFC7807-C6 | i18n / `Accept-Language` 기반 message localization 은 RFC 7807 표준에 **명시 없음** | (부재 자체가 claim — 2026-05-27 WebFetch 재검증 시에도 i18n / Accept-Language 관련 normative 진술 발견되지 않음) | `official-standard` [2026-05-27 verified — 부재 사실 확인] | 다국어 error message 정책 | RFC 7807 이 i18n 을 금지한다는 뜻 아님 — 구현자 책임 |
|
|
|
|
## Usage Boundaries / 적용 경계
|
|
|
|
- **이 자료가 직접 증명하는 것** (2026-05-22 capture + 2026-05-27 WebFetch verbatim 재검증):
|
|
- `RFC7807-C1`: media type `application/problem+json` 이 정식 IANA 등록 type
|
|
- `RFC7807-C2`: `type` URI 가 primary identifier (= 짧은 `code` 필드는 표준 1급 아님)
|
|
- `RFC7807-C3`: 확장 메커니즘 + unknown extension ignore 규칙
|
|
- `RFC7807-C4`: body status 와 HTTP status 일치 의무
|
|
- `RFC7807-C5`: `detail` 의 의도된 용도 (디버깅 정보 아님)
|
|
- **이 자료가 증명하지 않는 것**:
|
|
- 성공 응답 shape (RFC 7807 은 실패 전용 — 성공/실패 비대칭)
|
|
- 짧은 머신리더블 `code` 필드의 표준 부재 (`RFC7807-C2` 의 함의 — 확장 필드 사용 필요)
|
|
- `category` / `retryable` / `correlation-id` 같은 운영 메타데이터 (`C3` 의 확장 영역)
|
|
- i18n / Accept-Language 정책 (`C6`)
|
|
- 외부 client 라이브러리의 실제 `application/problem+json` 지원 범위
|
|
- **내 프로젝트에 적용하려면 추가 확인이 필요한 것**:
|
|
- 2026-05-27 시점 재확인 + RFC 9457 (후속) 과의 차이 검토 (특히 `type` URI 의 안정성 요구사항, `instance` URI 동작)
|
|
- ca-tmpl 의 `{success, data, error.{code,category,message,retryable,details}, meta}` 균일 shape 가 `RFC7807-C2` 의 `type` URI primary identifier 와 어떻게 충돌하는지 (custom `code` 채택 trade-off)
|
|
- Spring Boot `ProblemDetail` API (Spring Framework 6+) 와 ca-tmpl custom envelope 의 호환성
|
|
|
|
## ca-tmpl 함의 (내 프로젝트 해석)
|
|
|
|
> 본 섹션은 자료 직접 인용이 아닌 ca-tmpl 결정 컨텍스트 해석. wiki 추출 시 source-summary 로 옮겨야 함.
|
|
|
|
- **표준 vs custom 의 trade-off**:
|
|
- 표준 준수도 ↑ (RFC 7807), client lock-in ↓. 단 `application/problem+json` content negotiation 처리 client 가 드뭄 → 실질 호환성은 custom 과 큰 차이 없음 (해석).
|
|
- 성공/실패 shape 비대칭 (실패 전용) vs ca-tmpl 균일 shape (`success: false` 분기) — DX 트레이드오프.
|
|
- `type` URI 카탈로그 운영 부담 vs custom `code` enum 단순성.
|
|
- **운영 메타데이터**: `category` / `retryable` / `code` 모두 RFC 7807 확장 영역 (`RFC7807-C3`). custom envelope 으로 1급 필드 승격하는 것이 ca-tmpl 결정.
|
|
- **상태 코드 정합**: ca-tmpl 도 `RFC7807-C4` 와 동일하게 HTTP status code 와 body 상태 일치 의무 (직접적 표준 인용은 아니지만 동일 원칙).
|
|
|
|
## 응답 shape 예시 (RFC 7807)
|
|
|
|
```json
|
|
{
|
|
"type": "https://example.com/probs/out-of-credit",
|
|
"title": "You do not have enough credit.",
|
|
"status": 403,
|
|
"detail": "Your current balance is 30, but that costs 50.",
|
|
"instance": "/account/12345/msgs/abc"
|
|
}
|
|
```
|
|
|
|
- 모든 필드 optional. `type` 미지정 시 `"about:blank"`.
|
|
- 확장: top-level 에 임의 필드 추가 가능 (예: `balance`, `accounts`) — `RFC7807-C3`.
|
|
|
|
## 메모 / Notes
|
|
|
|
- **재검증 완료**: 2026-05-27 datatracker WebFetch 재검증 성공 (5/5 verbatim, §번호 확인 — C1=§3, C2/C4/C5=§3.1, C3=§3.2).
|
|
- **RFC 9457 후속**: 7807 은 obsolete. wiki 승급 시 9457 기준으로 업데이트할지 결정 필요.
|
|
- **단점 (해석)**: i18n 미지원, code 필드 없음 (확장 영역), 성공 응답 별도 — custom envelope 대비 운영 부담 큼.
|
|
|
|
## Related / 관련
|
|
|
|
- 같은 주제 다른 raw / 표준:
|
|
- RFC 9457 (Problem Details — 2023 revision) — 별도 raw 작성 후보
|
|
- Spring `ProblemDetail` API (Spring Framework 6+) — 별도 raw 작성 후보
|
|
- 인용하는 branch:
|
|
- [[raw/branch-notes/feature-operational-error-observability-foundation]]
|
|
- [[raw/branch-notes/feature-boundary-validation-mapping-contract]]
|
|
- [[raw/branch-notes/feature-business-rule-validation-contract]]
|
|
- 인용하는 project:
|
|
- [[raw/project-notes/ca-skeleton-operational-contract]] (§3, §6)
|
|
- 인용한 wiki 요약: (미작성)
|