TIL22 - 일관성 있는 웹 서비스 인터페이스 설계를 위한 REST API 디자인 규칙

✔️Intro

백엔드 개발자 채용공고에서 빠질 수 없는 문구가 있습니다 바로 "RESTful API 기반 설계"입니다. 저 역시 위코드에서 프로젝트를 하기 위해 RESTful API에 대해 배웠습니다. 저희 회사의 경우, 일부 URL이 RESTful API의 규칙에 조금 맞지 않는 게 있어서 수정이 필요한 상황이었으며 회사 사수분이 RESTful API에 대한 지식을 넓힐 수 있는 방법으로 이 책을 추천해주셨습니다. 

 

✔️기본배경

제가 위코드에서 배웠던 RESTful API 규칙은 크게 아래 다섯가지입니다.

 

• url은 페이지 기준이 아닌 자원 기준으로 작성한다.
• 동사로 작성하지 않는다.
• HTTP Method를 정의하기 때문에 url에 add, search 같은 걸 쓰지 않는다.
• 검색 키워드는 body를 통해 전달하지 않고 Query String을 사용한다.
• 언더바를 사용하지 않고 '-'를 사용한다.

하지만 책을 읽으며 내가 몰랐던 부분이 많다는 걸 다시 한 번 깨닫게 되었습니다.

✔️URL URN URI

RESTful API를 배울 때 가장 저를 헷갈리게 했던 것들입니다.

우선, 이것들의 차이를 알고 가는 것이 RESTful API의 이해에 도움이 됩니다.

 

리소스 : HTTP에서 요청한 대상

 

URN : 리소스의 이름
URL : 리소스의 위치
URI : 리소스의 ID

 

URI는 인터넷에 있는 자원을 나타내는 유일한 주소입니다.
URL은 어떻게 리소스를 얻을 것이고 어디에서 가져와야하는지 명시하는 URI입니다.
URN은 리소스를 어떻게 접근할 것인지 명시하지 않고 경로와 리소스 자체를 특정하는 것을 목표로하는 URI입니다.

 

http://127.0.0.1:8000/users 를 예시로 들어보겠습니다.

 

URN : 127.0.0.1:8000/users 

URL : http://127.0.0.1:8000

URI : http://127.0.0.1:8000/users

 

이렇게 되는 것입니다 그리고 

URI를 URN, URL 두 가지 형태로 나타낼 수 있습니다.

✔️What is REST API?

REpresentational State Transfer의 약자로 REST API는 로이 필딩에 의해 창시되었습니다. 의미는 웹상에 존재하는 모든 자원에 고유한 URI를 부여하여 자원에 대한 주소를 지정하는 방법론, 규칙을 말합니다.

✔️그 외 규칙

제가 위에 말한 5가지 규칙 외에 여기서 나온 규칙들에 대해 추가로 작성해보겠습니다. 규칙이 거의 100가지 정도 되는 것 같은데, 일상에서 많이 실수하고 있는 것들만 선별해서 가져오게 되었습니다.

 

1. URI 마지막 문자로 슬래시를 포함하지 않는다
   URI 경로 마지막에 슬래시를 붙이는 건, 혼란을 초래할 수 있습니다. 그러므로 슬래시를 추가하지 않는다고 합니다. 규칙을 엄격하게 적용하지 않은 API들은 클라이언트가 보낸 URI를 마지막에 슬래시가 없는 URI로 리다이렉트하기도 합니다. 즉, 응답코드 301로 한다는 의미입니다. Django에선 APPEND_SLASH = False로 마지막에 슬래시가 오지 않도록 설정할 수 있습니다.
   
   
2. 302는 사용하지 않는다
   리소스를 이동시켰을 때 사용하는 301이나, 303, 307을 이용한다고 합니다. 
   
   
3. 응답코드 204는 바디에 의도적으로 아무것도 포함하지 않을 때 사용한다.
   저는 DELETE 메서드를 사용할 때, 데이터가 없으니 204를 사용해야지라고 막연히 생각했었습니다. 책에서는 REST API가 응답 메시지의 바디에 어떠한 상태 메시지나 표현을 포함해서 보내지 않을 때 사용한다고 합니다. 그리고 보통 DELETE뿐만 아니라 PUT, POST 등에도 사용되는데 GET에도 응답할 수 있다고 합니다. 요청된 리소스는 존재하나 바디에 포함시킬 어떠한 상태 표현도 가지고 있지 않다는 것을 나타낸다고 합니다.
   
   
4. REST API는 구현되는 것이 아니라 설계되어야 한다.
   REST API를 코딩한다는 것은 백엔드 시스템의 리소스에 대한 인터페이스를 구현하는 것입니다. 이 작업은 프레임워크마다 달라지지만 백엔드 시스템의 데이터 모델을 해석하여 웹 지향적인 리소스 모델로 옮기는 코드를 작성하는 핵심 작업은 똑같습니다. 이 때 일관성을 유지하여 클라이언트-서버 처리과정을 고려하여 설계를 하는 것이 형식적이고 틀에 박힌 코드를 대체할 수 있는 방법이라고 합니다.

✔️마치며..

위에 언급한 것처럼 규칙이 굉장히 많았고, 저 역시 이렇게 체계적인 설계였구나라는 걸 깨닫게 되었습니다. 차후에 있을 기능 신규/수정 개발에 대해 EndPoint 설계를 할 일이 있을 때 곰곰히 잘 생각해야겠다고 느꼈습니다.