junghyunlyoo restapi - GANGNAM-JAVA/JAVA-STUDY GitHub Wiki

REST API의 의미

• REST(REpresentational State Transfer) '대표적인 상태 전달'

• REST란, "웹에 존재하는 모든 자원(이미지, 동영상, DB 자원)에 고유한 URI를 부여해 활용"하는 것

• 자원을 정의하고 자원에 대한 주소를 지정하는 방법론을 의미

• 따라서 Restful API는 REST 특징을 지키면서 API를 제공하는 것

REST API의 예시

http://uniesta.com/news/view.do?ncd=3421128

이 URI는 Non RESTful URI로, 어떤 자원(resource)인지 쉽게 파악할 수 없다.

http://uniesta.com/boards/1/posts/406

이 URL는 RESTful URI로, 요청하는 자원(resource)이 게시판들 중 첫번째 게시판에 있고, 그 게시판의 글들 중 406번째 글임을 쉽게 알 수 있다.

REST API의 구성

요소	예시
자원(RESOURCE)	URI
행위(Verb)	HTTP METHOD
표현(Representations)	/users GET

REST API의 특징

Stateless

HTTP는 Stateless Protocol 이므로, REST 역시 무상태성을 갖는다. 

즉, HttpSession과 같은 컨텍스트 저장소에 상태정보를 따로 저장하고 관리하지 않고, API 서버는 들어오는 요청만을 단순 처리한다.

세션과 같은 컨텍스트 정보를 신경쓸 필요가 없어 구현이 단순해진다.

Cacheable

HTTP 기존의 웹 표준을 그대로 사용하므로, 웹에서 사용하는 기존의 인프라를 그대로 활용 가능하다.

HTTP 프로토콜 기반의 로드밸런서나, SSL은 물론이고 HTTP가 가진 가장 강력한 특징 중의 하나인 캐싱 기능을 적용 가능하다.

Self-descriptiveness

동사(Method) + 명사(URI) 로 이루어져있어 어떤 메서드에 무슨 행위를 하는지, 문서를 보지 않고도 파악할 수 있다.

REST API의 설계1 - 기본설계

• URI는 자원을 표현해야 한다.(리소스명은 동사보다는 명사를 사용)

• 그리고 슬래시 구분자(/)는 계층 관계를 나타내는데 사용한다.

ex1) http://restapi.example.com/houses/apartments 

ex2) http://restapi.example.com/animals/mammals/whales

• 분명한 URI를 만들어 통신을 해야 하기 때문에 혼동을 주지 않도록 URI의 마지막에는 슬래시(/)를 사용하지 않는다.

• URI에 포함되는 모든 글자는 리소스의 유일한 식별자로 사용되어야 한다.

• URI에 대문자 사용은 피하도록 해야 한다. (대소문자에 따라 다른 리소스로 인식하게 되기 때문)

• URI를 쉽게 읽고 해석하기 위해 불가피하게 긴 URI를 사용하게 된다면, 하이픈을 사용해 가독성을 높일 수 있다.

(_은 URI에 사용하지 않는다.)

• 메시지 바디 내용의 포맷을 나타내기 위한 파일 확장자를 URI 안에 포함시키지 않는다. 대신 Accept header를 사용한다.

ex) GET /members/soccer/345/photo HTTP/1.1 Host: restapi.example.com Accept: image/jpg

• 자원에 대한 행위는 HTTP Method(GET, POST, PUT, DELETE 등)으로 표현

REST API의 설계2 - 리소스 간의 관계 표현

• REST 리소스 간에는 연관 관계가 있을 수 있고, 이런 경우 다음과 같이 표현한다.

/리소스명/리소스ID/관계가 있는 다른 리소스명

ex) GET : /users/{userid}/devices (일반적으로 소유 ‘has’의 관계를 표현할 때)

• 관계명이 복잡하다면 이를 서브 리소스에 명시적으로 표현한다.

ex) GET : /users/{userid}/likes/devices (사용자가 좋아하는 디바이스 목록)

REST API의 설계3 - 자원을 표현하는 Colllection과 Document

Collection과 Document에 대해 이해하면 URI 설계가 수월해진다.

Collection과 Document는 URI에 표현되는 리소스를 의미한다.

• Collection -> 문서들의 집합, 객체들의 집합

• Document -> Collection 중 하나의 특정 객체

http:// restapi.example.com/sports/soccer

    Collection : sports

    Document : soccer

http:// restapi.example.com/sports/soccer/players/13
    
    Collection : sports, players

    Document : soccer, 13번 player

이 두개의 예로 보면 알 수 있듯, Collection은 복수로 사용하고 있다.

좀 더 직관적인 REST API를 위해서, 리소스가 단수인지, 복수인지 정확히 표현하는 것이 좋다.

REST API의 설계의 잘못된 예

x	o
GET /members/delete/1	DELETE /members/1
GET /members/show/1	GET /members/1
GET /members/insert/2	POST /members/2