이 메모의 상태

이것은 인터넷 표준 트랙 문서이다.¶

이 문서는 인터넷 엔지니어링 태스크포스(IETF)의 산출물이다. 이는 IETF 커뮤니티의 합의를 나타낸다. 이 문서는 공개 검토를 받았으며 인터넷 엔지니어링 운영 그룹(IESG)에 의해 발행 승인을 받았다. 인터넷 표준에 대한 추가 정보는 RFC 7841의 섹션 2에서 확인할 수 있다.¶

이 문서의 현재 상태, 정오표, 그리고 이에 대한 피드백 제공 방법에 관한 정보는 https://www.rfc-editor.org/info/rfc9457에서 확인할 수 있다.¶

Copyright Notice

Copyright (c) 2023 IETF Trust and the persons identified as the document authors. All rights reserved.¶

This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (https://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Revised BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Revised BSD License.¶

목차

1. 소개

HTTP 상태 코드(섹션 15 of [HTTP])가 항상 오류에 관한 충분한 정보를 유용하게 전달할 수 있는 것은 아니다. 웹 브라우저를 사용하는 사람은 HTML [HTML5] 응답 콘텐츠를 이해할 수 있는 경우가 많지만, HTTP API의 비인간 소비자는 그렇게 하기 어렵다.¶

이러한 부족함을 해결하기 위해, 이 명세는 발생한 문제의 구체 사항을 설명하는 간단한 JSON [JSON] 및 XML [XML] 문서 형식, 즉 "문제 상세 정보"를 정의한다.¶

예를 들어, 클라이언트의 계정에 충분한 크레딧이 없음을 나타내는 응답을 생각해 보자. API 설계자는 일반적인 HTTP 소프트웨어(예: 클라이언트 라이브러리, 캐시, 프록시)에 응답의 일반 의미론을 알리기 위해 403 Forbidden 상태 코드를 사용하기로 결정할 수 있다. API별 문제 상세 정보(예: 서버가 요청을 거부한 이유와 적용 가능한 계정 잔액)는 응답 콘텐츠에 담길 수 있으므로, 클라이언트가 이를 바탕으로 적절히 동작할 수 있다(예: 계정에 더 많은 크레딧을 이체하도록 트리거).¶

이 명세는 특정 "문제 유형"(예: "크레딧 부족")을 URI [URI]로 식별한다. HTTP API는 자신에게 고유한 문제를 식별하기 위해 자신이 제어하는 URI를 사용하거나, 상호운용성을 촉진하고 공통 의미론을 활용하기 위해 기존 URI를 재사용할 수 있다(섹션 4.2 참조).¶

문제 상세 정보에는 문제의 특정 발생을 식별하는 URI와 같은 다른 정보도 포함될 수 있다 (사실상 "지난 목요일 Joe가 충분한 크레딧을 갖고 있지 않았던 시점"이라는 개념에 식별자를 부여함). 이는 지원 또는 포렌식 목적에 유용할 수 있다.¶

문제 상세 정보의 데이터 모델은 JSON [JSON] 객체이다. JSON 문서로 직렬화될 때는 "application/problem+json" 미디어 유형을 사용한다. 부록 B는 "application/problem+xml" 미디어 유형을 사용하는 동등한 XML 형식을 정의한다.¶

문제 상세 정보가 HTTP 응답으로 전달될 때, 그 콘텐츠는 사전 협상을 사용하여 협상될 수 있다. 섹션 12.1 of [HTTP]를 참조하라. 특히, 사람이 읽을 수 있는 문자열(예: title 및 description에 있는 문자열)에 사용되는 언어는 Accept-Language 요청 헤더 필드(섹션 12.5.4 of [HTTP])를 사용하여 협상될 수 있지만, 그 협상 결과가 여전히 선호되지 않는 기본 표현을 반환할 수도 있다.¶

문제 상세 정보는 어떤 HTTP 상태 코드와도 함께 사용할 수 있지만, 가장 자연스럽게는 4xx 및 5xx 응답의 의미론에 들어맞는다. 문제 상세 정보가 HTTP에서 문제의 상세 정보를 전달하는 유일한 방법은 (당연히) 아니라는 점에 유의하라. 예를 들어 응답이 여전히 리소스의 표현이라면, 해당 애플리케이션의 형식으로 관련 상세 정보를 설명하는 것이 종종 더 바람직하다. 마찬가지로, 정의된 HTTP 상태 코드는 추가 상세 정보를 전달할 필요가 없는 많은 상황을 포괄한다.¶

이 명세의 목적은 공통 오류 형식이 필요한 애플리케이션을 위해 이를 정의하여, 각 애플리케이션이 자체 형식을 정의해야 하거나, 더 나쁘게는 기존 HTTP 상태 코드의 의미론을 재정의하려는 유혹을 받지 않도록 하는 것이다. 어떤 애플리케이션이 오류 전달에 이 형식을 사용하지 않기로 선택하더라도, 이 설계를 검토하면 기존 형식에서 오류를 전달할 때 마주하는 설계 결정을 안내하는 데 도움이 될 수 있다.¶

[RFC7807]로부터의 변경사항 목록은 부록 D를 참조하라.¶

2. 요구사항 언어

이 문서의 핵심 단어 "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", 및 "OPTIONAL"은, 여기에서 보인 것처럼 모두 대문자로 나타날 때에만 BCP 14 [RFC2119] [RFC8174]에 설명된 대로 해석되어야 한다.¶

3. 문제 상세 정보 JSON 객체

문제 상세 정보의 정규 모델은 JSON [JSON] 객체이다. JSON 문서로 직렬화될 때, 이 형식은 "application/problem+json" 미디어 유형으로 식별된다.¶

예:¶

POST /purchase HTTP/1.1
Host: store.example.com
Content-Type: application/json
Accept: application/json, application/problem+json

{
  "item": 123456,
  "quantity": 2
}

HTTP/1.1 403 Forbidden
Content-Type: application/problem+json
Content-Language: en

{
 "type": "https://example.com/probs/out-of-credit",
 "title": "You do not have enough credit.",
 "detail": "Your current balance is 30, but that costs 50.",
 "instance": "/account/12345/msgs/abc",
 "balance": 30,
 "accounts": ["/account/12345",
              "/account/67890"]
}

여기에서 크레딧 부족 문제(그 type으로 식별됨)는 "title"에서 403의 이유를 나타내고, "instance"로 특정 문제 발생을 식별하며, "detail"에 발생별 상세 정보를 제공하고, 두 개의 확장도 추가한다. "balance"는 계정 잔액을 전달하고, "accounts"는 계정을 충전할 수 있는 링크를 나열한다.¶

이를 수용하도록 설계된 경우, 문제별 확장은 같은 문제 유형의 여러 인스턴스를 전달할 수 있다. 예:¶

POST /details HTTP/1.1
Host: account.example.com
Accept: application/json

{
  "age": 42.3,
  "profile": {
    "color": "yellow"
  }
}

HTTP/1.1 422 Unprocessable Content
Content-Type: application/problem+json
Content-Language: en

{
 "type": "https://example.net/validation-error",
 "title": "Your request is not valid.",
 "errors": [
             {
               "detail": "must be a positive integer",
               "pointer": "#/age"
             },
             {
               "detail": "must be 'green', 'red' or 'blue'",
               "pointer": "#/profile/color"
             }
          ]
}

여기에서 가상의 문제 유형은 "errors" 확장을 정의한다. 이는 각 검증 오류의 상세 정보를 설명하는 배열이다. 각 멤버는 문제를 설명하는 "detail"과 JSON Pointer [JSON-POINTER]를 사용하여 요청 콘텐츠 안에서 문제의 위치를 가리키는 "pointer"를 포함하는 객체이다.¶

API가 서로 같은 유형을 공유하지 않는 여러 문제를 만난 경우, 가장 관련성이 높거나 긴급한 문제가 응답에 표현되는 것이 RECOMMENDED된다. 여러 이질적인 유형을 전달하는 일반적인 "batch" 문제 유형을 만드는 것은 가능하지만, 이는 HTTP 의미론에 잘 매핑되지 않는다.¶

또한 클라이언트가 Accept에 이 유형을 나열하지 않았음에도 API가 "application/problem+json" 유형으로 응답했다는 점에 유의하라. 이는 HTTP에서 허용된다(섹션 12.5.1 of [HTTP] 참조).¶

tag:example@example.org,2021-09-17:OutOfLuck

4. 새 문제 유형 정의

HTTP API가 오류 조건을 나타내는 응답을 정의해야 하는 경우, 새 문제 유형을 정의하는 것이 적절할 수 있다.¶

그렇게 하기 전에, 그것이 무엇에 유용한지와 어떤 것은 다른 메커니즘에 맡기는 것이 더 나은지 이해하는 것이 중요하다.¶

문제 상세 정보는 기반 구현을 위한 디버깅 도구가 아니다. 오히려 HTTP 인터페이스 자체에 관한 더 자세한 정보를 노출하는 방법이다. 새 문제 유형의 설계자는 보안 고려사항 (섹션 5), 특히 오류 메시지를 통해 구현 내부를 노출함으로써 공격 벡터를 노출할 위험을 신중하게 고려해야 한다.¶

마찬가지로, 진정으로 일반적인 문제, 즉 웹의 어떤 리소스에도 적용될 수 있는 조건은 일반 상태 코드로 표현하는 것이 보통 더 낫다. 예를 들어, PUT 요청에 대한 403 Forbidden 상태 코드는 그 자체로 설명적이므로 "write access disallowed" 문제는 아마 불필요하다.¶

마지막으로, 어떤 애플리케이션은 이미 정의한 형식 안에서 오류를 전달하는 더 적절한 방법을 가질 수 있다. 문제 상세 정보는 새 "fault" 또는 "error" 문서 형식을 확립해야 할 필요성을 피하기 위한 것이지, 기존 도메인별 형식을 대체하기 위한 것이 아니다.¶

그렇더라도, HTTP 콘텐츠 협상(예: 이 형식에 대한 선호를 나타내기 위해 Accept 요청 헤더 사용, [HTTP], 섹션 12.5.1 참조)을 사용하여 기존 HTTP API에 문제 상세 정보 지원을 추가할 수 있다.¶

새 문제 유형 정의는 다음을 MUST 문서화해야 한다:¶

1. type URI(일반적으로 "http" 또는 "https" 스킴 사용)¶
2. 이를 적절히 설명하는 title(짧게 생각하라)¶
3. 그 유형과 함께 사용될 HTTP 상태 코드¶

문제 유형 정의는 적절한 상황에서 Retry-After 응답 헤더([HTTP], 섹션 10.2.3)의 사용을 지정할 MAY 수 있다.¶

문제 유형 URI는 문제를 해결하는 방법을 설명하는 HTML [HTML5] 문서로 해석되는 것이 SHOULD 된다.¶

문제 유형 정의는 문제 상세 정보 객체의 추가 멤버를 지정할 MAY 수 있다. 예를 들어, 확장은 기계가 문제 해결에 사용할 수 있는 다른 리소스로의 typed link [WEB-LINKING]를 사용할 수 있다.¶

그러한 추가 멤버가 정의되는 경우, 그 이름은 문자(ALPHA, [ABNF], 부록 B.1에 따름)로 시작하는 것이 SHOULD 되며, ALPHA, DIGIT([ABNF], 부록 B.1), 및 "_" 문자로 구성되는 것이 SHOULD 된다 (JSON이 아닌 형식으로도 직렬화될 수 있도록). 또한 세 문자 이상인 것이 SHOULD 된다.¶

5. 보안 고려사항

새 문제 유형을 정의할 때는 포함되는 정보를 신중하게 검토해야 한다. 마찬가지로, 실제로 문제를 생성할 때에도, 그것이 어떤 방식으로 직렬화되든 제공되는 상세 정보는 또한 면밀히 검토되어야 한다.¶

위험에는 시스템, 시스템 접근, 또는 시스템 사용자들의 개인정보를 침해하는 데 악용될 수 있는 정보 유출이 포함된다.¶

발생 정보에 대한 링크를 제공하는 생성자는 스택 덤프와 같은 구현 상세 정보를 HTTP 인터페이스를 통해 제공하지 않는 것이 권장된다. 이는 서버 구현, 그 데이터 등에 관한 민감한 상세 정보를 노출할 수 있기 때문이다.¶

"status" 멤버는 HTTP 상태 코드 자체에서 이용 가능한 정보를 중복하여, 둘 사이에 불일치가 발생할 가능성을 가져온다. 불일치는 예를 들어 중개자가 전송 중에 HTTP 상태 코드를 변경했음을 나타낼 수 있기 때문에(예: 프록시 또는 캐시에 의해), 둘의 상대적 우선순위는 명확하지 않다. 일반 HTTP 소프트웨어(예: 프록시, 로드 밸런서, 방화벽, 바이러스 스캐너)는 이 멤버에 전달된 상태 코드를 알거나 존중할 가능성이 낮다.¶

6. IANA 고려사항

"Media Types" 레지스트리 아래의 "application" 레지스트리에서, IANA는 "application/problem+json" 및 "application/problem+xml" 등록을 이 문서를 참조하도록 업데이트했다.¶

IANA는 섹션 4.2에 명시된 대로 "HTTP Problem Types" 레지스트리를 만들고, 섹션 4.2.1에 따라 "about:blank"를 등록했다.¶

부록 A. HTTP 문제용 JSON 스키마

이 섹션은 HTTP 문제 상세 정보를 위한 비규범 JSON Schema [JSON-SCHEMA]를 제시한다. 이것과 명세 본문 사이에 불일치가 있는 경우, 후자가 우선한다.¶

# NOTE: '\' line wrapping per RFC 8792
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "An RFC 7807 problem object",
  "type": "object",
  "properties": {
    "type": {
      "type": "string",
      "format": "uri-reference",
      "description": "A URI reference that identifies the \
problem type."
    },
    "title": {
      "type": "string",
      "description": "A short, human-readable summary of the \
problem type."
    },
    "status": {
      "type": "integer",
      "description": "The HTTP status code \
generated by the origin server for this occurrence of the problem.",
      "minimum": 100,
      "maximum": 599
    },
    "detail": {
      "type": "string",
      "description": "A human-readable explanation specific to \
this occurrence of the problem."
    },
    "instance": {
      "type": "string",
      "format": "uri-reference",
      "description": "A URI reference that identifies the \
specific occurrence of the problem. It may or may not yield \
further information if dereferenced."
    }
  }
}

부록 B. HTTP 문제와 XML

XML [XML]을 사용하는 HTTP 기반 API는 이 부록에서 정의한 형식을 사용하여 문제 상세 정보를 표현할 수 있다.¶

XML 형식에 대한 RELAX NG 스키마 [ISO-19757-2]는 다음과 같다:¶

   default namespace ns = "urn:ietf:rfc:7807"

   start = problem

   problem =
     element problem {
       (  element  type            { xsd:anyURI }?
        & element  title           { xsd:string }?
        & element  detail          { xsd:string }?
        & element  status          { xsd:positiveInteger }?
        & element  instance        { xsd:anyURI }? ),
       anyNsElement
     }

   anyNsElement =
     (  element    ns:*  { anyNsElement | text }
      | attribute  *     { text })*

이 스키마는 문서화만을 목적으로 하며, XML 형식의 모든 제약을 포착하는 규범 스키마가 아님에 유의하라. 선택한 스키마 언어의 기능에 따라, 다른 XML 스키마 언어를 사용하여 유사한 제약 집합을 정의할 수도 있다.¶

이 형식의 미디어 유형은 "application/problem+xml"이다.¶

확장 배열과 객체는, 하나 이상의 자식을 포함하는 요소를 객체를 나타내는 것으로 간주하여 XML 형식으로 직렬화된다. 단, "i"라는 이름의 자식 요소만 하나 이상 포함하는 요소는 배열로 간주한다. 예를 들어, 위의 예는 XML에서 다음과 같이 나타난다:¶

HTTP/1.1 403 Forbidden
Content-Type: application/problem+xml
Content-Language: en

<?xml version="1.0" encoding="UTF-8"?>
<problem xmlns="urn:ietf:rfc:7807">
  <type>https://example.com/probs/out-of-credit</type>
  <title>You do not have enough credit.</title>
  <detail>Your current balance is 30, but that costs 50.</detail>
  <instance>https://example.net/account/12345/msgs/abc</instance>
  <balance>30</balance>
  <accounts>
    <i>https://example.net/account/12345</i>
    <i>https://example.net/account/67890</i>
  </accounts>
</problem>

이 형식은 XML 네임스페이스를 사용한다. 이는 주로 이를 다른 XML 기반 형식에 임베드할 수 있도록 하기 위한 것이며, 다른 네임스페이스의 요소나 속성으로 확장할 수 있거나 확장해야 함을 의미하지 않는다. RELAX NG 스키마는 XML 형식에서 사용되는 하나의 네임스페이스에 속한 요소만 명시적으로 허용한다. 모든 확장 배열과 객체는 오직 그 네임스페이스만 사용하여 XML 마크업으로 MUST 직렬화되어야 한다.¶

XML 형식을 사용할 때, XML에 XML 처리 명령을 임베드하여 클라이언트가 참조된 XSL Transformations (XSLT) 코드 [XSLT]를 사용해 XML을 변환하도록 지시할 수 있다. 이 코드가 XML을 (X)HTML로 변환한다면, XML 형식을 제공하면서도 변환을 수행할 수 있는 클라이언트가 클라이언트에서 렌더링되고 표시되는 사람 친화적인 (X)HTML을 표시하게 할 수 있다. 이 방법을 사용할 때에는 XSLT 코드를 실행할 수 있는 클라이언트 수를 최대화하기 위해 XSLT 1.0을 사용하는 것이 바람직하다는 점에 유의하라.¶

부록 C. 다른 형식과 함께 문제 상세 정보 사용

일부 상황에서는, 여기에서 설명한 형식 이외의 형식에 문제 상세 정보를 임베드하는 것이 유리할 수 있다. 예를 들어, HTML [HTML5]을 사용하는 API는 문제 상세 정보를 표현하는 데에도 HTML을 사용하고자 할 수 있다.¶

문제 상세 정보는 기존 직렬화(JSON 또는 XML) 중 하나를 해당 형식 안에 캡슐화하거나, 문제 상세 정보의 모델(섹션 3에 지정됨)을 그 형식의 관례로 변환함으로써 다른 형식에 임베드될 수 있다.¶

예를 들어, HTML에서는 문제를 script 태그 안에 JSON을 캡슐화하여 임베드할 수 있다:¶

<script type="application/problem+json">
  {
   "type": "https://example.com/probs/out-of-credit",
   "title": "You do not have enough credit.",
   "detail": "Your current balance is 30, but that costs 50.",
   "instance": "/account/12345/msgs/abc",
   "balance": 30,
   "accounts": ["/account/12345",
                "/account/67890"]
  }
</script>

또는 Resource Description Framework in Attributes (RDFa) [RDFA]로의 매핑을 정의할 수도 있다.¶

이 명세는 다른 형식에 문제 상세 정보를 임베드하는 것에 관해 구체적인 권고를 하지 않는다. 이를 임베드하는 적절한 방법은 사용 중인 형식과 그 형식의 적용 방식 모두에 따라 달라진다.¶

부록 D. RFC 7807로부터의 변경사항

이 개정판은 다음 변경사항을 만들었다:¶

• 섹션 4.2는 공통 문제 유형 URI의 레지스트리를 도입한다¶
• 섹션 3은 여러 문제를 어떻게 처리해야 하는지 명확히 한다¶
• 섹션 3.1.1은 역참조할 수 없는 type URI를 사용하는 지침을 제공한다¶

감사의 말

저자들은 의견과 제안을 제공한 Jan Algermissen, Subbu Allamaraju, Mike Amundsen, Roy Fielding, Eran Hammer, Sam Johnston, Mike McCall, Julian Reschke, 및 James Snell에게 감사한다.¶

저자 주소