안녕하세요! 😊
이 문서는 RFC 9457의 내용을 시간순으로, 그리고 최대한 자세하게 구조화하여 설명합니다.
중요한 대사(문장)는 인용구로, 핵심 키워드는 굵게 또는 코드로 표시해 이해를 돕겠습니다.

1. 개요 및 목적

RFC 9457은 HTTP API에서 발생하는 오류를 기계가 읽을 수 있는 표준 형식으로 전달하기 위한 "문제 상세 정보(Problem Details)" 포맷을 정의합니다.
이전 표준인 RFC 7807을 대체하며, JSON과 XML 두 가지 형식을 지원합니다.

"이 문서는 HTTP 응답 콘텐츠에서 오류에 대한 기계 판독 가능한 세부 정보를 전달하는 '문제 상세 정보'를 정의합니다. 이를 통해 HTTP API마다 새로운 오류 응답 포맷을 정의할 필요가 없어집니다."

왜 필요한가요?

• HTTP 상태코드만으로는 오류의 원인을 충분히 설명하기 어렵습니다.
• 사람은 HTML 오류 페이지를 보고 이해할 수 있지만, API를 사용하는 프로그램은 그렇지 못합니다.
• 따라서, 기계가 이해할 수 있는 구조화된 오류 정보가 필요합니다.

"HTTP 상태코드는 오류에 대한 충분한 정보를 제공하지 못할 때가 많습니다. 웹 브라우저를 사용하는 사람은 HTML 응답을 이해할 수 있지만, HTTP API의 비인간 소비자는 그렇지 않습니다."

2. 요구사항 용어

문서 내에서 MUST, SHOULD, MAY 등은 RFC 2119/8174에 따라 엄격한 의미로 사용됩니다.

3. 문제 상세 정보 JSON 객체

3.1 기본 구조

• 문제 상세 정보는 기본적으로 JSON 객체입니다.
• 미디어 타입은 application/problem+json입니다.
• XML 형식(application/problem+xml)도 지원합니다.

예시

{
  "type": "https://example.com/probs/out-of-credit",
  "title": "잔액이 부족합니다.",
  "detail": "현재 잔액은 30이지만, 해당 상품의 가격은 50입니다.",
  "instance": "/account/12345/msgs/abc",
  "balance": 30,
  "accounts": ["/account/12345", "/account/67890"]
}

"잔액이 부족합니다."
"현재 잔액은 30이지만, 해당 상품의 가격은 50입니다."

• type: 문제 유형을 식별하는 URI
• title: 짧고 사람이 읽을 수 있는 요약
• detail: 구체적인 설명
• instance: 이 문제 발생의 고유 식별자(URI)
• balance, accounts: 확장 필드 (문제 유형에 따라 추가 가능)

여러 오류를 한 번에 표현할 때

{
  "type": "https://example.net/validation-error",
  "title": "요청이 유효하지 않습니다.",
  "errors": [
    {
      "detail": "양의 정수여야 합니다.",
      "pointer": "#/age"
    },
    {
      "detail": "'green', 'red', 'blue' 중 하나여야 합니다.",
      "pointer": "#/profile/color"
    }
  ]
}

"요청이 유효하지 않습니다."
"양의 정수여야 합니다."
"'green', 'red', 'blue' 중 하나여야 합니다."

• errors: 각 오류의 세부 정보를 배열로 제공

여러 문제 유형이 동시에 발생할 경우

• 가장 중요한 문제만 응답에 포함하는 것이 권장됩니다.

3.1 문제 상세 정보 객체의 멤버

3.1.1 type

• 문제 유형을 식별하는 URI (예: https://example.com/probs/out-of-credit)
• 없으면 기본값은 about:blank
• 절대 URI 사용을 권장합니다.

"type 멤버가 없으면 값은 'about:blank'로 간주합니다."

• URI가 실제로 접근 가능한 경우, 문제 유형에 대한 문서를 제공해야 합니다.
• 상대 URI는 혼동을 줄 수 있으니 주의!

3.1.2 status

• HTTP 상태코드 (예: 403, 422 등)
• 참고용이며, 실제 HTTP 응답의 상태코드와 일치해야 합니다.

"status 멤버는 참고용이며, 실제 HTTP 응답의 상태코드와 일치해야 합니다."

3.1.3 title

• 문제 유형의 짧은 요약 (사람이 읽기 쉬움)
• 문제마다 바뀌지 않고, 로컬라이징(다국어 지원)만 다를 수 있습니다.

3.1.4 detail

• 이 문제 발생에 대한 구체적 설명
• 클라이언트가 문제를 해결하는 데 도움이 되는 정보에 집중해야 합니다.

3.1.5 instance

• 이 문제 발생의 고유 식별자(URI)
• 실제로 접근 가능하면, 해당 문제에 대한 추가 정보를 제공할 수 있습니다.
• 절대 URI 사용을 권장합니다.

3.2 확장 멤버(Extension Members)

• 문제 유형에 따라 추가적인 멤버를 정의할 수 있습니다.
• 예: balance, accounts, errors 등
• 클라이언트는 모르는 확장 멤버는 무시해야 합니다.

"클라이언트는 인식하지 못하는 확장 멤버를 무시해야 하며, 이를 통해 문제 유형이 진화할 수 있습니다."

4. 새로운 문제 유형 정의하기

4.1 언제 새 문제 유형을 정의해야 할까?

• HTTP 상태코드만으로 충분하지 않을 때 새 문제 유형을 정의합니다.
• 디버깅 정보가 아니라, HTTP 인터페이스의 의미를 전달하는 용도입니다.
• 보안상 주의: 내부 구현 정보를 노출하지 않도록 주의해야 합니다.

"문제 상세 정보는 내부 구현의 디버깅 도구가 아니라, HTTP 인터페이스 자체에 대한 더 많은 정보를 노출하는 방법입니다."

• 너무 일반적인 문제(예: 403 Forbidden)는 굳이 새로 정의할 필요 없음

4.2 문제 유형 등록(Registry)

• 공통적으로 쓰이는 문제 유형 URI는 IANA에 등록할 수 있습니다.
• 등록 시에는 다음 정보를 포함해야 합니다:
  • Type URI
  • Title
  • 추천 HTTP 상태코드
  • 참고 문서

4.2.1 about:blank

• 기본 문제 유형
• 추가 의미 없이, HTTP 상태코드만으로 의미가 충분할 때 사용
• 이 경우 title은 상태코드의 표준 문구(예: 404면 "Not Found")를 사용

"about:blank가 사용될 때, title은 해당 상태코드의 표준 문구와 같아야 하며, 필요에 따라 로컬라이징될 수 있습니다."

5. 보안 고려사항

• 문제 상세 정보에 포함되는 정보는 신중하게 검토해야 합니다.
• 민감한 정보(예: 스택 트레이스, 내부 경로 등)가 노출되지 않도록 주의!
• status 멤버와 실제 HTTP 상태코드가 다를 경우 혼란이 생길 수 있으니, 항상 일치시키는 것이 좋습니다.

"문제 상세 정보를 생성할 때 포함되는 정보는 신중하게 검토되어야 하며, 시스템을 위험에 빠뜨릴 수 있는 정보가 노출되지 않도록 해야 합니다."

6. IANA 등록 사항

• application/problem+json, application/problem+xml 미디어 타입이 이 문서를 참조하도록 갱신됨
• HTTP Problem Types 레지스트리가 생성되고, about:blank이 기본값으로 등록됨

7. 참고 문헌

• HTTP, JSON, XML, URI 등 관련 표준 문서가 참고로 명시되어 있습니다.

부록

A. JSON 스키마 예시

• 문제 상세 정보 객체의 비공식 JSON 스키마가 제공됩니다.

B. XML 형식

• XML 기반 API를 위한 문제 상세 정보 XML 포맷과 예시가 제공됩니다.

C. 기타 포맷과의 연동

• HTML 등 다른 포맷에 문제 상세 정보를 포함하는 방법(예: <script type="application/problem+json">로 JSON 삽입)도 설명합니다.

핵심 요약 및 활용 팁

• 문제 상세 정보(Problem Details)는 HTTP API에서 오류를 표준화된 구조로 전달하는 방법입니다.
• 기본 필드: type, title, status, detail, instance
• 확장 필드: 문제 유형에 따라 자유롭게 추가 가능
• JSON/XML 모두 지원, 미디어 타입은 각각 application/problem+json, application/problem+xml
• 보안상 민감 정보 노출 주의!
• IANA 레지스트리를 통해 공통 문제 유형을 등록/재사용 가능

마무리

이상으로 RFC 9457의 주요 내용을 시간순, 구조적으로 정리해보았습니다!
이 표준을 따르면, API 오류 응답을 일관되고, 기계가 이해할 수 있으며, 확장 가능한 방식으로 제공할 수 있습니다.
궁금한 점이 있으면 언제든 질문해 주세요! 🚀

주요 키워드:

• 문제 상세 정보(Problem Details)
• HTTP API
• JSON/XML
• type, title, status, detail, instance
• 확장 필드(Extension Members)
• about:blank
• 보안
• IANA 레지스트리