REST API, parameter, query 에 대한 고찰

필자가 초창기에 REST API 를 이용해서 프로젝트 내부에 GET 을 구성할 때 가장 난감했던게 있었습니다.

'보면 이해가는데, 대체 어떻게 했길래 저렇게 해 낸걸까?'

 

예를 들면 아래의 react 코드가 있습니다.

  const getData = async () => {
    const res = await fetch(
      `https://api.jikan.moe/v4/anime?q=${search}&sfw&limit=6`
    );
    const resData = await res.json();
    setAnimeData(resData.data);
  };
  useEffect(() => {
    getData();
  }, [search]);

참고로 이 getAnimeSearch 의 경우, 그냥 홈페이지 내에서 소개하는 GET 부분의 표준 URL을 눌러보면

https://api.jikan.moe/v4/anime

만 나옵니다.

 

그렇다면 여기서 ?q=${search}&sfw&limit=6 가 뭘 뜻하는지는 유추가 가능하지만 

'저건 필자가 작명해 낸 query path 인 걸까?' 라는 생각이 들 수 있습니다.

 

안타깝게도 ? 의 정체는 최소한의 JavaScript 문법을 이해하지 않는 한 영영 알 수 없을겁니다. 최소한 react 를 하려면 자바스크립트는 필수라는 현실이 있습니다. 참고로 저건 조건의 확인을 요구하는 문법 정도로 여기시면 됩니다.

 

그리고 저 같이 독학으로 진행하는 분이라면 더욱 조심해야 할 점이, 길을 잃지 않으려면 schema 라는 개념에 대해 알고 가시는 걸 추천합니다. 이걸 알아야만, 최소한 내가 어느 허공에다가 지금 요청 신호를 보내고 있나를 유추할 수 있습니다. 마찬가지로, 여기에서 '뭘 불러올까?' 를 고민 해 볼 수 있는 일종의 수색 차트입니다.

 

CS 가르치는 대학에서는 이걸 알려주는지 모르겠으나, 이 schema 라는 걸 인지하지 않으면 매번 console.log 찍고 접근 성공 후, 브라우저 내에서 원하는 데이터 값을 추리해 나가는 난황이 있을겁니다.

 

그럼 q는 대체 뭘까요. 저것의 정체는 query parameter 입니다. 크게 path 와 query parameter 가 있는데, 이 query parameter 의 경우, 연결점이라 보면 되겠습니다. 

 

*참고로 "The path parameter defines the resource location, while the query parameter defines sort, pagination, or filteroperations." 입니다. (*필요 시 댓글 남겨주시면 번역하겠습니다. 필자의 언어적 편의상 원문으로 둡니다.)

 

자, sfw 또한 query parameter 입니다.

      `https://api.jikan.moe/v4/anime?q=${search}&sfw&limit=6`

 

그렇다면, 이제 뭐가 남았을까요? 네, 놀랍게도(?) liimt 도 query parameter 였습니다.

여기서 JS 만 쓰인 것은 다음과 같습니다.

      `https://api.jikan.moe/v4/anime?q=${search}&sfw&limit=6`

여담으로 ${search} 는 짐작하셨다시피, 저 코드블럭에는 생략 된 react 내에서 쓰인 useState 의 state 입니다. 저 search 부분이 제대로 fetch 가 이뤄졌는지(비유를 하면)안전 확인 장치로서 useEffect 쪽에 쓰이고 있었죠. 

 

여기까지가, query parameter 였습니다. 그럼 path parameter 는 뭘까요?

`For example, /users/{id}`, `{id}` is the path parameter of the endpoint

`/users`- it is pointing to a specific user's record.

An endpoint can have multiple path parameters, like in the example:

`/organizations/{orgId}/members/{memberId}`. 

 

여기서 {id} 와 {orgId} 같은 것이 path parameter 의 예시라 판단 해 볼 수 있습니다.조금만 더 볼까요?

 

```java curl /surfreport/beachId?days=3&units=metric&time=1400```

What do we see in this GET request?  

• `/surfreport/{beachID}` `/surfreport` is the endpoint, and `beachID` is the path parameter. The `/surfreport/{beachID}` path parameter takes a geographic beach code to look up the resource associated with that code.
• `?` is where our query string begins. This information is returned in a JSON file.

잊지마세요. GET request 라는걸 아는 확실한 척도는 그 API 문서에서 소개하고 있습니다.

 

여담이지만 위의 jikan api 는 v4 가 나온지 얼마 안되어서 아직 불안정합니다. 적어도 지금 사용하는 것은 비추천합니다.

 

저기...이거 말고 혹시 또 다른건 없나요?

있습니다. 혹시...끌리신다면 여기는 어떠신가 해서 남겨둡니다.

REST API Design Best Practices for Parameter and Query String Usage

How to design RESTful search/filtering?