TSL : 2020-04-27

요약

최근 며칠 간 soloLearn으로 RESTful API에 대해 공부했다. 처음에는 용어가 생소해서 어려운 개념처럼 느껴지고 공부를 시작하기 두려웠었다. 그런데 막상 공부를 시작하고 나니, 그동안 내가 프로그래밍 하면서 무의식적으로 이미 RESTful API의 여러 규칙들을 지키고 있었다는 것을 깨달았다.

분명 복습하지 않고, 또 내 코드에 적용하지 않고 지나가면 까먹을 것이 분명하기에, 복습할 겸 TSL에 정리해보려고 한다.

---

RESTful API란?

REST는 Representational State Transfer의 약자이다. (참고로 API는 Application Programming Interface의 약자이다) 약자가 무엇의 줄임말인지 알아도 도대체 그것이 무엇인지 감이 안 온다. 그냥 한국말로 풀어 설명하는 것이 이해가 빠를 것이다.

내가 이해하기로는 RESTful API라는 개념은 web에서 client와 server간의 통신이 이뤄질 때 지키면 좋은 규칙들이다. 말 그대로 지키면 좋은 것이고, 그 규칙을 준수하라고 강요하는 이는 없다. 단지 이 공통적인 룰들을 무시하고 맘대로 코딩하면 다른 사람과의 협업이 매우 어려울 것이라는 것 뿐.

client와 server간에 통신이 무엇인지 조금 더 설명하자면 이렇다. client측은 정보 열람을 요청하거나, 수정을 요구하는 측이고, server는 정보들을 가지고 있으면서 client의 요청에 따라 적절한 서비스를 제공한다.(요청한 정보를 JSON 또는 XML형식으로 건네주거나, 수정 또는 제거하는 등) 그렇다면 client와 server간에는 서로 공통의 언어가 있어서 요청과 서비스를 주고 받을 수 있을 것이다. 그 공통의 언어가 바로 URI(Uniform Resource Identifier)이다. 잉? URL은 인터넷 주소라는 걸 알겠는데 URI라고? 오타인가? 라고 나도 처음에 생각했다. 찾아보니 우리가 아는 URL은 URI의 자식 요소 같은 개념, 즉 URI가 좀 더 포괄적인 개념이라고 한다. 요즘은 URL보다 URI를 많이 쓴다고 한다. 어쨌든, client와 server는 URI를 통해 소통한다.

HTTP란?

RESTful API를 이해하기 위해서는 HTTP를 어느정도 이해하고 있는 것이 좋다. HTTP는 Hypertext Transfer Protocol의 약자이다. protocol이라는 것은 규칙을 말한다. 직역하면 hypertext를 이리저리 주고 받을 때 지켜야 할 규칙들인 셈이다. 그럼 hypertext는 또 무슨 개념인지 의문이 생긴다. hypertext의 hyper라는 단어는 "초월적"이라는 의미를 가지고 있다. 초월적 텍스트? 이해가 잘 안 된다. 그래서 구글링을 해봤다.

결국 나무위키의 좋은 예시를 찾아 냈다. 일반적인 텍스트는 A쪽에서 B쪽으로 넘어가려면 그 사이의 페이지들을 거쳐서 가야 한다. 책을 한 장씩 넘겨야지만 B쪽을 펼 수 있다. (책갈피가 있다면 다르겠지만 설명을 위한 예시이므로 예외는 논외로 하자)

반면, HYPER텍스트는 다르다. 예시로 우리가 웹사이트를 돌아다니다가 HOME 버튼을 누르면 어떻게 되는지 생각해보자. 그동안 우리가 방문했던 모든 페이지를 거꾸로 돌려서 다시 HOME 화면으로 돌아가는가? 아니다. 그냥 바로 HOME으로 이동한다. 초월적이라는 의미가 바로 이 현상을 말한다. 위와 같이 책으로 비유하자면 A쪽에서 B쪽으로 가기 위해서는 손가락을 딱 튕기면 바로 쪽수가 바뀌는 마법같은 현상이 되겠다.

실제로 우리가 HTTP를 어디서 볼 수 있는지 궁금해진다.

답은 간단하다. 아무 인터넷 페이지에 가서 개발자 도구를 열고 Network 탭으로 들어가서 새로고침을 해보자. 그러면 어떤 리스트들이 쫙 뜰 것이다. 그 중 아무거나 하나를 클릭해보면 위와 같이 해당 요청과 응답에 대한 각종 정보들이 나올 것이다.

그 . 래 . 서 우리가 왜 HTTP를 이야기 하고 있나? RESTful API는 client와 server간의 통신과 관련이 있다고 했다. 또 하나의 특징은 RESTful API가 주로 HTTP web API에 쓰인다는 점이다. client는 server에 무언가를 요청할 때 HTTP 규칙과 형식에 따라 요청한다. HTTP request에는 server에 보내는 정보들(URI, GET방식인지 POST방식인지 등등)이 있다. server는 그 request를 받아서 해석하고, 어떤 request에 대한 응답인지와 그 응답을 보낸다.

HTTP 메세지 속에는 크게 3가지의 정보가 들어간다. 이 것이 무엇에 대한 메세지인지, 각종 header들, 그리고 건네주어야 할 데이터가 있다면 그 데이터를 담고 있는 body가 그것이다.

HTTP에 대한 이야기는 이정도로 하고 다시 RESTful API로 돌아가보자.

RESTful API의 구조

REST에서는 오고 가는 데이터를 resource라고 부른다. 권장되는 resource의 구조가 있고, 그걸 따라 하는 것이 좋다. Singleton은 한 번에 하나의 사건만 일어나는 것이다. 예를 들어 특정 유저의 이름을 가져오는 것은 Singleton이다. 단수형로 쓴다.(user, name etc...) 반면, Collection은 이름 그대로 여러 정보들이 들어가있는 것을 말한다. 복수형으로 쓴다.(uesrs, names, songs etc...)

/users ==> Collection
/users/{userId} ==> Singleton
만약 userId 아래 skills라는 Collection이 있으면
/users/{userId}/skills ==> Collection
/users/{userId}/skills/{skill-name} ==> Singleton

이름 정하기

코딩에서 변수명을 잘 정하는 것이 중요하듯, RESTful API에서도 resource들의 이름을 정하는 것은 매우 중요하다. 직관적으로 읽기 쉽고, 통상적으로 사용하는 규칙들을 잘 적용해야 한다.

resource는 기본적으로 명사의 형태를 가진다. 명사는 하위 구조를 가질 수 있지만 동사는 어렵기 때문이다.(예를 들어 "동물"은 개, 고양이 등을 하위 구조로 가질 수 있지만, "먹다"라는 동사는 힘들다)

resource에는 4가지 타입이 있다.

1. Document
   • Document는 단수형의 개념이다. 이후에 나올 collection 안의 하나의 정보 조각이라고 생각하면 이해하기 쉽다.
   • Document 아래에는 또 다른 collection이 있을 수 있다. 예를 들어 멤버 중 한 명의 출석체크를 생각하면 쉽다. 한 명의 멤버까지만 생각하면 Document지만 그 멤버의 출석체크는 리스트일테니까 collection이 된다.
   • ex) http://api/swimming.com/members/{id}
2. Collection
   • Collection은 쉽게 말하면 위의 Document들이 들어있는 폴더 같은 개념이다. 복수형으로 쓴다. Collection에서는 Document를 추가하거나 삭제할 수 있다.
   • ex) http://api/swimmingkiim.com/members http://api/swimmingkiim.com/members/{id}/skills
3. Store
   • Store는 collection과 비슷한데 다른 점은 user가 언제 데이터를 추가하거나 제거할 것인지 결정할 수 있다는 점이다. 음악 사이트의 플레이리스트를 생각하면 쉽다.
   • ex) http://api.swimmingkiim.com/members/{id}/memos
4. Controller
   • Controller는 위의 세가지와 달리 동사의 형태이다. 마치 함수처럼 인자를 받아서 결과를 return한다.
   • ex) http://api.swimmingkiim.com/members/{id}/playlists/play

작명규칙

흔히 사용하는 작명규칙이 있다.

1. 요소들을 구분할 때는 /를 사용한다.
2. URI 맨 끝을 /로 끝내지 않는다.
3. 띄어쓰기를 필요로 할 때는 -을 쓴다. _도 가능하지만 환경에 따라 잘 보이지 않을 수도 있다.
4. 대문자말고 소문자를 사용한다.
5. 파일 확장자를 쓰지 않는다.
6. URI collection을 필터한 결과로 받고 싶을 떄는 query를 사용한다.
7. CRUD(create, read, update, delete)의 이름을 사용하지 않는다. 대신 GET, POST, PUT, DELETE 방식을 잘 활용하여 구분하라.

GET 방식

GET 방식은 server로부터 데이터를 읽어올 때사용한다. 이 방식은 단순이 있는 데이터를 읽어오는 것 뿐이어서 resource에 어떠한 변화도 주지 않는다. 나아가 똑같은 URI 요청을 반복해도, 중간에 POST, PUT, DELETE 등이 오지 않는 이상, 매번 똑같은 결과를 던져준다. 이러한 성질을 idempotent(멱등법칙 : 여러번 수행해도 결과가 달라지지 않는 성질)적이라고 한다.

요청 받은 정보가 resource에 있으면 HTTP response는 요청한 데이터와 함께 200(OK)을 던져준다. resource를 찾지 못했다면 HTTP response는 404(NOT FOUND)를 던져준다. 만약 GET request가 알맞게 쓰여있지 않았다면 400(BAD REQUEST)를 보내준다.

POST 방식

POST 방식은 정보를 추가할 때 사용된다. REST에서는 collection에 새로운 데이터를 추가할 때 사용된다.

성공적으로 정보가 추가 되었다면 HTTP response는 201(Created) 코드를 던져준다.

POST 방식은 non-idempotent하다.

PUT 방식

PUT 방식은 기존에 있는 정보를 수정할 때 사용된다. PUT 방식으로 수정을 요청 받은 데이터를 찾을 수 없는 경우에는 새로 만들 수 있는 경우도 있다.

없던 정보가 새로 만들어졌을 경우에는 HTTP 201코드, 성공적으로 수정한 경우에는 200 또는 204(No content) 코드를 보내준다.

DELETE 방식

DELETE 방식은 특정 정보를 삭제하고 싶을 때 사용한다.

성공적으로 정보가 삭제되었다면 HTTP 200(OK), 또는 204(No content)를 보내준다.

논쟁적인 부분이지만 DELETE도 idempotent(멱등법칙 : 여러번 수행해도 결과가 달라지지 않는 성질)하다고 본다. 맨처음 호출되어서 정보가 삭제되고 난 후에는 똑같은 요청이 왔을 떄 404(NOT FOUND)를 보내주지만 resource의 state는 변하지 않았다고 보는 것이다.

---

---

간단하게 내가 배운 것을 정리해 보았다. 미루고 미루다 당일에 포스트를 다 완성하지 못 했지만ㅠㅠ

soloLearn에는 흥미로운 주제들이 많이 있다. 다음에는 자료구조나 디자인 패턴에 대해 공부해보고 싶다.