REST API를 이용한 Web APIs design

REST API가 뭐에요? API가 뭐에요? Web API가 뭐에요? 등의 질문은 본인 경험상 회사 기술 면접뿐만 아니라, 어디가서 본인을 개발자라고 소개한다면 간혹 받을 수 있는 질문인 것 같다.
그런데 실무에서 매일 개발 유지 보수하면서도, 막상 질문을 받으면 썩 만족스럽게 답변을 하지 못하는 본인을 심심찮게 발견하곤 했다. 따라서 이번 포스팅은 어디가서 해당 질문을 갑자기 받더라도 명확하고 간결하게 대답하기 위한 본인만의 cheet sheet이다.

---

API
Application Programming Interface에요, 라고 답변하면 이제 막 기술 면접 준비한 신입 티가 팍팍 날 것 같지 않은가. 원하는 결과를 얻기 위해서 사용자에게 제공되는 버튼 정도로 설명한다면 사전적 의미 및 실사용 사례에서 벗어나지 않고 통용될 것으로 생각된다. 사용 방법에 맞게만 버튼을 누른다면 당신은 원하는 결과를 얻게 될 것이다. 예를 들어 편지를 쓰고 봉투에 넣어 정해진 약식에 맞게 수신자, 발신자의 정보를 입력하여 우체국통에 우편을 넣으면 우체국이 알아서 우편을 잘발송을 해주는 것 처럼 말이다. 그 사이에 일어나는 자세한 일에 대해선 사용자가 알필요가 없다. 사용자가 뒷단의 자세한 사항에 대해서 알필요가 없다는 사실은 뒤에서 설명할 REST API 규격을 위해 지켜야할 요소 중에 하나이기도 하다.

개발 실무에서 말하는 API는 그 의미의 범위가 다소 넓긴 한데, 예를 들어 특정 모듈에 구현된 함수를 API라고 부르거나, 플랫폼에서 제공하는 개발자 도구인 SDK tools를 API로 부르는 사람도 보았다. 이러나 저러나 사용자가 원하는 결과를 얻게 해주기 위해 제공된 도구임에는 틀림 없으니 대충 알아서 적당히들 이해하고 넘어가는 것 같다. 

Web API 
원하는 결과를 얻기 위해서 사용자가 호출할 수 있는 버튼 문장 앞에 '브라우저에서' 라는 한 단어만 더 추가하면 된다. 즉, 브라우저 (흔히들 클라이언트 라고 칭한다) 에서 서버 측으로 부터 원하는 결과를 얻기 위해 사용하는 버튼, 전문용어로 바꿔말해 인터페이스라고 생각하면 된다. 

REST API (Representational State Transfer API)
따라서 Web API란 결국 Client와 Server 사이의 통신 방법에 대한 규격, 즉 약속이라고도 볼 수 있다. 참고로 규격, 약속, 아키텍처 이 셋은 결국 사실 같은 말이다. 아키텍처는 규격을 의미하고 규격은 곧 약속이기 때문이다. 이후 부터는 친숙하게 표현하기 위해 약속이란 단어로 통일하겠다.

출처: https://iq.opengenus.org/rpc-vs-rest/

이 통신 방법에 대한 약속에는 여러가지가 있을 수 있다. 예를 들어 A와 B가 대화를 할 때는 수어로만 한다던가 또는 편지를 써서만 대화를 주고 받는다던가 말이다. 그와 마찬가지로 Web API에서 Client와 Server가 통신하는 방법에는 여러가지가 있을 수 있고, REST API 는 그 중 하나일 뿐이다. 그 외 RPC도 있으니 REST와 RPC의 차이점에 대해 궁금하면 여기를 참고 바란다.
흔히들 말하는 Restful 하다는 것의 의미는, 별게 아니라 REST API 통신 방법에대한 약속을 어기지 않고 잘지켰다 정도 그 이상 그 이하도 아니다.

실무에서는 주로 REST한 Client와 Server간의 통신을 구현하기 위한 네트워크 프로토콜로서 HTTP을 사용한다. FTP, Websocket 등을 사용하여 RESTful 한 API pattern을 설계 및 구현할 수도 있다. websocket을 이용해서도 REST API를 구현할 수 있을까? 문득 궁금하여 찾아보았던 적이 있는데 궁금하면 아래 링크를 참고 바란다.
- Rest Over Websocket

Rest Over Websocket

- SwaggerSocket

다시 본론으로 돌아와서, 그렇다면 RESTful 하기 위해 지켜야 할 약속들이 뭐가 있는지 알 필요가 있다.
이름에서 그 힌트가 조금 있긴 하다. Representational State Transfer, 즉 표현적인 상태 전송이란 뜻이다. REST API라고 불리기 위해선, 아래 6가지 사항을 준수해야한다.

1. Statelessness. 하나의 요청을 처리하기 위해선 그 모든 정보가 들어가 있어야 한단 것이다. 즉, 서로 다른 요청간 대한 정보를 서버에서는 모르는 것이다. Statelessness를 보완하기 위해서 나온 개념에는 Cookie, Session 등이 있다. 
2. Client-Server. Client와 Server 구조로 두 entity의 역할이 명확하게 구분되어 있어야 한단 것이다.
3. Cacheable. Server로 부터 응답받은 데이터는 client side에 cacheable해야한단 것이다.
4. Layered System. Client는 서버가 명확히 누구인지, 어떤 계층을 가지는지 등의 자세한 정보를 모르고도 통신할 수 있어야 한단 것이다. 
5. Uniform Interface. 아래에서 좀 더 자세히 다루도록 하겠다.
6. Code on demand. 필요하다면 Client에서 실행할 코드를 서버에 보내서 처리할 수도 있어야 한단 것이다. 이 부분이 아직 명확히 이해되진 않는데, SSR이 이에 대한 예시가 아닐까 싶다. 

보통 1, 3은 HTTP를 사용하면 어플리케이션에서 별다른 구현없이 얻을 수 있긴하다.

5번의 Uniform Interface에는 4가지가 있다.

1. Resource identification in requests. request URL 에서 resource에 대한 식별자. 즉, what에 해당한다.
2. Resource manipulation through representations.  원하는 resource에 대한 행위. 즉, How에 해당한다.
3. Self-descriptive messages. 서버로 부터 받은 메세지를 어떻게 처리해야하는지 표시 해줘야 한단 것이다. Header에 추가하는 Contents-Type: application/json과 같은 것이 이에 해당한다.
4. Hypermedia as the engine of application state (HATEOAS). Server가 응답해준 데이터를 가지고 Client가 더 요청할 수 있는 URL을 link라는 정보로서 모두 응답해줘야 한단 것인데, 이렇게 하려면 API 설계시 유의해야하고 복잡도가 올라가기 때문에 많은 경우 생략하곤 한다. HATEOAS를 지킨 대표적인 Open API에는 Github API가 있다. 궁금하다면 링크를 참고해보면 이해할 수 있을 것이다.

REST API에서는 CRUD를 구현해야한다. 보통 HTTP를 사용하여 구현하기 때문에 HTTP 를 예시로 들면 각각 기능들은 HTTP의 method에 대응할 수 있다.

Create: http의 post method에 대응
Read: http의 get method에 대응
Update: http의 put method에 대응
Delete: http의 delete method에 대응

마지막으로 Uniform Interface의 1,2 번 요구사항 대한 보충 설명을 위해 좋은 예시와 나쁜 예시를 들어보고 글을 마치겠다.

1번. Resource identification in requests
나쁜 예시) GET /post/1/tags
좋은 예시) GET /tags?postId=1

2번. Resource manipulation through representations
나쁜 예시) GET /posts/getPosts
좋은 예시) get /posts