[RESTful API 설계하기] 3. RESTful API 데이터 조회 GET Method

[RESTful API 설계하기] 1. RESTful과 API

[RESTful API 설계하기] 2. REST 특징

[RESTful API 설계하기] 4. RESTful API 데이터 생성 POST Method

RESTful API중 데이터 조회를 위한 방법은 GET, HEAD 두 가지가 있다. 

Method가 조회를 담당하는데, 이중 HEAD는 실제 response body가 없는 녀석이다.

GET

{
  "took":"12",
  "code":"200",
  "response":"HTTP 1.1 200 OK",
  "Content-Type":"application/json;charset=UTF-8",
  "Content-Length":"79",
  "users" : [ {
    "address" : "dev.whoan@gmail.com",
    "name" : "dev.whoan",
    "user_SEQ" : "1"
  } ]
}

HEAD

{
  "took":"12",
  "code":"200",
  "response":"HTTP 1.1 200 OK",
  "Content-Type":"application/json;charset=UTF-8",
  "Content-Length":"79"
}

---

많은 사람들이 API를 생성할 때 다음과 같은 형식을 가지게 설계한다.

1. QueryString

GET /getUsers?name={name}&user_SEQ={seq}&type={type}&print={print}

2. URI Segment

GET /users/name/{name}/user_SEQ/{seq}?type={type}&print={print}
사실 이 방식은 MkWeb을 설계하면서 고안한 방법이고, 앞 글을 보면 내가 준 팁에 그대로 나와있다.

앞서 말한것 처럼 RESTful API는 URI Segment를 지향하고, 주소에 데이터 관련 조작 방식을 나타내지 않는게 좋기 때문에 2. URI Segment방식을 활용하여 설계하는 것이 좋다.

하지만 바로 전 글에서 말한것 처럼 꼭 이를 지킬 필요는 없다. ElasticSearch의 RESTful API같은 경우에는 QueryString중 q 파라미터를 통해 데이터를 조회하는것 처럼, 내가 잘 설계하고, 사람들에게 잘 지침을 주면 된다.

MkWeb의 경우에는 다음과 같이 설계 했다.

 /DATASET/조건1/{조건1값}/조건2/{조건2값}/...?OPTIONS

먼저 데이터 셋을 정의해라

어떤 RESTful API든 간에 우리가 조회하고자 하는 대상이 있다. 해당 대상에 대한 데이터 셋을 먼저 정의하고, URI의 최상단에 선언하자.

그렇게 되면, 우리가 조회하고자 하는 데이터가 무엇인지 한눈에 보기 쉽기 때문이다.

데이터 셋을 정의할 때는, 여러개의 데이터를 하나로* 묶을 수 있고, 한 API당 하나의 데이터만**을 조회하게 할 수 있다.

MkWeb에서는 한 API당 하나의 데이터만을 조회하게 했는데, 이미 MkWeb에서 지원하는 다른 SQL Method에서 여러 데이터를 하나로 묶은 결과를 받을 수 있기 때문이었고, 큰 이유는 API는 데이터를 조작하기 위함인데, 여러 데이터를 통합했을 때 발생하는 데이터는 이러한 목적, 즉 이미 조작된 데이터이기 때문에 약간 다르다고 생각했기 때문이다.

*여러개의 데이터를 하나로: 유저정보 + 직장정보

**한 API당 하나의 데이터: 유저정보, 직장정보 각각 따로

데이터 조건들은 모두 Key-Value 쌍을 이루게 하자

RESTful API를 처음 설계할 때, 다음과 같은 설계를 허용할지 엄청 고민했다.

GET /users/name
MkWeb 자체가 범용적인 사용이 가능하기를 바랬고, 그렇기 때문에 발생한 고민이었는데 결국 의미 없는 고민이었다.

해당 요청의 목적은 요청에 대한 응답이 이름만 반환하기를 바랬던 것인데, 이는 사용자가 요청부분에서 담당할게 아니라, 응답하기 위한 데이터 셋에 name만 반환하도록 설계하면 되는 것 이었다.

딴 말이 길었는데, 조건들이 Key-Value 쌍을 이룸으로써 어떤 데이터 셋에 대한. 조회를 할 때, 정확한 데이터만 집을 수 있도록 함이다. 물론 정확한 데이터, Unique하지 않은 필드의 조회에 대해서는 그 결과에서도 겹치는 부분이 많을 것이다. (동명이인과 같이)

그렇지만, 적어도 쌍을 이루게 함으로써 조회의 정확도를 높이고, RESTful API의 설계 난이도를 낮출 수 있다.

API 조건은 모두 Query String으로

URI Segment에 조회하고자 하는 데이터 셋을 특정짓고, 검색 옵션을 모두 Query String에 넣음으로써 우리는 무엇이 데이터와 관련된 조건이고, 응답에 대한 옵션인지를 한눈에 파악할 수 있다.

API 조건은 예를 들어, 응답을 특정 방식으로 정렬하기를 바라거나, 데이터 조회시 20개만 가져오길 바라는 등, 검색하고자 하는 데이터를 특정하지는 않지만, 데이터 조회에 영향을 미치는 부가 기능을 의미한다.

1.Query String처럼 한곳에 데이터 검색을 위한 조건과 옵션을 모두 때려 넣으면, 어느 것이 데이터 조건이고, 부가기능인지 헷갈리기 때문이다.

---

그래서 설계를 어떻게 해야 하는가?

사실 많은 사람들이 설계를 어떻게하는지 보기 위해서 이 페이지에 들어왔을거라 생각한다. 나도 처음 RESTful API를 접했을 때 많은 고민을 했고, 특히 MkWeb의 특징을 살리기 위해 가능한 모든 방안을 수용 가능하도록 만들려고 했다. 하지만 RESTful API인 것 처럼, 그리고 이미 RESTful API의 설계에 대해 고민을 해봤다면, 의미 없는 질문인 것을 알 수 있다.

결국, RESTful API를 설계하기 위한 방법론, 즉 설계도면을 구하고자 하는 것이지, 이미 설계도면을 구한 상태에서 설계를 어떻게 해야하는가 하는 질문은, 건축하기 위한 설계도를 구했으나, 내부 자재는 어떤걸 쓸지, 드릴질은 몇번 할지를 묻는것과 같기 때문이다.

이미 프로그래밍을 할 수 있고, 웹 통신을 할 수 있다면, 위 방법들을 통해 적어도, 낮은 수준의 코딩에서라도 GET Method를 구현할 수 있다고 생각한다.

---