새로운 HTTP QUERY 메서드 설명

RESTful API의 세계에서 우리는 오랫동안 엄격한 (자체적으로 부과된) 규칙에 따라 살아왔습니다. GET으로 데이터를 가져오든, POST로 엔티티를 생성하든, 또는 PUT으로 리소스를 업데이트하든, HTTP 메서드는 서버에 당신의 의도가 무엇인지 알려줍니다.

최근 RFC 10008이 발표되었으며, 이는 HTTP를 위한 새로운 QUERY 메서드를 정의합니다. 이미 다른 HTTP 메서드들이 있는데 왜 이것이 필요할까요? 함께 알아봅시다.

순수하게 기술적인 관점에서 보면, HTTP 메서드는 단순한 문자열일 뿐입니다. 이론적으로는

GET /api/v1/users

를 보내는 대신

FETCH /api/v1/users

를 사용할 수도 있습니다. 하지만 실제로는 GET이나 POST와 같이 잘 알려진 HTTP 메서드 주변에 수많은 RFC와 암묵적이고 문서화되지 않은 동작들이 존재합니다.

예를 들어, 브라우저는 주소를 입력하거나 북마크를 클릭할 때 GET 요청을 보냅니다. 표준 HTTP 폼 (forms)은 메서드로 GET과 POST만을 허용합니다. 대부분의 프록시 (proxies), 방화벽 (firewalls) 및 웹 서버 (webservers)는 오직 "표준" HTTP 메서드만을 허용합니다.

그렇다면 수십 년 동안 잘 작동해 온 기존 메서드 세트가 이미 있는데, 왜 새로운 HTTP 메서드를 도입하는 것일까요?

GET을 사용한 쿼리 (Queries)

전통적으로 리소스를 필터링하고 싶다면, GET 요청에서 쿼리 파라미터 (query parameters)를 사용했습니다 (예: /api/v1/users?role=admin&status=active&sort=desc).
이는 단순한 필터링에는 잘 작동합니다. 하지만 복잡한 관계형 쿼리 (relational queries), 깊은 중첩 (deep nesting), 또는 고급 로직을 수행해야 할 때, URL은 거대해지고 읽기 어려워지며, 때로는 브라우저나 서버의 문자 제한에 걸리기도 합니다.

다른 잠재적인 문제들은 다음과 같습니다:

• 비-ASCII (non-ASCII) 또는 특수 문자를 파라미터로 보내려면 인코딩 (encoding)이 필요하며, 이는 요청 크기를 증가시킵니다.
• 서버 및 기타 미들웨어 (middlewares)는 아마도 요청 파라미터를 로그 (log)에 남길 것이며, 이는 특정 상황에서 문제가 될 수 있습니다.
• 배열 (arrays)과 같은 일부 데이터 구조를 표현하는 방식은 잘 정의되어 있지 않고 구현 방식에 따라 다릅니다 (예: ?roles[0]=admin&roles[1]=reporter vs ?roles=admin&roles=reporter vs ?roles[]=admin&roles[]=reporter). 깊게 중첩된 구조를 표현하는 경우도 마찬가지입니다.

이 모든 것들이 데이터를 쿼리 파라미터 (query parameters)로 전송할 때 발생하는 단점들이므로, 단순히 JSON 요청 본문 (request body)을 포함한 GET 요청을 보내면 안 되는 걸까요? 다시 말하지만, 이론적인 관점에서는 이것이 작동해야 합니다. 어떤 HTTP RFC (Request for Comments)도 HTTP GET 요청을 수행할 때 요청 본문을 사용하는 것을 명시적으로 금지하지는 않지만, 그렇게 해서는 안 된다고 지시합니다. 그 결과, 다양한 클라이언트 (client), 프록시 (proxy) 및 웹 서버 (webserver) 구현체들은 본문이 포함된 GET 요청을 서로 다르게 처리합니다. 어떤 것들은 이를 즉시 거부하고, 어떤 것들은 단순히 본문을 버리며, 다른 것들은 이를 해석합니다.

이 때문에 요청 본문을 포함한 HTTP GET을 사용하는 것은 좋지 않은 생각입니다. 예를 들어 기업 방화벽 뒤에 있는 사용자나 다른 브라우저를 사용하는 사용자가 귀하의 웹사이트를 이용하지 못할 수도 있기 때문입니다. 이것이 바로 GET 요청이 이제 요청 본문을 지원해야 한다고 명시하는 새로운 RFC가 없는 이유이기도 합니다. 그렇게 한다면 수많은 기존 구현체들이 깨질 것이기 때문입니다.

해결책: POST를 이용한 쿼리 (Querying using POST)

GET을 사용하여 요청 본문을 보내는 것이 문제를 일으킬 수 있으므로, 해결책은 POST를 사용하는 것입니다.

POST는 요청 본문을 허용하지만, 심각한 의미론적 (semantic) 문제를 야기합니다. POST는 비멱등적 (non-idempotent)으로 정의되어 있으며, 리소스 생성 또는 처리를 목적으로 합니다.

이것이 엄청난 문제처럼 들리지 않을 수도 있지만, 예를 들어 실패 시 자동 재시도 (automatic retries)를 구현할 때 매우 번거로울 수 있습니다. GET 메서드는 안전하고 멱등적 (idempotent)으로 정의되어 있으므로, 서버 구현이 올바르다면 부작용 (side effects)을 걱정하지 않고 실패한 요청을 재시도할 수 있습니다. 또한 프록시나 다른 미들웨어 (middleware)가 해당 작업이 읽기 전용 (read-only)임을 자동으로 이해하는 것을 불가능하게 만듭니다. 예를 들어, 미들웨어는 GET 요청을 일정 시간 동안 자동으로 캐싱 (cache)할 수 있지만, 이는 POST 요청에서는 작동하지 않습니다.

QUERY 메서드

위의 모든 이유로 인해, 수년간의 논의 끝에 QUERY 메서드가 명시되었습니다. QUERY 메서드는 특별한 것이 아니며, RFC는 대략 이 메서드가 GET 메서드와 유사하지만 요청 본문을 가진다고 기술하고 있습니다. 이 메서드는 안전하고 멱등적 (idempotent)이어야 합니다.

QUERY 요청은 캐싱 (caching)될 수 있지만, 구현 시 요청 본문 (request content)을 캐시 키 (cache key)에 포함하도록 주의 깊게 처리해야 합니다. 요컨대, 이 메서드는 복잡한 검색 쿼리 (search queries)를 위한 적절한 HTTP 메서드를 마침내 제공합니다.

QUERY 주의사항 (gotchas)

모든 검색 관련 엔드포인트 (endpoints)를 즉시 QUERY를 사용하도록 전환하고 싶은 유혹이 생길 수 있습니다. 그렇게 하기 전에 고려해야 할 몇 가지 사항이 있습니다.

• HTTP QUERY에 대한 지원은 여전히 매우 제한적이며, 앞으로도 당분간은 그럴 수 있습니다. 모든 곳에서 완전히 지원되기까지는 수년이 걸릴 수도 있습니다. 예를 들어, Kreya는 최근 1.20 릴리스 (release)를 통해 HTTP QUERY에 대한 즉각적인 지원을 추가했습니다 (비록 이전에도 커스텀 HTTP 메서드를 보내는 것은 가능했지만 말입니다). 다른 클라이언트 (clients), 프록시 (proxies) 및 웹 서버 (webservers)는 여전히 이를 거부할 수 있습니다.
• URL 파라미터 (parameters)에 데이터를 포함하는 표준 GET 쿼리는 여전히 완벽하게 괜찮습니다. 이를 QUERY 메서드로 즉시 변경할 필요가 없다면 그대로 두십시오.
• 사용자가 필터링된 데이터의 링크를 공유하거나 북마크할 수 있어야 한다면, 계속해서 GET 요청을 사용하십시오. QUERY 요청으로서 링크를 공유하는 것은 작동하지 않습니다.
• QUERY 요청에 대한 커스텀 캐싱 (custom caching)을 구현하는 것은 요청 본문 (request body)을 고려해야 하기 때문에 GET 요청보다 더 어렵습니다.

결론

요약하자면, HTTP QUERY는 읽기 전용 (read-only) 요청에 대해 POST를 대체합니다. 모든 곳에서 완전히 지원될 때까지 시간이 걸릴 수 있지만, 일반적인 GET 요청이 귀하의 유스케이스 (use case)에 충분하지 않다면 여전히 이를 고려(및 테스트!)해야 합니다.