REST API #2 - 개념 정리 (2)

(2) 리소스

행위가 되는 대상, 혹은 행위를 하는 대상에 대응이 되는 리소스는 URI를 구성하는 요소 중 하나입니다.

REST URI를 구성할 때 직관적으로 구성하는 것을 통해서 사용자 간 이해도를 높일 수 있습니다. 구성 방식에 있어서 직관성을 높이는 방식이 존재합니다.

 

※ URI, Uniform Resource Identifier은 네트워크 상의 자원을 식별하기 위한 문자열의 구성입니다. URI의 한 형태인 URL, Uniform Resource Locator은 통합 자원 식별자로 인터넷 상의 자원 위치를 표현하는 유일한 주소입니다. https://ansrlm.tistory.com의 경우 https://ansrlm.tistory.com이라는 위치를 나타내고 있기 때문에 URI이며 URL입니다. https://ansrlm.tistory.com/5의 경우는 조금 다릅니다. path parameter로 5라는 숫자가 표현되고 있다면, URL은 https://ansrlm.tistory.com이고, postId에 해당하는 자원의 정보에 도달하기 위해서 5라는 식별자가 필요한 것입니다. 그래서 해당 부분은 URI지만 URL은 아닙니다.

 

1) URL을 길게 만드는 것보다 최대 2~3 depth정도로 구성하는 것이 좋습니다.

 

HTTP GET /categories/:categoryId/sectors/:sectorId/books/:bookId/pages/:pageNumber...

 

위와 같이 (말도 안되는 형태이지만) depth가 깊어질수록 어떤 행위를 하는지 알기가 어려워집니다. 특정 비즈니스 로직 요건에 의해서 해당 URL구성이 필요한 경우를 제외하고, 일반적인 경우 REST API의 장점인 Self-Descriptiveness를 이용하지 않는 anti-pattern이 될 가능성이 높아집니다.

 

2) URI에 리소스명을 사용할 때는 동사보다는 명사를 통해서 구성합니다.

해당 방식은 1, 3과 보다도 최대한 지키는 것이 중요합니다. URL에 동사를 통해서 구성된 요소가 있다면, HTTP Method인 CRUD를 사용하는 것과 중복 작용을 할 뿐 아니라, 해당 메서드와의 방향성이 다르게 보인다면 사용자가 혼란을 느낄 가능성이 높아집니다.

 

HTTP POST /getCategories
HTTP POST /addBaseballCategory

 

해당 방식은 GET method대신 POST method를 사용하는 것으로 혼란을 일으킬 가능성과, POST method를 사용하는 것을 add와 중복 적용을 보이게 됩니다.

 

HTTP GET /categories
HTTP POST /categories

 

HTTP method를 사용하는 것과 동시에, body parameter에 baseball을 표현하는 방식을 통해서 구성하는 것으로 getCategories, addBaseballCategory에서 생길 수 있는 문제점들을 회피할 수 있습니다.

그러나 해당 방식에도, 비즈니스 로직 요건에 의해서 칼같이 지켜지지 않을 수 있습니다. (특정 페이지를 읽음과 동시에 페이지 조회수를 증가시키는 경우가 이에 해당합니다)

 

3) 단수형 명사보다는 복수형 명사를 사용하는 것이 좋습니다.

단수형 명사보다 복수형 명사를 사용하는 것을 통해서 리소스의 관계에 대해서 암시적인 표현이 가능합니다.

 

HTTP GET /categories
HTTP GET /categories/:categoryId
HTTP GET /categories/10

 

line 1에서는 카테고리 리스트에 대한 정보들을 가져오는 것을,

line 2에서는 카테고리 중 특정 카테고리에 대한 정보들을 가져오는 것을 표현할 수 있습니다. 해당 방식을 통해서 categoryId = 10인 경우인 line 3이 10에 대한 정보들을 요청할 수 있습니다.

 

리소스간의 연관관계가 존재할 경우 표현하는 방식을 선택할 수 있습니다. 해당 부분은 상황에 맞게 좋은 처리 방식을 선택하는 것이 필요합니다.

 

1) 리소스 간의 암시적 표현

조금 전에 소개드린 복수형 명사를 통해서 리소스의 관계 표현을 하는 방식과 비슷합니다.

 

HTTP GET /baseballPlayers/:playerId/statistics

 

위와 같은 표현을 통해서 특정 플레이어가 가진 통계치를 가져올 수 있습니다. 해당 방식으로 has / is에 대한 암시적 표현이 가능합니다.

 

2) 리소스 간의 명시적 표현

리소스의 관계 표현이 모호해 질수도 있는 부분에 대해서 명시적으로 표현하는 방식을 사용함으로써 사용자의 이해를 돕습니다.

 

HTTP GET /baseballPlayers/:playerId/mean/statistics

 

URL에 mean을 추가적으로 사용하는 것으로, 만약 전의 URL이 특정 플레이어가 가진 연도별 통계치를 가져왔다면 모든 연도를 합친 평균치를 가져오겠다고 표현할 수 있습니다. (그러나 해당 부분 표현에 있어서 두 표현 모두 연도별인지 바로 이해할 수 없기 때문에 URL의 구성을 더 잘해야 한다고 할 수 있겠습니다)

 

암시적 / 명시적 표현에 있어서 사용자의 이해를 돕고, 간결하게 표현할 수 있는 방법의 조율이 필요합니다. 너무 암시적으로 표현할 경우 이해도가 떨어질 수도 있으며. 너무 명시적으로 표현할 경우 URL이 길어지는 결과를 낳기 때문입니다.

 

(3) 메시지

자바스크립트가 유행하기 전 XML의 형태로 많이 사용했고, 근래에 들어서 사용의 편의성을 위해서 JSON 포맷을 많이 사용하고 있는 메시지는 자신을 어떻게 처리해야 할지에 대한 정보를 포함하고 있습니다. header에 Content-Type: JSON을 기입하는 것으로 response message를 처리할 방법을 전달할 수 있습니다. 해당 방식을 통해서 메시지 body parameter의 포맷을 나타내기 위해서 URI에 포함하는 것을 피할 수 있습니다.

 

HTTP response code와 response body에 에러의 상세 정보에 대해서 명시할 수 있습니다. 에러의 종류, 혹은 성공의 상세 정보에 대해서 명시하는 것이 2xx, 3xx, 4xx, 5xx를 묶어서 200은 성공, 500은 실패와 같이 HTTP response code를 적게 사용하는 것을 대신할 수는 없습니다. 해당 부분의 구현은 REST API 디자인 및 Self-Descriptiveness을 지키지 않는 anti-pattern입니다. 즉, 클라이언트가 올바르지 못한 요청을 보낸 400 error code와 로그인을 하지 않아서 페이지를 열 권한이 없는 401 error code는 구별해야 한다는 것을 의미합니다. 다른 경우로, 403 error code에서 UNAUTHORIZED.ROLE / INVALID.STATUS와 같이 response body에 명시해 에러의 종류를 세분화하는 방식을 통해서 이슈 트레킹을 원활하게 할 수 있습니다.

 

HTTP 응답 코드는 종류가 매우 많기 때문에 저가 서술하기보다는, 위키피디아를 첨부합니다. ko.wikipedia.org/wiki/HTTP_%EC%83%81%ED%83%9C_%EC%BD%94%EB%93%9C

 

 

 

※ 잘못된 부분이나 궁금한 점 댓글로 작성해 주시면 최대한 답변하겠습니다. 읽어주셔서 감사합니다.

※ REST API #3 - Fetch에서 fetch함수에 대한 설명으로 이어집니다.