이 사이트의 번역글입니당.
"https://www.moesif.com/blog/technical/api-design/REST-API-Design-Best-Practices-for-Parameters-and-Query-String-Usage/"
REST API design Best Practices for Parameter and Query String Usage.
API를 설계할 때, 사용자에게 서비스 자체를 넘어 어느정도의 권한을 주는 것이 목표입니다. HTTP 동사(ex.POST, GET)와 URL 자원들이 기본적인 인터렉션을 허용하긴하지만. 보통 추가적인 기능을 제공하는 것이 필수적입니다. 혹은 추가적인 기능을 제공하지않으면 API가 이용하기 불편하게 됩니다.
페이지네이션의 예시를 들어보겠습니다. 만약 데이터베이스에 수백만의 article을 저장하고 있을때, 한번의 response에 모든 article을 전달하면 안됩니다. 이런 문제를 해결할 수 있는 방법은 parametrization(매개변수화)을 이용하는 것입니다.
What is Parametrization
일반적으로 parametrization은 한 종류의 request configuration (request 구성)이라고 할 수 있습니다. 단순히 'request'에 매개변수를 추가하는 것입니다.
프로그래밍 관점에서, 우리는 한 함수를 이용해서 반환값(return 값)을 요청할 수 있습니다. 만약에 그 함수가 아무 인자도 받지 않는다면, 우리는 반환값에 아무런 영향을 줄 수 없습니다.
API도 마찬가지입니다.! 특히 REST API 는 stateless기 때문에 더더욱 그렇습니다.
모든 REST 상호작용은 stateless입니다. 그말은 즉슨, 모든 요청은 연결에 필요한 필수적인 정보들을 각각 가지고 있다는 말입니다.
HTTP에 인자를 더하는 방법은 여러가지가 있습니다.
- query string,
- body of POST, PUT and Patch request
- header
이 세가지는 각각의 사용 방식과 규칙이 있습니다. 천천히 알아보죠!
인자를 전달할때 가장 간단한 방법은 모든 인자를 'body'에 집어넣는 것입니다. 많은 API들이 이 방식을 이용합니다. 모든 endpoint들은 POST요청을 이용하고 모든 인자들은 body안에 들어갑니다. 예전의 API에서는 맞는 방식입니다. 하지만 10년이 넘는동안 수많은 수의 인자들이 생겨났고, 수많은 종류의 인자들이 생겨났습니다. 지금의 상황에서는 모든 인자를 body에 넣어 이용하는 것은 적절치 않습니다.
What kind of parameter do we want to add?
우리 스스로에게 질문해야할 첫번째는 어떤 종류의 인자를 입력, 추가하고 싶은지? 입니다.
어쩌면 우리가 입력, 추가하려는 인자가 HTTP specification에 header로 이미 표준화되어있을수도 있습니다.
HTTP에는 여러가지 종류의 필드들이 표준화되어있습니다. header로 쓰라고 정의되어있는 것은 그렇게 따르시면 됩니다. 표준이니 되도록 따라야 합니다.
예를 들어 Accept header는 서버에서 어떤 타입의 받을지 정의할수 있게 해줍니다.
첫번째로 우리는 우리가 전달하고자하는 데이터가 HTTP header 표준으로 정의되어있는지 확인해봐야합니다. 확인해본 뒤 없다면 custom header를 만들어서 전달할지, 아니라면 queryString으로 전달할지 정합니다.
When should we use the query string?
우리가 원하는 인자(parameter)가 표준 Header값에 속하지 않거나 조심해야하는 데이터가 아니라면, query string으로 적합한지 확인할수 있습니다.
역사적으로 query string의 목적은 이름이 나타내듯이 데이터를 검색할 때 이용하는 것입니다. <isindex>라는 HTML 요소가 있는데, 서버에 특정 키워드를 보낼때 쓰입니다. 그리고 서버는 <inindex>로 보내진 특정 키워드와 메치되는 페이지를 응답합니다.
시간이 지나서 query string은 웹의 형식안에서 GET 요청을 통해 서버로 데이터를 보내기 위한 용도로 변경되었습니다.
그러므로 query string의 주 목적은 필터링, 검색, 그리고 페이지네이션입니다. 디테일한 내용은 이곳참조.
중량~
한가지 예를 들겠습니다. api를 이용하여 기사(article)를 읽어올 때 ?withComments를 query string 으로 붙일 수 있습니다. 혹은 query string대신에 header에 넣을 수도 있습니다.
HTTP specification에서도 맞는 용도라고 설명합니다. 그러나 custom header를 만들어서 전달하는 것보다 query string에 붙이는 것이 훨씬 빠르고 표현이 분명해집니다.
Header에 씌이기 알맞은 인자들은 여러 endpoint에서 쓰이는 것들입니다. 예를 들자면 authentication token 같은 것.
소수의 endpoint에서만 쓰이는 인자들은 queryString에 적합합니다.
