REST API & URI 설계 원칙 (RFC-3986)

 

REST ( Representational State Transfer : 자원의 상태 전달) - 네트워크 아키텍처이다.

 

 

1. Client와 Server가 서로 독립적으로 분리되어 있어야 합니다.  클라이언트와 서버가 한 곳에 구성되어있다던지, 서로의 정보가 서로 밀접하다면 Rest api를 잘 못 지켰다고 할 수 있습니다.

2. Stateless 해야 합니다. 즉 요청에 대해서 클라이언트의 상태를 서버에 저장하지 않습니다.  즉 서버는 상대를 알지 못해야 합니다.

3. Cache 클라이언트는 서버의 응답을 Cache 할 수 있어야 합니다. 클라이언트가 Cache를 통해서 응답을 재사용할 수 있어야 하며, 이를 통해서 서버의 부하를 낮출 수 있습니다.

4. Layed System 서버와 클라이언트 사이에 방화벽, 게이트웨이, Proxy 등 다양한 계층 형태로 구성이 가능해야 하며, 이를 확장할 수 있어야 합니다. 

5. 인터페이스의 일관성을 지키고, 아키텍처를 단순화시켜 작은 단위로 분리하여, 클라이언트, 서버가 독립적으로 개선될 수 있어야 합니다. 즉 서버가 변경돼도 클라이언트가 변경되더라도 문제가 없어야 합니다.

 

 1) 자원의 식별

 웹 기반 REST에서는 리소스 접근할 때 URI를 사용합니다.

 

https://foo.co.kr/user/100 

 

다음과 같이 서버에 접근했을 때 리소스는 user이고 식별자는 100입니다.

 

 2) 메시지를 통한 리소스 조작

 

Web에서는 다양한 방식으로 데이터를 전달할 수 있습니다.

그중에서 많이 사용하는 방식은 HTML, XML, JSON, TEXT 등이 존재합니다.

이 중에서 어떠한 타입의 데이터인지를 알려주기 위해서 HTTP Header 부분에 content-type을 통해서 데이터의 타입을 지정해 줄 수 있습니다. 

ex) 

content-type : application/json 

 

또한 리소스 조작을 위해서 데이터 전체를 전달하지 않고 , 이를 메시지로 전달합니다. 

즉  한 번 더 추상화시켜 메시지 형태로 전달하게 된다면 서버의 resource 변경으로 클라이언트가 영향을 받지 않을 수 있기 때문입니다. 만약 직접적으로 데이터를 전달하게 된다면 client-server가 독립적으로 확장하지 못하고 종속적이게 될 수 있습니다.

 

 

 3) 자기 서술적 메시지

 

요청하는 데이터가 어떻게 처리되어야 하는지 충분한 데이터를 포함할 수 있어야 한다.

HTTP 기반의 REST에서는 HTTP Method와 Header 정보, 그리고 URI의 포함되는 정보로 표현할 수 있습니다.

 

GET: https://naver.com/user/100 , 사용자의 정보 요청

POST: https://naver.com/user/ , 사용자 정보 생성

PUT: https://naver.com/user/ 사용자 정보 생성 및 수정

DELETE: https://naver.com/user/100 사용자 정보 삭제 

 

사실  HTTP 메서드들은 종류가 다양하지 않기 욱여넣는 느낌이 없잖아 있긴 한데, 그 외에 담지 못한 정보들은 URI 메시지, header를 통하여 표현할 수 있습니다. 

 

 4) 애플리케이션 상태에 대한 엔진으로써 하이퍼 미디어

(협업에서는 잘 사용하지 않는다.)

 왜냐면 클라이언트에 불필요한 정보까지 처리를 해야 하기 때문

 

Rest API를 개발할 때 단순히 Cilent 요청에 대한 데이터만 응답해주는 것이 아닌 관련된 리소에 대한 Link 정보까지 같이 포함되어야 한다.

이 말은 클라이언트가 리소스를 얻기 위해 서버에 요청을 했을 때 서버에서는 해당 리소스에 대한 다양한 정보를 얻을 수 있는 LINK를 첨가해서 응답을 해줘야 한다는 것입니다. 

EX) JSON

{

 user : 100,

 link : [

  userlist : https://exaple.com/userlist,

 ]

}

이렇지 않을까 합니다.

 

6. 자바 애플릿, 자바스크립트, 플래시 등 특정한 기능을 서버로부터 클라이언트가 전달받아 코드를 실행할 수 있어야 한다.

 

 

 

이러한 조건들을 잘 갖춘 경우 REST Ful 하다고 표현하고, 이를 REST API라고 부릅니다.

 

 

 

URI 설계 원칙 

 

developer.mozilla.org/ko/docs/Web/HTTP/Resources_and_specifications

HTTP 리소스와 명세 - HTTP | MDN

위의 하이퍼 링크는 HTTP에서 사용하는 여러 가지 명세들이 존재합니다. 들어가서 한 번씩 읽어보시는 걸 추천드립니다.

 

 

우선 uri는  인터넷에서 특정한 자원을 나타내는 주소 값이고 해당 값은 유일합니다. 주소 값이기 때문에 변경이 가능하며, 요청 시 응답 값은 매번 달라질 수 있습니다.

헷갈리는 url은 인터넷 상에서 자원, 특정한 파일이 어디에 위치하는지 식별하는 주소 입니다.

그렇기 때문에 변경되지 않으면서 url로 요청 시 해당 자원/파일이 서버의 특정 위치에 존재하는지 알 수 있습니다.

url은 uri의 하위 개념입니다.

 

URI의 자원은 범용적인 의미로 사용됩니다. 예를 들어 전자 문서, 이미지, 정보 소스, 자바스크립트 코드 등입니다.

 

1. 슬래시 구분자 (/)는 계층 관계를 나타내는 데 사용합니다.

https://naver.com/category/article/sports/baseball 

 잘 보면 카테고리라는 큰 계층 밑에 전자 기사라는 계층 및에 스포츠 유형이 있고 그 밑에 야구라는 특정 계층이 존재합니다.  가상 주소니까 눌러보시지 마시고 즉 /는 계층관의 관계를 표현할 때 사용합니다.

 

2. URI 마지막 문자로 /는 포함하지 않는다.

https://naver.com/category/article/sports/baseball/ 다음처럼 마지막 문자에 / 가 포함하지 않는 것이 좋습니다.

 

3. 하이픈(-)은 URL 가독성을 높이는 데 사용합니다.

https://naver.com/category/article/sports/baseball-kr

 

한국야구로 계층을 나누어도 되는데 만약 한국야구만 보여주는 페이지라면 다음과 같이 하이픈을 사용해 가독성을 올려줄 수 있습니다. (다시 생각해보니 계층을 나누는 것이 확장성이 있어 보입니다만 예제입니다.)

 

4. 밑줄( _ ) 은 사용하지 않습니다.

 

https://naver.com/category/article/sports/baseball_kr

 

5. URI 경로에는 소문자가 적합합니다. 

6. 파일 확장자는 URI에 포함하지 않습니다. 

 web.jsp 같이 확장자 x

 

7. 프로그래밍 언어에 의존적인 확장자는 사용하지 않습니다.

 web.do처럼 의존적인 확장자

 

8. 구현에 의존적인 경로를 사용하지 않습니다.

 우리 서버는 서블릿으로 만든 건지 servlet을 uri에 포함하지 않습니다.

 

9. 세션 ID를 포함하지 않습니다.

https://naver.com/category/article/sports/baseball_kr?session-id=asdafs

 

10. 프로그래밍 언어의 Method 명을 이용하지 않는다.

https://naver.com/category/article/sports/baseball?action=start

다음처럼 start라는 method를 노출시키지 않습니다.

 

11. 명사에 단수형보다는 복수형을 사용해야 한다. 컬렉션에 대한 표현은 복수로 사용합니다. 

https://naver.com/categories/articles/sports/baseball

 

12. 경로 부분 중 변하는 부분은 유일한 값으로 대체해야 합니다.

https://naver.com/categories/articles/sports/baseball/{baseball-id}

우리는 이걸 Path variable이라고 부릅니다.

 

13. CRUD 기능을 실제로 나타내는 URI에 사용하지 않습니다.

GET : https://naver.com/categories/articles/sports/baseball/{baseball-id}/READ

메서드를 통해서 나타내는 것이 원칙입니다.

 

14. Query Parameter 디자인은 컬렉션 결과에 대해서 필터링을 할 수 있으며, 페이지 구분을 하기 위해 사용합니다.

https://naver.com/categories/articles/sports/baseball?chapter=2&page=0&size=10&sort=desc