HTTP QUERY 메서드

이 문서는 다음에 정의된 용어를 사용합니다: 3절, [HTTP].

또한 URI 쿼리 매개변수라는 용어를 URI의 쿼리 구성 요소에 있는 매개변수(4.2.2절, [HTTP])에 사용하고, 쿼리 콘텐츠라는 용어를 요청 콘텐츠(6.4절, [HTTP]), 즉 QUERY 요청의 콘텐츠에 사용합니다.

핵심 단어 "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY" 및 "OPTIONAL"은 이 문서에서 다음에 설명된 대로 해석해야 합니다: BCP 14 [RFC2119] [RFC8174]. 단, 여기에 표시된 것처럼 모두 대문자로 나타나는 경우에만 해당합니다.

QUERY 요청의 의미론은 요청 콘텐츠와 미디어 유형 같은 관련 메타데이터 모두에 따라 달라집니다 ([HTTP], 8.3.1절). 일반적으로 콘텐츠와 메타데이터가 일치하지 않는 요청의 문제는 반드시 4xx (클라이언트 오류) 응답으로 거부해야 합니다 ([HTTP], 15.5절).

• 요청에 미디어 유형 정보가 없으면 정의상 올바르지 않으며 400 (클라이언트 오류) 같은 4xx 상태 코드로 실패해야 합니다.
• 미디어 유형이 지정되었지만 리소스에서 지원하지 않는 경우에는 415 (지원하지 않는 미디어 유형)가 적절합니다. 여기에는 특히 미디어 유형 자체는 알려져 있지만 대상 리소스에 대한 QUERY에 특화된 의미론이 없는 경우가 포함됩니다. 두 경우 모두 Accept-Query 응답 필드(3절)를 사용하여 클라이언트에 지원되는 미디어 유형을 알릴 수 있습니다.
• 미디어 유형이 지정되었지만 실제 요청 콘텐츠와 일치하지 않는 경우에는 400 (잘못된 요청)을 반환할 수 있습니다. 즉, 서버는 요청 콘텐츠에서 미디어 유형을 추론한 다음 누락되거나 "잘못된" 값을 덮어쓰는 것이 허용되지 않습니다 (즉, "콘텐츠 스니핑").
• 미디어 유형이 지정되어 이해할 수 있고 콘텐츠가 실제로 해당 유형과 일치하지만, 쿼리의 실제 내용 때문에 쿼리를 처리할 수 없다면 422 (처리할 수 없는 콘텐츠) 상태를 사용할 수 있습니다. 예를 들어 존재하지 않는 테이블을 식별하는, 구문상 올바른 SQL 쿼리가 있습니다.
• 클라이언트가 Accept 필드를 사용하여 특정 응답 미디어 유형을 요청했지만 ([HTTP], 12.5.1절), 리소스에서 이를 지원하지 않는 경우에는 406 (수용할 수 없음) 상태 코드가 적절합니다.

주어진 QUERY 요청의 동등 리소스는 GET 요청에 응답하고, 해당 QUERY 요청과 그 대상을 나타내며, 메시지 콘텐츠와 메타데이터 모두를 고려하는 리소스입니다 (6절, [HTTP]). 특히 여기에는 표현 메타데이터(8절, [HTTP]), 예를 들어 콘텐츠의 미디어 유형이 포함됩니다.

즉, 동등 리소스는 QUERY를 구현하는 리소스에서 요청 콘텐츠를 반영하여 파생됩니다.

동등 리소스라는 용어는 선택된 표현 같은 다른 HTTP 측면의 동작을 정의하기 위한 수단으로 사용됩니다. 서버는 이러한 리소스에 URI를 할당할 수 있지만 반드시 할당할 필요는 없습니다 (1.1절, [URI] 참조). URI를 할당하면 이러한 리소스에 GET 요청으로 접근할 수 있게 됩니다.

성공 응답(2xx, 15.3절, [HTTP])에는 연산 결과에 해당하는 리소스의 식별자가 담긴 Content-Location 헤더 필드가 포함될 수 있습니다. 자세한 내용은 8.7절, [HTTP]를 참조하십시오. 이는 클라이언트가 표시된 URI에 GET 요청을 보내 방금 수행된 쿼리 연산의 결과를 검색할 수 있다는 서버의 주장을 나타냅니다. 표시된 리소스는 임시적일 수 있습니다.

부록 A.4.1에서 예제를 참조하십시오.

서버는 QUERY 요청의 동등 리소스(2.2절)에 URI를 할당할 수 있습니다. 서버가 그렇게 하면 해당 리소스의 URI를 2xx 응답의 Location 헤더 필드에 포함할 수 있습니다 (다음 참조: 10.2.2절, [HTTP]). 이는 클라이언트가 표시된 URI에 GET 요청을 보내 쿼리 콘텐츠를 다시 전송하지 않고 방금 수행된 쿼리 연산을 반복할 수 있다는 주장입니다. 이 리소스의 URI는 임시적일 수 있습니다. 이후 요청이 실패하면 클라이언트는 원래 QUERY 요청 대상과 이전에 제출한 콘텐츠를 사용하여 재시도할 수 있습니다.

부록 A.4.2에서 예제를 참조하십시오.

경우에 따라 서버는 사용자 에이전트를 다른 URI로 리디렉션하여 QUERY 요청에 간접적으로 응답할 수 있습니다 (다음 참조: 15.4절, [HTTP]).

상태 코드가 301 (영구 이동, [HTTP], 15.4.2절) 또는 308 (영구 리디렉션, [HTTP], 15.4.9절)인 응답은 대상 리소스가 Location 응답 필드에서 참조하는 다른 URI로 영구적으로 이동했음을 나타냅니다 ([HTTP], 10.2.2절). 마찬가지로 상태 코드가 302 (발견됨, [HTTP], 15.4.3절) 또는 307 (임시 리디렉션, [HTTP], 15.4.8절)인 응답은 대상 리소스가 일시적으로 이동했음을 나타냅니다. 네 경우 모두 서버는 사용자 에이전트가 Location에서 참조하는 새 대상 URI로 유사한 QUERY 요청을 보내 원래 QUERY 요청을 완료할 수 있음을 제안합니다.

301 또는 302 응답 후 POST를 GET 요청으로 리디렉션하는 예외는 QUERY 요청에 적용되지 않는다는 점에 유의하십시오.

QUERY에 대해 상태 코드가 303 (다른 리소스 참조, 15.4.4절, [HTTP])인 응답은 Location 응답 필드에서 참조하는 URI에 대한 일반적인 검색 요청을 통해 원래 쿼리를 완료할 수 있음을 나타냅니다 ([HTTP], 10.2.2절). HTTP에서는 새 대상 URI에 GET 요청을 보내는 것을 의미하며, 이는 다음 예제에 나와 있습니다: 부록 A.4.3.

선택된 표현(3.2절, [HTTP])은 QUERY 요청의 경우 해당 QUERY 요청의 동등 리소스(2.2절)에 대한 GET 요청의 선택된 표현과 같습니다.

조건부 QUERY는 선택된 표현(즉, 콘텐츠 협상이 이루어진 후의 쿼리 결과)이 조건부 헤더 필드에 기술된 상황에서만 응답으로 반환되도록 요청하며, 이는 다음에 정의되어 있습니다: 13절, [HTTP].

부록 A.5에서 예제를 참조하십시오.

QUERY 메서드에 대한 응답은 캐시할 수 있습니다. 캐시는 이를 사용하여 후속 QUERY 요청을 충족할 수 있습니다. 다음을 따릅니다: 4절, [HTTP-CACHING].

QUERY 요청의 캐시 키(2절, [HTTP-CACHING])는 반드시 요청 콘텐츠(6절, [HTTP-CACHING]) 및 관련 메타데이터(8절, [HTTP])를 반영해야 합니다.

• 콘텐츠 인코딩 제거 (8.4절, [HTTP]).
• 요청의 Content-Type 필드에 있는 미디어 하위 유형 접미사로 표시되는 형식 규칙에 관한 지식을 바탕으로 정규화 (예: "+json"; 다음 참조: 4.2.8절, [RFC6838]).
• 요청의 Content-Type 필드로 표시되는 콘텐츠 자체의 의미론에 관한 지식을 바탕으로 정규화.

이러한 변환은 오직 캐시 키를 생성하기 위한 목적으로만 수행되며, 요청 자체를 변경하지 않는다는 점에 유의하십시오.

클라이언트는 "no-transform" 캐시 지시어를 사용하여 ( 5.2.1.6절, [HTTP-CACHING]) 이러한 변환이 이루어지지 않기를 바란다는 뜻을 나타낼 수 있습니다(단, 이 지시어는 권고일 뿐입니다).

QUERY 메서드 응답의 캐싱은 GET 응답의 캐싱보다 본질적으로 복잡하다는 점에 유의하십시오. 캐시 키를 결정하려면 요청 콘텐츠를 완전히 읽어야 하기 때문입니다. QUERY 응답이 Location 응답 필드(2.4절)를 제공하여 동등 리소스의 URI를 나타낸다면 (2.2절), 클라이언트는 후속 요청에서 GET으로 전환하여 처리를 간소화할 수 있습니다.

QUERY에 대한 범위 요청의 의미론은 GET에 대한 의미론과 같으며, 다음에 정의되어 있습니다: 14절, [HTTP]. 그러나 바이트 범위 요청은 (작성 시점에 정의된 유일한 범위 단위) QUERY 요청의 결과에는 별다른 가치를 제공하지 않습니다.

쿼리 형식은 결과 집합을 제한하거나 페이지별로 탐색하는 고유한 방식을 정의하는 경우가 많으며, SQL의 "FETCH FIRST ... ROWS ONLY"가 그 예입니다. 이러한 내장 기능이 HTTP 범위 요청 대신 사용될 것으로 예상됩니다.

IANA는 QUERY 메서드를 "하이퍼텍스트 전송 프로토콜(HTTP) 메서드 레지스트리"에 추가했습니다. 위치는 <http://www.iana.org/assignments/http-methods>입니다 (다음 참조: 16.3.1절, [HTTP]).

IANA는 Accept-Query 필드를 "하이퍼텍스트 전송 프로토콜(HTTP) 필드 이름 레지스트리"에 추가했습니다. 위치는 <https://www.iana.org/assignments/http-fields>입니다 (다음 참조: 16.1.1절, [HTTP]).

QUERY /contacts HTTP/1.1
Host: example.org
Content-Type: application/x-www-form-urlencoded
Accept: application/json

select=surname,givenname,email&limit=10&match=%22email=*@example.*%22

HTTP/1.1 200 OK
Content-Type: application/json

[
  { "surname": "Smith",
    "givenname": "John",
    "email": "smith@example.org" },
  { "surname": "Jones",
    "givenname": "Sally",
    "email": "sally.jones@example.com" },
  { "surname": "Dubois",
    "givenname": "Camille",
    "email": "camille.dubois@example.net" }
]

OPTIONS /contacts HTTP/1.1
Host: example.org

HTTP/1.1 200 OK
Allow: GET, QUERY, OPTIONS, HEAD

Allow 응답 필드(10.2.1절, [HTTP])는 지정된 리소스에서 지원되는 메서드 집합을 나타냅니다.

OPTIONS 사용에는 대안이 있습니다. 예를 들어 서버의 지원 여부를 미리 알지 못해도 QUERY 요청을 시도할 수 있습니다. 그러면 서버는 요청을 처리하거나 405 (허용되지 않는 메서드, 15.5.6절, [HTTP]) 같은 4xx 상태로 Allow 응답 필드를 포함하여 응답할 수 있습니다.

HEAD /contacts HTTP/1.1
Host: example.org

HTTP/1.1 200 OK
Content-Type: application/xhtml
Accept-Query: application/x-www-form-urlencoded, application/sql

어떤 요청 메서드에 대한 응답에 Accept-Query가 포함되는지는 접근하는 리소스에 따라 달라집니다.

HTTP/1.1 415 Unsupported Media Type
Content-Type: application/xhtml
Accept: application/x-www-form-urlencoded, application/sql

QUERY /contacts HTTP/1.1
Host: example.org
Content-Type: application/x-www-form-urlencoded
Accept: application/json

select=surname,givenname,email&limit=10&match=%22email=*@example.*%22

HTTP/1.1 200 OK
Content-Type: application/json
Content-Location: /contacts/stored-results/17
Location: /contacts/stored-queries/42
Last-Modified: Sat, 25 Aug 2012 23:34:45 GMT
Date: Sun, 17 Nov 2024, 16:10:24 GMT

[
  { "surname": "Smith",
    "givenname": "John",
    "email": "smith@example.org" },
  { "surname": "Jones",
    "givenname": "Sally",
    "email": "sally.jones@example.com" },
  { "surname": "Dubois",
    "givenname": "Camille",
    "email": "camille.dubois@example.net" }
]

QUERY /rfc-index.xml HTTP/1.1
Host: example.org
Date: Sun, 7 Sep 2025, 00:00:00 GMT
Content-Type: application/xslt+xml
Accept: text/csv

...XSLT를 사용하는 쿼리 콘텐츠...

HTTP/1.1 200 OK
Date: Sun, 7 Sep 2025, 00:00:00 GMT
Location: /stored-queries/4815162342
Content-Type: text/csv
Accept-Query: "application/sql", "application/xslt+xml"
Last-Modified: Sun, 31 Aug 2025, 08:44:00 GMT
Vary: Accept-Query, Content-Encoding, Content-Type

decade, total, with errata, % with errata, average page count
1960, 26, 5, 19.2, 5.3
1970, 666, 18, 2.7, 6.1
1980, 376, 44, 11.7, 23.4
1990, 1593, 269, 16.9, 25.5
2000, 2888, 1048, 36.3, 27.3
2010, 2954, 895, 30.3, 26.1
2020, 1133, 230, 20.3, 26.2

여기서 서버는 "/stored-queries/4815162342" 경로를 동등 리소스에 할당하여 (2.4절) 이후 GET에서 사용하도록 했습니다.

QUERY /rfc-index.xml HTTP/1.1
Host: example.org
Date: Mon, 8, Sep 2025, 11:00:00 GMT
Content-Type: application/sql
Accept: text/csv
If-Modified-Since: Sun, 31 Aug 2025, 08:44:00 GMT
Vary: Accept-Query, Content-Type

...같은 쿼리이지만 SQL 사용...

HTTP/1.1 304 Not Modified
Date: Mon, 8 Sep 2025, 11:00:00 GMT
Content-Type: text/csv
Location: /stored-queries/4815162342
Accept-Query: "application/sql", "application/xslt+xml"
Last-Modified: Sun, 31 Aug 2025, 08:44:00 GMT
Vary: Accept-Query, Content-Type

GET /stored-queries/4815162342 HTTP/1.1
Host: example.org
Date: Sun, 21, Sep 2025, 12:08:00 GMT
Accept: text/csv
If-Modified-Since: Sun, 31 Aug 2025, 00:00:00 GMT

HTTP/1.1 200 OK
Date: Sun, 21, Sep 2025, 12:08:00 GMT
Content-Type: text/csv
Last-Modified: Thu, 18 Sep 2025, 19:56:00 GMT
Vary: Accept-Query, Content-Encoding, Content-Type

decade, total, with errata, % with errata, average page count
1960, 26, 5, 19.2, 5.3
1970, 666, 18, 2.7, 6.1
1980, 376, 44, 11.7, 23.4
1990, 1593, 269, 16.9, 25.5
2000, 2888, 1048, 36.3, 27.3
2010, 2954, 895, 30.3, 26.1
2020, 1133, 230, 20.3, 26.2

(이 10년 기간에 해당하는 행의 변경에 유의하십시오.)

아래 다이어그램은 조건부 요청의 사용과, 동등 리소스에 URI가 할당되었을 때(그리고 클라이언트가 이를 활용할 때) 어떻게 달라질 수 있는지를 보여 줍니다. 가상의 필드 이름 "Validator"는 설명을 위해 사용됩니다.

다음 예제는 JSON 형태의 [RFC8259] RFC 정오표 데이터베이스에 대한 요청을 보여 줍니다.

아래 요청은 확장 가능 스타일시트 언어 변환(XSLT)을 사용하여 연도 및 정의된 정오표 유형별로 요약된 정오표 정보를 추출합니다.

QUERY /errata.json HTTP/1.1
Host: example.org
Content-Type: application/xslt+xml
Accept: application/xml, text/csv

<transform xmlns="http://www.w3.org/1999/XSL/Transform"
  xmlns:j="http://www.w3.org/2005/xpath-functions"
  version="3.0">

  <output method="text"/>

  <param name="input"/>

  <variable name="json"
    select="json-to-xml(unparsed-text($input))"/>

  <variable name="sc">errata_status_code</variable>
  <variable name="sd">submit_date</variable>

  <template match="/">
    <text>year, total, rejected, verified, hdu, reported</text>
    <text>&#10;</text>
    <variable name="en" select="$json//j:map"/>
    <for-each-group select="$en"
      group-by="substring-before(j:string[@key=$sd],'-')">
      <sort select="current-grouping-key()"/>
      <variable name="year" select="current-grouping-key()"/>
      <variable name="errata" select=
        "$en[$year=substring-before(j:string[@key=$sd],'-')]"/>
      <value-of select="concat(
        $year,
        ', ',
        count($errata),
        ', ',
        count($errata['Rejected'=j:string[@key=$sc]]),
        ', ',
        count($errata['Verified'=j:string[@key=$sc]]),
        ', ',
        count(
          $errata['Held for Document Update'=j:string[@key=$sc]]),
        ', ',
        count($errata['Reported'=j:string[@key=$sc]]),
        '&#10;')"/>
    </for-each-group>
  </template>

</transform>

HTTP/1.1 200 OK
Content-Type: text/csv
Accept-Query: "application/jsonpath", "application/xslt+xml"
Date: Wed, 19 Feb 2025, 17:10:01 GMT

year, total, rejected, verified, hdu, reported
2000, 14, 0, 14, 0, 0
2001, 72, 1, 70, 1, 0
2002, 124, 8, 104, 12, 0
2003, 63, 0, 61, 2, 0
2004, 89, 1, 83, 5, 0
2005, 156, 10, 96, 50, 0
2006, 444, 54, 176, 214, 0
2007, 429, 48, 188, 193, 0
2008, 423, 52, 165, 206, 0
2009, 331, 39, 148, 144, 0
2010, 538, 80, 232, 222, 4
2011, 367, 47, 170, 150, 0
2012, 348, 54, 149, 145, 0
2013, 341, 61, 169, 106, 5
2014, 342, 73, 180, 72, 17
2015, 343, 79, 145, 89, 30
2016, 295, 46, 122, 82, 45
2017, 303, 46, 120, 84, 53
2018, 350, 61, 118, 98, 73
2019, 335, 47, 131, 94, 63
2020, 387, 68, 117, 123, 79
2021, 321, 44, 148, 63, 66
2022, 358, 37, 198, 40, 83
2023, 262, 38, 121, 33, 70
2024, 322, 33, 125, 23, 141
9999, 1, 0, 0, 1, 0

QUERY /errata.json HTTP/1.1
Host: example.org
Content-Type: application/jsonpath
Accept: application/json

$..[
     ?@.errata_status_code=="Rejected"
     && @.submit_date>"2024"
   ]
   ["doc-id"]

HTTP/1.1 200 OK
Content-Type: application/json
Accept-Query: "application/jsonpath", "application/xslt+xml"
Date: Thu, 20 Feb 2025, 09:55:42 GMT
Last-Modified: Thu, 20 Feb 2025 06:10:01 GMT

[
  "RFC1185","RFC8407","RFC6350","RFC8467","RFC1157","RFC9543",
  "RFC9076","RFC7656","RFC2822","RFC9460","RFC2104","RFC6797",
  "RFC9499","RFC9557","RFC2131","RFC2328","RFC9001","RFC3325",
  "RFC9438","RFC2526","RFC2985","RFC7643","RFC9132","RFC6376",
  "RFC9110","RFC9460","RFC7748","RFC9497","RFC8463","RFC4035",
  "RFC7239","RFC9083","RFC9537","RFC9537","RFC9420","RFC9000",
  "RFC9656","RFC9110","RFC2324","RFC2549","RFC6797","RFC2549",
  "RFC8894"
]