REST API 와 URI 설계

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

 

특징

1. client, server

client와 server가 독립적으로 분리 되어 있어야 한다.

 

2. Stateless

요청에 대해서 client의 상태를 서버에 저장하지 않는다.

 

3. Cache

client는 서버의 응답(response)를 Cache(임시저장) 할 수 있어야 한다.

client가 Cache를 통해 response를 재사용! 할 수 있어야 하고, 이를 통해 서버의 부하(오버헤드)를 낮춘다.

(서버에서도 캐싱해서 부하를 낮추기도한다. ex) redis cache같은?)

 

4. 계층화된 시스템 ( Layered System)

server와 client 사이에 방화벽, Gateway, Proxy같은 다양한 계층 형태로 구성할 수 있고 이를 확장할 수 있다

 

5. 인터페이스 일관성

일터페이스 일관성을 지키고. 아키텍쳐를 작은 단위로 분리해 클라, 서버가 독립적으로 개선될 수 있어야한다.

• 자원의 식별
   웹 기반 REST 에서는 리소스 접근할 때 URI를 사용
   https://foo.co.kr/user/100
   Resource: user
   식별자: 100 
   100번째 유저라는 것을 식별할 수 있어야함
  
  
• 메세지를 통해 리소스 조작
  HTML, XML, JSON, TEXT 등으로 데이터를 전달 가능하다. 어떤 타입인지 알려주기 위해
  HTTP Header의 Content-type으로 테이터 타입 지정할 수 있음.
  메시지 형태로 데이터를 주고받아야하며 data를 전체로 주고받지 말아야 함.  특정 API 스펙을 공유해 클라이언트 서버가 독립적으로!
• 자기 서술적 메세지
  요청 데이터가 어떻게 처리 되는지 충분한 데이터를 포함할 수 있어야 함.
  Http기반의 REST에선 Http Method와 Header정보, 그리고 URI에 포함되는 정보로 표현할 수 있다. 그 외에 담지 못한 정보들은 URI의 메세지를 통해 표현해야 한다.
  
  

이런 조건들을 잘 갖춘 경우를 REST ful하다고 하고 이를 REST API라고 한다.

 

---

URI과 URL 

* URI ( Uniform Resource Identifier ) 

인터넷에서 특정 자원을 나타내는 주소 값. 해당 값을 유일. 

Request:  https://www.udemy.co.kr/reousrce/sample/1

Response:  study.pdf

 

* URL (Uniform Resource Locator)

인터넷 상에서 자원, 특정 파일이 어디에 위치하는 지 식별하는 주소

Request: https://www.udemy.co.kr/study.pdf 

 

URL주소 자체가 특정 서버의 특정 디렉토리의 위치한 특정 파일

따라서 URL은 URI의 하위개념

 

 

 

 

URI 설계 원칙

* RFC-3986을 따라서 설계원칙을 세움

 

• 슬래시 구분자는 계층 관계를 나타내는 데 사용
  https://hyeokjin-store/category/pants
  
  
• URI 마지막에는 / 포함하지 않음
  https://hyeokjin-store/category/pants/
  
  
• 하이픈은 URI가독성을 높이는 데 사용. 2단어 이상일때 카멜케이스말고 하이픈으로!
  https://hyeokjin-store/my-point
  
  
• 밑줄 (_) 은 사용하지 말 것
  https://hyeokjin-store/my_point
  
  
  
• URI 경로는 소문자로
  https://hyeokjin-store/my/point (o)
  https://hyeokjin-store/MY/point (x)
  
  
  
• 파일 확장자는 URI에 포함하지 않음
  https://hyeokjin-store/usage.jsp (x)
• 프로그래밍 언어에 의존적인 확장자를 사용하지 않음
  https://hyeokjin-store/usage.go (x)
  
  
• 구현에 의존적인 경로를 사용하지 않음
  https://hyeokjin-store/servlet/classes/java/usage (x)
• 세션 ID는 포함하지 않음
  https://hyeokjin-store/my?session-id=dke132 (x)
  
  
• 프로그래밍 언어의 Method명을 이용하지 않음 (introduce메소드를 실행시려라 라는..)
  https://hyeokjin-store/my?action=introduce
  
• 명사에 단수형 보다 복수형으로 사용. 컬렉션에 대한 표현은 복수로 사용함
  https://hyeokjin-store/pants/short/reds
  
  
• 컨트롤러 이름으로는 동사를 사용
  https://hyeokjin-store/pants/re-order
  
• 경로 부분 중 변하는 부분은 유일한 값으로 대체함
  pants/shorts/{shorts-category-id}/product/{product-id}
  pants/shorts/2/product/12033
  
  
  
  
• CROD 기능을 URI에 사용하지 않음
  /user/100/READ (x)
  
  
• URI Query Parameter 디자인
  URI쿼리 부븐으로 컬렉션 결과에 대해 필터링 할 수 있음
  pants/short?szise=32
  
  
  
• URI 쿼리는 컬렉션의 결과를 페이지로 구분하여 나타내는 데 사용
  pants/short?szise=32&page=0&sort=asc