[Knowledge] REST, REST API

REST

Representational State Transfer

주로 웹을 설계하기 위한 아키텍처 스타일

웹의 장점을 최대한 활용하기 위해서 고안되었다.

• 자원(Resource): URI을 통해 각 자원을 명확하게 식별(URI는 자원의 상태나 행위를 표현하면 안된다.)
• 행위(Verb): 각 자원에 대한 동작(생성, 읽기, 수정, 삭제)은 HTTP Method(GET, POST, PUT, DELETE 등)를 이용해 명시
• 표현(Represetation): 자원의 상태는 XML, JSON 등 다양한 방식으로 표현되어 전송될 수 있다. URI가 식별하는 자원을 조작

 

제약 조건

• Client - Server 구조: API를 호출하는 Client와 API를 제공하는 Server구조로 되어 있다.
• Stateless: 자원은 독립적이다. 지금 사용자가 어떠한 상태에서 호출했는지는 영향을 주지 않도록 설계
• Cacheable: 서버 응답에 캐시 관련 정보가 포함되어 클라이언트/중간 서버에서 캐싱이 가능함
• 일관된 인터페이스: 일관적인 URI, 표준 HTTP 메서드 사용 등 인터페이스가 통일
• 계층 구조(Layered System): 서버와 클라이언트 사이에 여러 계층을 둘 수 있어 보안, 인증, 로드 밸런싱에 유리

 

REST API

REST 아키텍처 스타일을 정확히 구현한 API 설계

현재 정말 RESTful 하게 구현된 API만으로 구성된 Client - Server 구조는 거의 없다.

REST의 정의를 정확하게 따르는 API 구현은 쉽지 않다.

 

특징

• 자원을 URI로 명확하게 표현하고 HTTP Method로 행위를 구분
• CRUD 작업(Create, Read, Update, Delete)을 명확하게 구분하여 처리

 

설계 규칙

명사 사용

URI에는 일반적으로 동사가 아닌 명사를 사용해서 자원을 표현한다.

/users, /products O

/getUsers X

 

복수형 사용

컬렉션(리스트 등)을 나타낼 때는 복수형 명사를 사용

/users O

 

계층 관계는 슬래시(/) 사용

URI의 각 / 는 자원 간 계층 관계를 표현

/users/123/posts O

 

맨 끝에 슬래시(/) 사용하지 않음

URI 경로 마지막에는 슬래시(/)를 붙이지 않음

/users O

/users/ X

 

소문자 사용

URI는 소문자만 작성(대문자는 혼동)

 

언더바(_)대신 하이픈(-) 사용

가독성을 위해 URI 안의 단어 연결은 -(하이픈) 사용

/game-manager O

 

파일 확장자 표기 금지

리소스를 나타낼 때, 파일 확장자는 포함하지 않는다.

/user/123 O

/users/123.json X

 

자원 식별 고유값(ID) 포함

특정 자원을 식별해야 할 때, URI에 고유한 ID를 포함합니다.

/users/123 O

 

필터링 정렬은 쿼리 파라미터 사용

/products?type=food&sort=name, asc O

/products/namesortedasc X