REST

네트워크 리소스를 정의하고 처리하는 방법을 설명하는 일련의 원칙을 기반으로 하는 아키텍처

REpresentational State Transfer 의 약자로 의역하면 자원의 표현으로 상태를 전달하는 것 정도로 해석할 수 있다.

REST 구성요소

• 자원(Resource)
  URI를 통해서 자원을 구분하고 호출한다.

• 행위(Verb)
  HTTP Method를 통해서 자원에 대해 어떠한 행위(CRUD)를 할지 지정한다.

• 표현(Representation)
  HTTP 응답코드를 통해서 자원의 전달 상태를 나타내며, 주로 XML 또는 JSON으로 데이터를 주고 받는다.

REST API

REST 기반으로 설계된 API

쉽게 말해서, API를 호출하는 HTTP 요청 정보를 보고 어떠한 자원을 다루는지, 그 자원에 대해 어떠한 행위를 하는지 알 수 있도록 설계된 API인 것이다.

REST API 설계 규칙

1. URI는 자원을 표현해야 한다.

회원 조회 API

GET /read-members  (X)
GET /members       (O)

• 행위에 대한 표현이 들어가서는 안된다.
• 자원의 이름은 동사보다는 명사를 사용해야 한다.

2. 행위에 대한 표현은 HTTP Method를 활용한다.

회원 등록 API

GET /create-member  (X)
POST /member        (O)

Method	역할
GET	리소스 조회 (READ)
POST	리소스 생성 (CREATE)
PUT	리소스 수정 (UPDATE)
DELETE	리소스 삭제 (DELETE)

3. URI 경로는 대문자보다는 소문자를 사용한다.

member/STOPH   (X)
member/stoph   (O)

대소문자에 따라 다른 자원으로 인식하게 되기 때문에 가급적 소문자를 사용하도록 해야한다.

4. 계층 관계는 슬래시(/)를 구분자로 하여 나타낸다.

/members/stoph    (멤버 중에서 stoph라는 이름을 가진 멤버 조회)
/posts/202926     (게시글 중에서 202926라는 글 번호를 가진 게시글 조회)

5. 마지막 문자로 슬래시(/)는 사용하지 않는다.

/members/stoph/  (X)
/members/stoph   (O)

URI에 포함되는 모든 글자는 자원의 유일한 식별자로 사용되어야 하므로 명확하게 자원을 표현해야 한다.

6. 언더스코어( _ )보다는 하이픈( - )을 활용한다.

posts/my_rest_api   (X)
posts/my-rest-api   (O)

불가피하게 긴 URI 경로를 사용하게 된다면 가독성을 위해서 언더스코어보다는 하이픈을 활용한다.

7. 파일 확장자는 URI에 포함시키지 않는다.

posts/202926/thumbnail.png   (X)
posts/202926/thumbnail       (O)

파일 확장자는 Accept-header를 사용하여 표현한다.

자원 간의 관계를 표현하는 방법

자원 간에는 연관 관계가 있을 수 있다.
예를 들어, 특정 회원이 좋아요를 누른 게시글들을 조회하는 API를 설계해보자.

GET /members/stoph/likes

• members - 회원들 중에서
• stoph - stoph라는 이름을 가진 회원이
• likes - 좋아요를 누른 게시글들

여기서 눈 여겨 볼 것은 자원을 표현할 때 복수형과 단수형을 활용해서 관계를 나타내고 있다는 점이다.
REST에서는 복수형을 Collection, 단수형을 Document 라고 표현한다.

Collection과 Document
Document는 하나의 문서 또는 하나의 객체,
Collection은 문서들의 집합 또는 객체들의 집합이라고 생각하면 된다.
즉, Document의 집합이 Collection이 되는 것이다.
Collection이나 Document 둘 다 자원으로써 URI에 표현이 가능하다.

참고

NHN Cloud Meetup! - REST API 제대로 알고 사용하기