HTTP용 Prefer 헤더

이 명세서는 Augmented Backus-Naur Form(ABNF) 표기법([RFC5234])을 사용하며, [RFC7230]의 섹션 3.2.1 및 3.2.4에서 정의된 "token", "word", "OWS", "BWS" 규칙과 #rule 확장을 참조로 포함합니다; 또한 [RFC7231]의 섹션 8.1.3에서 정의된 "delta-seconds" 규칙도 포함합니다.

1. 요청을 10초 내에 처리하지 못할 경우 비동기 처리로 202 (Accepted) 응답을 반환하도록 요청합니다. 또한 정의되지 않은 "priority" 선호도 지정되어 있습니다:

POST /some-resource HTTP/1.1
Host: example.org
Content-Type: text/plain
Prefer: respond-async, wait=10
Prefer: priority=5

{...}

2. 관대한(lenient) 처리를 사용:

POST /some-resource HTTP/1.1
Host: example.org
Content-Type: text/plain
Prefer: Lenient

{...}

3. return=minimal 선호에 대해 선택적이며 정의되지 않은 매개변수를 사용하는 예:

POST /some-resource HTTP/1.1
Host: example.org
Content-Type: text/plain
Prefer: return=minimal; foo="some parameter"

{...}

"respond-async" 선호는 클라이언트가 서버가 응답을 비동기적으로 수행하는 것을 선호함을 나타냅니다. 예를 들어 응답을 생성하는 데 걸리는 시간이 서버가 설정한 임의의 임계값을 초과할 경우, 서버는 202 (Accepted) 응답을 반환함으로써 "respond-async" 선호를 존중할 수 있습니다.

ABNF:

  respond-async = "respond-async"
      

"respond-async" 선호의 주요 동기는 클라이언트가 비동기 응답 처리에 대한 능력과 선호를 서버에 표시할 수 있게 하여 비동기 요청 처리의 작동을 용이하게 하는 것입니다.

"respond-async" 선호를 지정한 요청 예시:

POST /collection HTTP/1.1
Host: example.org
Content-Type: text/plain
Prefer: respond-async

{Data}

202 (Accepted)를 사용한 비동기 응답 예시:

HTTP/1.1 202 Accepted
Location: http://example.org/collection/123

202 (Accepted) 응답 상태는 [RFC7231]에서 정의되어 있지만, 해당 응답 코드를 언제 어떻게 사용하고 최종 결과를 결정하는 절차에 대해서는 거의 지침이 제공되지 않습니다. 따라서 특정 서버가 비동기 응답을 어떻게 지원하는지는 구현별 세부사항이며 본 명세서의 범위를 벗어납니다.

"return=representation" 선호는 클라이언트가 성공적인 요청에 대한 응답에 해당 리소스의 현재 상태를 나타내는 엔터티를 포함하기를 선호함을 나타냅니다.

반면 "return=minimal" 선호는 클라이언트가 성공적인 요청에 대해 서버가 최소한의 응답만 반환하길 원함을 나타냅니다. 일반적으로 이러한 응답은 204 (No Content) 상태를 사용할 수 있지만, 0 길이의 응답 엔터티를 가진 200 (OK)과 같은 다른 코드가 적절하게 사용될 수도 있습니다. 적절한 최소 응답의 판단은 전적으로 서버의 재량입니다.

ABNF:

  return = "return" BWS "=" BWS ("representation" / "minimal")
      

"return=representation" 선호를 존중할 때 반환된 표현은 요청이 영향을 미치는 다른 리소스를 위한 표현일 수 있으며, 이 경우 반환된 표현의 URI를 식별하기 위해 Content-Location 헤더를 사용할 수 있습니다.

"return=representation" 선호는 수정 이후 리소스의 현재 표현을 가져오기 위한 추가 GET 요청의 필요성을 제거하여 클라이언트와 서버 간 통신을 최적화하는 수단을 제공하는 것을 목표로 합니다.

POST 또는 PUT과 같은 수정 요청을 성공적으로 처리한 후, 서버는 작업의 상태를 설명하는 엔터티를 반환하거나 수정된 리소스 자체의 표현을 반환하기로 선택할 수 있습니다. 반환할 엔터티의 유형 선택은 전적으로 서버의 재량이지만, "return=representation" 및 아래 정의된 "return=minimal" 선호는 서버가 응답을 구성할 때 클라이언트의 선호를 고려할 수 있게 합니다.

"return=representation" 선호를 지정한 요청 예시:

PATCH /item/123 HTTP/1.1
Host: example.org
Content-Type: application/example-patch
Prefer: return=representation

1c1
< ABCDEFGHIJKLMNOPQRSTUVWXYZ
---
> BCDFGHJKLMNPQRSTVWXYZ

리소스 표현을 포함한 응답 예시:

HTTP/1.1 200 OK
Content-Location: http://example.org/item/123
Content-Type: text/plain
ETag: "d3b07384d113edec49eaa6238ad5ff00"

BCDFGHJKLMNPQRSTVWXYZ

대조적으로 "return=minimal" 선호는 요청 후 서버가 클라이언트에게 반환해야 하는 데이터 양을 줄일 수 있습니다. 이는 대역폭이 제한된 모바일 장치와 통신하거나 클라이언트가 요청 결과에 대한 추가 정보를 전혀 필요로 하지 않을 때 특히 유용합니다.

"return=minimal" 선호를 지정한 요청 예시:

POST /collection HTTP/1.1
Host: example.org
Content-Type: text/plain
Prefer: return=minimal

{Data}

최소 응답 예시:

HTTP/1.1 201 Created
Location: http://example.org/collection/123

"return=minimal"과 "return=representation" 선호는 상호 배타적인 지시입니다. 단일 요청에 두 선호가 동시에 포함되는 상황은 의미가 없을 것으로 예상되며, 그러한 요청은 보통 클라이언트의 코딩 오류로 인한 것입니다. 따라서 두 선호가 모두 포함된 요청은 어느 것도 지정되지 않은 것처럼 처리할 수 있습니다.

"wait" 선호는 클라이언트가 요청이 수신된 후 서버가 요청을 처리하는 데 걸릴 것으로 예상하는 최대 시간을 초 단위로 설정하는 데 사용할 수 있습니다. 응답 생성이 지정된 시간보다 오래 걸리는 경우 서버나 프록시는 비동기 처리 모델을 선택하여 예를 들어 202 (Accepted) 응답을 반환할 수 있습니다.

ABNF:

  wait = "wait" BWS "=" BWS delta-seconds
      

HTTP 메시지는 네트워크를 통과하고 중계자에 의해 처리되는 동안 일정 시간이 소요된다는 점을 고려하는 것이 중요합니다. 이는 클라이언트가 서버가 요청을 처리하는 데 걸리는 시간 외에도 응답을 기다리는 총 시간을 증가시킵니다. 엄격한 시간 요구사항을 가진 클라이언트는 이러한 요인을 추정하여 wait 값을 적절히 조정할 수 있습니다.

다른 선호와 마찬가지로 "wait" 선호는 무시될 수 있습니다. 클라이언트는 기다릴 준비가 된 시간보다 오래 걸리는 요청을 포기할 수 있습니다.

예를 들어 다음 요청을 받은 서버는 처리에 10초 이상 걸리는 경우 비동기 응답을 선택할 수 있습니다:

POST /collection HTTP/1.1
Host: example.org
Content-Type: text/plain
Prefer: respond-async, wait=10

{Data}

"handling=strict" 및 "handling=lenient" 선호는 요청 처리 중 발생할 수 있는 잠재적 오류 조건을 서버가 어떻게 처리하길 원하는지를 클라이언트가 표시할 때 사용됩니다. 예를 들어 요청의 페이로드에 다양한 경미한 구문 또는 의미론적 오류가 포함되어 있지만 서버가 요청을 이해하고 성공적으로 처리할 수 있는 경우, 요청을 적절한 "4xx" 오류로 거부할지 아니면 처리를 계속할지 결정해야 합니다. "handling=strict" 선호는 개별 오류가 복구 가능하더라도 클라이언트가 요청을 거부하기를 선호함을 나타냅니다. 반대로 "handling=lenient" 선호는 서버가 요청 처리를 시도하기를 원함을 나타냅니다.

ABNF:

  handling = "handling" BWS "=" BWS ("strict" / "lenient")
    

"strict" 선호를 지정한 요청 예시:

POST /collection HTTP/1.1
Host: example.org
Content-Type: text/plain
Prefer: handling=strict

"handling=strict"와 "handling=lenient" 선호는 서로 배타적인 지시입니다. 단일 요청에 두 선호가 동시에 포함되는 상황은 의미가 없을 것으로 예상되며, 그러한 요청은 대개 클라이언트의 코딩 오류로 인한 것입니다. 따라서 두 선호가 모두 포함된 요청은 어느 것도 지정되지 않은 것처럼 처리할 수 있습니다.

IANA는 "HTTP Preferences"라는 새 레지스트리를 "Hypertext Transfer Protocol (HTTP) Parameters" 레지스트리 아래에 생성했습니다. 새 등록은 Specification Required 정책([RFC5226])을 사용합니다. 등록된 선호에 대한 요구사항은 섹션 4에 설명되어 있습니다.

등록 요청은 일반적으로 필요한 명세에서 완성된 등록 템플릿을 포함합니다. 그러나 출판 이전에 값 할당을 허용하기 위해, 지정 전문가(Designated Expert)는 사전에 제출된 템플릿을 근거로 명세서가 출판될 것이라고 확신되면 등록을 승인할 수 있습니다. 지정 전문가는 널리 배포되어 있고 적시에 등록될 가능성이 낮은 비등록 선호를 제3자가 등록하도록 결정할 수 있습니다.

• Preference: (섹션 2에 주어진 문법 규칙을 따르는 Prefer 요청 헤더 필드의 값)
• Value: (선호 토큰에 대한 가능한 값의 열거 또는 설명)
• Optional Parameters: (선호 토큰과 관련된 선택적 매개변수 및 그 값의 열거)
• Description:
• Reference:
• Notes: [optional]

"Value" 및 "Optional Parameters" 필드는 특정 선호 토큰 정의가 어느 하나를 정의하지 않을 경우 등록 템플릿에서 생략될 수 있습니다.

등록 요청은 <ietf-http-wg@w3.org> 메일링 리스트로 보내져야 하며, 제목란에 명확히 표시되어야 합니다(예: "NEW PREFERENCE - example"은 "example" 선호를 등록하기 위한 것). 요청 제출 후 최대 14일 이내에 지정 전문가는 등록 요청을 승인하거나 거부하고 그 결정을 검토 리스트 및 IANA에 통지합니다. 거부 시에는 설명과, 해당되는 경우 성공적인 요청이 되기 위한 제안이 포함되어야 합니다.

전문가는 다음을 확인해야 합니다:

• 요청된 선호 이름이 섹션 2의 token 규칙을 따르며 다른 등록된 선호 이름과 동일하지 않다는 것;
• 관련된 값, 매개변수 이름 및 값이 섹션 2의 해당 ABNF 문법 사양에 부합하는지;
• 이름이 선호의 특수성에 적합한지; 즉 의미가 특정 애플리케이션에 매우 특화된 경우 이름이 이를 반영하여 덜 특화된 용도를 위한 일반 이름을 남겨둬야 한다는 것;
• 요청된 선호가 성공적인 처리를 위해 서버, 클라이언트 또는 중계자에게 필수적인 동작을 강제하지 않는지;
• 선호를 정의하는 명세 문서가 선호 사용과 관련된 적절하고 완전한 보안 고려사항 논의를 포함하는지.

• Preference: respond-async
• Description: 클라이언트가 서버가 요청에 대해 비동기적으로 응답하기를 선호함을 나타냄
• Reference: [this specification], 섹션 4.1

• Preference: return
• Value: "minimal" 또는 "representation" 중 하나
• Description: 값이 "minimal"인 경우 서버가 요청에 대해 최소 응답을 반환하기를 선호함을 나타냄. 값이 "representation"인 경우 서버가 요청에 대한 응답에 리소스의 현재 상태 표현을 포함하기를 선호함을 나타냄.
• Reference: [this specification], 섹션 4.2

• Preference: wait
• Description: 클라이언트가 요청이 수신된 후 서버가 요청을 처리하는 데 걸릴 것으로 예상하는 최대 시간을 나타냄
• Reference: [this specification], 섹션 4.3

• Preference: handling
• Value: "strict" 또는 "lenient" 중 하나
• Description: 값이 "strict"인 경우 클라이언트가 요청 처리에 엄격한 검증과 오류 처리를 적용하길 원함을 나타냄. 값이 "lenient"인 경우 클라이언트가 관대한 검증과 오류 처리를 적용하길 원함을 나타냄.
• Reference: [this specification], 섹션 4.4

7.1. 규범적 참고문헌

[RFC2119]

Bradner, S., “Key words for use in RFCs to Indicate Requirement Levels”, BCP 14, RFC 2119, March 1997, <http://www.rfc-editor.org/info/rfc2119>.

[RFC3864]

Klyne, G., Nottingham, M., and J. Mogul, “Registration Procedures for Message Header Fields”, BCP 90, RFC 3864, September 2004, <https://www.rfc-editor.org/info/rfc3864>.

[RFC5226]

Narten, T. and H. Alvestrand, “Guidelines for Writing an IANA Considerations Section in RFCs”, RFC 5226, May 2008, <https://www.rfc-editor.org/info/rfc5226>.

[RFC5234]

Crocker, D., Ed. and P. Overell, “Augmented BNF for Syntax Specifications: ABNF”, STD 68, RFC 5234, January 2008, <https://www.rfc-editor.org/info/rfc5234>.

[RFC7230]

Fielding, R., Ed. and J. Reschke, Ed., “Hypertext Transfer Protocol (HTTP/1.1): Message Syntax and Routing”, RFC 7230, June 2014.

[RFC7231]

Fielding, R., Ed. and J. Reschke, Ed., “Hypertext Transfer Protocol (HTTP/1.1): Semantics and Content”, RFC 7231, June 2014.

7.2. 비규범적 참고문헌

[RFC5023]

Gregorio, J., Ed. and B. de hOra, Ed., “The Atom Publishing Protocol”, RFC 5023, October 2007, <https://www.rfc-editor.org/info/rfc5023>.