I. REST란 무엇인가?
- Representational State Transfer(REST)는 API 작동 방식에 대한 조건을 부과하는 소프트웨어 아키텍처이다.
- REST 기반 아키텍처를 사용하여 대규모 고성능 통신을 안정적으로 지원할 수 있다.
- API 설계 시 REST 아키텍처의 스타일을 따르는 API를
REST API라고 함. RESTful API는 REST 아키텍처를 충실하게 따라 구현된 API라고 함.
II. REST 아키텍처 스타일
1. 균일한 인터페이스 (Uniform Interface)
- 서버가 표준 형식으로 정보를 전송한다는 것을 말하며, 형식이 지정된 리소스를 표현이라 한다.
- URI로 지정한 리소스에 대해 조작을 통일되고 한정적인 인터페이스로 수행하는 스타일을 말한다.
균일한 인터페이스의 4가지 아키텍처 제약 조건
- 자원을 객체로 보고 자원에 대한 고유한 식별자로
URI를 사용해야 한다.- 표현을 통해 자원에 대한 조작을 하며, 특정 시점에 자원이 지니고있는 상태를 특정 형식으로 표현화하고 클라이언트와 서버 간에 전송한다.
- 클라이언트와 서버를 오가는 메세지는 중개자들(컴포넌트)에게 자기 자신을 설명할 수 있어야 한다.
(요청, 응답에 대한 처리방법 등)- 하이퍼미디어를 통해 앱 상태 변경할 수 있는 인터페이스를 제공해야 한다.
2. 무상태 (Stateless)
- 작업을 위한 상태정보를 따로 저장하고 관리하지 않는다.
- 별도로 세션이나 쿠키 정보를 관리하지 않고, 서버는 들어온 요청만 처리한다.
- 서버에서 불필요한 정보를 관리하지 않아 서비스의 자유도가 높고 구현이 단순해진다.
3. 계층화 시스템 (Layered System)
- 클라이언트 요청을 이행하기 위해 함께 작동하는 보안, 어플리케이션, 비즈니스 로직과 같은 여러 계층으로 여러 서버에서 실행되도록 설계할 수 있다.
4. 캐시 가능성 (Cache)
- HTTP가 가진 캐싱 기능의 적용이 가능하다.
5. Code-On-Demand
- 요청을 받으면 서버에서 클라이언트로 바로 실행 가능한 코드를 전송하여 클라이언트 기능을 확장할 수 있는 기능
6. Client - Server 구조
- 서버와 클라이언트의 역할이 구분되어 있어 클라이언트와 서버에서 개발해야 할 내용이 명확해지고 서로간 의존성이 줄어들게 된다.
III. RESTful API 작동 방식
- 클라이언트가 API 문서에 따라 서버가 이해하는 방식으로 요청 형식을 지정하여 요청 전송
- 서버가 해당 요청을 수행할 수 있는 권한이 클라이언트에 있는지 확인
- 서버가 요청을 수신하고 내부적으로 처리
- 서버가 클라이언트에 응답을 반환하고, 응답에는 요청 처리 결과에 대한 여부도 포함된다.
IV. REST API 디자인 가이드
REST API 설계 시 가장 중요한 항목
- URI는 정보의 자원을 이름으로 구분하여 표현한다.
- 자원의 상태를 주고 받는 행위는 HTTP Method로 표현한다.
- GET, POST, PUT, DELETE 등
- REST API 중심 규칙
1)URI는 정보의 자원을 표현해야 한다.
2) 리소스명은 동사보다는 명사를 사용한다.
3) 자원에 대한 행위는 HTTP Method로 표현한다.
4) URI는 자원을 표현하는데 중점을 두어야 하며 Method가 들어가면 안된다.
유저 정보 가져오는 URI
GET /user/delete/1 (x)
GET /user/1 (o)
유저 추가 등록
GET /user/insert/1 (x) - GET 메서드는 리소스 생성에 맞지 않다.
POST /user/2 (o)- URI는 자원을 표현하는데에 집중하고 행위에 대한 정의는 HTTP Method를 통해 하는 것이 REST한 API를 설계하는 중심 규칙이다.
HTTP Method 역할
- POST
- 해당 URI를 요청하면 리소스를 생성
- body에 리소스를 실어서 호스트 요청을 보냄
- GET
- 해당 리소스를 조회하고 해당 도큐먼트에 대한 자세한 정보를 가져옴
- PUT
- 해당 리소스를 업데이트
- 요청을 보낼 때 보내지 않은 정보는 null로 업데이트
- DELETE
- 해당 리소스를 삭제
- 요청을 보내지 않은 데이터는 기존 데이터 유지
-
URI (Uniform Resouce Identifiers)
URI 네이밍 규칙
- 슬래시(/) 구분자는 계층 관계를 나타낼 때 사용
- 마지막 문자로 슬래시(/)를 포함하지 않는다.
https://restapi.example.com/person/male/ (x)
https://restapi.example.com/person/male (o)- (-)하이픈을 사용하여 URI 가독성을 높여준다.
- (_)밑줄은 사용하지 않는다.
- 소문자를 사용한다.
https://example.com/korea/SeoulSi (x)
https://example.com/korea/seoul_si (x)
https://example.com/korea/seoul-si (o)- 파일 확장자는 URI에 포함시키지 않는다.
- 메세지 바디에 파일 확장자를 URI에 포함시키지 않고 Accept header를 사용한다.
https://example.com/korea/seoul-si/city.png (x)
GET / korea/seoul-si/city HTTP/1.1 Host: restapi.example.com Accept: image/png- 자원의 필터링을 위해 새로운 API를 만들지 않고 Query string을 이용한다.
- Query string : 주소?속성=값&속성=값&...
- 특정 주소로 접근할 때 페이지에 대한 옵션으로 활용
/person/maleSortByAgeAscending (x)
/person?type=male&sort=age,asc (o)- 리소스 간의 관계 표현 방법
- REST 리소스 간에 연관 관계가 있는 경우
/리소스명/리소스 ID/관계가 있는 다른 리소스명
GET : /users/{userid}/devices (일반적으로 소유의 관계를 표현할 때)- 관계 명이 복잡한 경우 서브 리소스에 명시적 표현 방법
GET : /users/{userid}/likes/devices (관계 명이 애매하거나 구체적 표현이 필요할 때)V. RESTful API 상태 코드 및 응답
- 상태 코드
- 200 : 일반 성공 응답
- 201 : POST 메서드 성공 응답
- 400 : 잘못된 요청
- 404 : 리소스를 찾을 수 없음
- 응답
- 메세지 본문 : 리소스 표현히 포함되며 XML 또는 JSON 형식으로 정보를 요청할 수 있음
- 헤더 : 응답에 대한 헤더 또는 메타데이터를 포함
.
.
.
.
.
.
.
.
.
습관을 들이도록 노력하자!