REST API (Representational State Transfer API)

<!-- 본 포스팅은 개인공부를 위한 용도로 잘못된 정보가 있을 수 있습니다. 오류 발견시 댓글 환영합니다. -->

REST API (Representational State Transfer API)

---

1. REST API

---

REST API는 Representational State Transfer API의 약자로 2000년 Roy Fielding의 박사 학위 논문에서 처음 등장하였다.

REST는 대규모 네트워크 시스템을 위한 아키텍처 형식으로 구성은 HTTP URI와 HTTP Method로 이루어져있다.

URI는 정보의 자원을 표현해야 하며, 자원에 대한 행위는 HTTP Method(GET, POST, PUT, DELETE 등)으로 표현한다.

최근 Open API등의 서비스 제공에서 많이 사용되어지며, 스프링MVC의 3버전부터 @ResponseBody를 이용하여 지원한다.

간단 용어정리

1) @RestController

컨트롤러의 설계 목적 자체가 REST방식으로 데이터를 서비스하기 위한 용도에 사용한다. 따라서 JSP를 뷰로 이용하지 않고, 만들어지는 데이터를 그대로 사용하기 위한 용도이다.

@RestController는 @Controller와 @ResponseBody를 합친역할을 수행하며, Spring 4.0부터 사용할 수 있다.

컨트롤러 클래스에 @RestController 어노테이션을 사용함으로써 @ResponseBody 어노테이션을 요청 매핑 메소드에 추가할 필요가 없다.

2) @ResponseBody

객체 → JSON. 자바 객체를 HTTP 응답 몸체로 매핑하는 역할을 한다.

3) @RequestBody

JSON → 객체. HTTP 요청의 몸체를 자바 객체로 매핑하는 역할을 한다.

4) @ResponseEntity

전체 HTTP 응답을 나타낸다.

@ResponseBody + HTTP상태코드. 데이터에 응답코드까지 전달한 것이다.

5) JSON (JavaScript Object Notation)

경량의 DATA-교환 방식으로 JavaScript에서 파생되어 객체를 표현하는 표기법으로 쓰이지만, 언어 독립형 데이터 포맷으로 수많은 프로그래밍 언어에서 이용가능하다.

예제1. @RestController이 적용된 컨트롤러의 모든 메소드는 @ResponseBody가 생략된다.

@RestController @RequestMapping("/sample") public class SampleController {   @RequestMapping("/sendVO")   public SampleVO sendVO() {     SampleVO vo = new SampleVO();     vo.setFirstName("홍만");     vo.setLastName("최");     return vo;   }

예제2. @RequestBody 위치와 @RestController사용으로 인해 생략된 @ResponseBody(ResponseEntity 앞)

@RestController @RequestMapping("/replies") public class ReplyController {   @RequestMapping(value = "", method = RequestMethod.POST)   public ResponseEntity<String> register(@RequestBody ReplyVO vo) {       entity = new ResponseEntity<String>("SUCCESS", HttpStatus.OK);     return entity;   }

2. REST API 특징

---

1) Client-Server

REST 서버는 API를 제공하며, 클라이언트는 사용자 인증이나 컨텍스트 등을 직접 관리하는 구조이다.

각각의 역할이 확실히 구분되어 클라이언트와 서버에서 개발해야할 내용이 명확해지고 서로간 의존성이 줄어든다.

2) 무상태성 (Stateless Server)

작업을 위한 상태정보를 따로 저장하고 관리하지 않는다. 세션 정보나 쿠키정보를 별도로 저장하고, 관리하지 않아서 API서버는 들어오는 요청만을 단순히 처리한다. 따라서 서비스의 자유도가 높아지며, 불필요한 정보를 관리하지 않아 구현이 단순해진다.

3) 캐시(Cache)

HTTP라는 기존 웹표준을 그대로 사용하여, 웹에서 사용하는 기존 인프라를 그대로 활용할 수 있다. 따라서 HTTP가 가진 캐싱기능을 적용할 수 있다.

4) 유니폼 인터페이스 (Uniform Interface)

URI로 지정한 리소스에 대한 조작을 통일되고 한정적인 인터페이스로 수행할 수 있는 구조이다.

5) 계층형 구조 (Layered System)

REST 서버는 다중 계층으로 구성될 수 있으며, 보안, 로드밸런싱, 암호화 계층을 추가해 구조상 유연성을 둘 수 있다.

6) 자체표현구조(Self-descriptiveness)

REST API 메시지만 보고 쉽게 이해할 수 있는 자체 표현 구조이다. 인터페이스의 유연성에 제약을 가하여 전체적인 아키텍쳐가 간결하다.

3. REST API 디자인 규칙

---

1) URI는 정보의 자원을 표현한다.

2) 자원에 대한 행위는 HTTP Method (POST, GET, PUT, DELETE)로 표현한다.

ex) REST를 이용하여 돼지를 표현하려면?

Resource	POST (Create)	GET (Read)	PUT/PATCH (Update)	DELETE (Delete)
/pigs	돼지 추가	돼지들의 목록보기	새로운 돼지 리스트로 교체	돼지 전체 삭제
/pigs/1234	에러방생	FOO 보기	FOO정보 업데이트 없을 시 에러발생	FOO 삭제

GET 작업은 항등(Idenponent) 이며, 그외 나머지 작업들은 부수작업 (Side effect)이 필요하다.

3) Naming

URL에 동사를 사용하지 않는다. HTTP Method를 동사 대용으로 사용한다.

대신 명사를 사용하도록 한다. 단수보다는 복수형 명사를 사용한다.

ex) /savePigs → /pigs - POST

4. HTTP 응답 상태 코드

---

클라이언트(웹 브라우저)에서 서버에 Request를 하면, 서버에서는 Response를 보내준다. 아래는 응답코드를 정리해보았다.

Response Code

1xx : 정보(Informational). 리퀘스트를 받고, 처리중인 상태

2xx : 성공(Success). 리퀘스트를 정상적으로 처리함

3xx : 리디렉션(Redirection). 리쉐스트 완료를 위해 추가 동작이 필요한 상태

4xx : 클라이언트 오류(Client Error). 클라이언트 요청을 처리할 수 없어 오류 발생

5xx : 서버 오류(Server Error). 서버에서 처리를 하지 못하여 오류 발생

200번대 응답(Response) : 성공(Success)

200	OK	요청 정상 처리.
204	No Content	요청을 정상 처리하였으나, 돌려줄 리소스가 없는 상태. 응답에 어떠한 EntityBody도 포함하지 않으며, 서버에서 처리 후, 클라이언트에 정보를 보낼 필요가 없는 경우에 사용한다.
206	Partial Content	Range가 지정된 요청인 경우, 지정된 범위만큼의 요청을 받았다는 것을 알려준다.

300번대 응답(Response) : 리디렉션(Redirection)

301	Moved Permanently	요청된 리소스에는 새로운 URI가 지정되어 있기 때문에, 이후 새 URI를 사용해야 한다는 것을 나타낸다. (영구적인 URI 변경)
302	Found	요청된 리소스에는 새로운 URI가 지정되어 있기 때문에, 이후 새 URI를 사용해야 한다는 것을 나타낸다. (일시적인 URI 이동)
303	See Other	요청에 대한 리소스는 다른 URI에 있기 때문에 GET 메서드를 사용해서 얻어야 한다는 것을 나타낸다. 리디렉션 위치를 GET 메서드를 통해 얻어야 한다.
304	Not Modified	요청한 리소스가 마지막 요청 이후 변경된 적이 없기 때문에 기존 클라이언트의 로컬 캐시 리소스를 사용하도록 알려준다. 300번대로 분류되어 있지만, 리디렉션과는 관계없는 처리를 함.
307	Temporary Redirect	임시로 페이지를 리다이렉트 한다.

400번대 응답(Response) : 리디렉션(Redirection)

400	Bad Request	클라이언트의 요청 구문이 잘못된 상태
401	Unauthorized	권한없는 컨텐츠를 요청했을때 인증을 거치라는 의미로 사용하며, 요청한 인증이 실패했을 경우에도 응답으로 전송한다.
403	Forbidden	접근 금지 응답. Directory Listing 요청 및 관리자 페이지 접근 등을 차단하는 경우 서버는 EntityBody에 접근 거부에 대한 이유를 명시하여 보낼 수 있다.
404	Not Found	클라이언트가 요청한 리소스가 서버에 없는 상태
405	Method Not Allowed	허용되지 않는 HTTP 메서드를 사용

500번대 응답(Response) : 리디렉션(Redirection)

500	Internal Server Error	서버에서 클라이언트 요청을 처리 중에 에러 발생
503	Service Unavailable	서버가 일시적으로 요청을 처리할 수 없음. 과부하 상태 혹은 점검으로 인해 요청을 처리할 수 없다.
504	Gateway Timeout	서버를 통하는 게이트웨이에 문제가 발생하여 시간초과 발생
505	HTTP Version Not Supported	서버를 통하는 게이트웨이에 문제가 발생하여 시간초과