REST API jwkim2

뒤에 이어질 [Tutorial: serverless-express-aurora](/frameworks/serverless/tutorial-serverless-express-aurora.html)를 위하여 REST API 에 대하여 잠시 설명합니다. 본 포스팅은 차후 API 카테고리로 이전 예정입니다.

REST API란?

REST(REpresentational State Transfer) API: 대의적(대표적) 상태 전달 API
무슨 말인지 모르겠습니다.

HTTP URI(Uniform Resource Identifier)를 통해 자원(Resource)을 명시하고 자원에 대한 행위를 HTTP Method를 통해 정의한다.
마음와 와닫지 않습니다.

2000년도 Roy Fielding의 박사학위 논문에서 최초로 소개 되었고, Roy Fielding은 HTTP의 주요 저자중 한 사람으로 웹의 아키텍처의 우수성에 비해 제대로 사용되어지지 못하는 모습에 안타까워하면 웹의 장점을 최대한 활용할 수 있는 아키텍처로써 REST를 발표했다고 합니다.
어쩌라고? (로이 박사님 죄송 ㅠㅠ)

REST는 거의 20년이나 된 것이기 때문에 자료도 너무 많은데도 불구하고 아직 개념을 제대로 이해하지 못한 분들도 있고, "읽어봐도 뭔 소리인지 잘모르겠다"라고 하는 사람들도 있습니다. 어렴풋이는 대충 알고 있는데 명확하게 설명을 잘 못하는 사람들도 있습니다. 제가 보았을때 공학을 너무 공학적으로 설명한(?) 글들이 많아 내용을 보고도 이해가 잘 되지 않았던것 같습니다.

사실 좋은 글들이 많은데 굳이 같은 내용을 제가 다시 설명하는 것은 큰 의미가 없는 것 같아서 조금 다른 방식으로 접근 해보려고 합니다.(이 블로그는 원래 평범하지 않습니다.)

REST API 의 시작(부제: 전쟁의 서막)

웹 개발자로 일하던 쿡이라는 사람이 있습니다. 쿡은 여러 Third Party 서비스를 한번에 연동하는 서비스를 개발하고 있습니다.

A라는 서비스의 친구 관련 API 를 물어보니, GetFriendInfo 라고 합니다.
B라는 서비스에 물어보니 GetFriends 라고 합니다.
C라는 서비스에 물어보니 GetMyFriendsInfo 라고 합니다.

WTF, 세 업체 친구 리스트를 연동해야 하는데 각각 이름이 다 다릅니다. 이번에는 친구 추가 API 입니다.

A 서비스: AddFriendInfo
B 서비스: AddFriends
C 서비스: AddMySuperUltraLovelyFriendInfo

이런 API 각 서비스별로 120개씩 존재합니다. 쿡은 이베이를 통해 심장약과 칼을 주문합니다.

이번에는 연동을 위해서 어떤 프로토콜을 사용하는지 물어봤습니다.

A 서비스: HTTP/JSON
B 서비스: SOAP/XML
C 서비스: TCP/PACKET

쿡은 이베이를 통해 바로 바주카포를 주문합니다. 6.25때 난리는 난리도 아닙니다.

REST API로 통합

각각의 서비스들마다 API 를 정의하는 방식과 연동 방법이 다르다보니 일일히 각 서비스에 맞춰서 개발을 하느라 시간이 오래 걸리고 생산성이 나지 않습니다. 결국 하고 싶은 것은 데이터를 읽기,추가,수정,삭제 4가지 뿐인데(-그것이 친구 데이터이든 아이템 데이터이든-) 부가적으로 할것이 너무 많습니다.

잘 생각해보니, DB에서 하는 일이라고는 트랜젝션이다 프로시져다 머다해도 결론적으로는 읽기(SELECT),추가(INSERT),수정(UPDATE),삭제(DELETE) 뿐이 없습니다.

잘 생각해보니, HTTP 에서는 GET,POST,PUT,DELETE 의 4가지 Methods 를 지원합니다.(사실 몇개 더 있습니다.)

바로 이거다. 하나의 자원에 대해서 HTTP를 통해서 GET(SELECT), POST(INSERT), PUT(UPDATE), DELETE(DELETE) 를 하자. 그리고 편의를 위해서 무조건 JSON 형태로 주고 받자.

URL GET POST PUT DELETE
service/friends 친구 정보 얻기 친구 추가 친구 정보 수정 친구 삭제
service/items 아이템 정보 얻기 아이템 추가 아이템 정보 수정 아이템 삭제

이것이 바로 REST API 입니다. 물론 쿡 혼자서 각 서비스들에게 API 를 변경하라고 할수는 없지만, 현실에서 각 서비스 제공자든 서비스 소비자든 통합을 원했고 이런 방식으로 표준스럽게 채택하여 사용하기 시작합니다.('표준스럽게라'라고 표현한것은 표준 위원회에서 공식적으로 채택한 내용은 아니나 사람들이 많이 사용하여 표준처럼 사용이 되어왔습니다.)

REST API 란 각기 다른 서비스나 서버-클라이언트 간에 규약입니다. 이름도 방식도 중구난방으로 하면 서로 힘드니 우리 이런 방식으로 통일해서 사용하자 해서 고착화 된 것이 REST API 입니다.

(쿡은 구매한 무기를 모두 환불합니다.)

REST API 설계

위에서 언급한바와 같이 REST API 는 정확한 표준은 아닙니다. 그냥 이런식으로 하자라고 고착화 된 것이다보니 완전히 통일이 되지 않았습니다. 대부분 많이 쓰는 방식이 존재하나 그것이 REST 다 라고 정의하기는 힘듭니다.(REST 스럽게 구현했다고 해서 RESTFul API 라는 표현도 합니다.)

이에 필자가 많은 사람들이 사용하는 방식으로 간단한 REST API를 정의하려고 합니다만 다른 사람도 모두 같은 방식을 쓰는 것은 아니라는 것만 염두해 두시면 됩니다.(실제로 개발에는 REST 보다는 차세대 API 방식인 GraphQL을 사용합니다.)

REST API 필요 개념

REST API 의 URL의 끝에 ID가 붙는지 안붙는지에 따라서 크게 두가지 형태로 나뉩니다.

  • 컬렉션(Collection): 집합(Array) > 유저들, 아이템들, 이벤트들
  • 도큐먼트(Document): 객체 하나(Object) > 유저, 아이템, 이벤트

중첩된 구조일 경우 상위 URL 에 종속적입니다. 다음은 예시입니다.

URL 구분 설명
/users 컬렉션 유저 리스트
/users/111 도큐먼트 유저 번호가 111 인 유저 정보
/users/111/items 컬렉션 유저 번호가 111 인 유저의 모든 아이템 리스트
/users/111/items/123 도큐먼트 유저 번호가 111 인 유저의 아이템중 아이템 번호가 123 인 아이템 하나의 정보

REST API 설계 규칙

  • 소문자, 숫자, -(대시)만 사용: _(언더바 사용안함)
  • 동사보다는 명사를 사용
  • 복수 명사만 사용, 단수 사용 안함
  • 슬래시(/)는 계층 관계
  • Stateless(무상태성): API 자체는 상태를 가지지 않음. Cookie, Session 등을 사용하지 않고 단순이 들어오는 요청값에 의해서만 처리하여 구현이 단순해 짐. 인증은 JWT를 사용하고 상태가 필요한 정보는 DB에 질의 함
예외: 자원이 대상이 아닌 인증등의 행위에 대해서는 동사를 허락하고 POST 방식을 사용(Web Form 과 동일)

HTTP Method

GET POST PUT DELETE
SELECT INSERT UPDATE DELETE
조회 추가 수정 삭제

HTTP 응답 코드

  • 200: 성공
  • 400: 잘못된 요청(파라미터를 잘못 보낸 경우)
  • 403: 권한 없음(유저가 어드민 API를 호출한 경우)
  • 404: 리소스 없음(존재하지 않는 리소스를 요청한 경우)
  • 500: 서버 오류(서버 내부 예외 상황)
Last Updated: 3/20/2019, 9:12:15 AM