RESTFUL API 설계

[1] REST 란?

웹 애플리케이션을 개발하기 위한 아키텍처 스타일 중 하나로 클라이언트와 서버 간의 통신 방식을 규정한 것 입니다. 

해당 통신 방식은 HTTP 프로토콜을 기반으로 하며 자원(resource), 행위(HTTP method), 표현(representation) 세 가지 요소로 구성됩니다. 

 

[2] REST API 란?

REST 아키텍처 스타일에 따라 구성한 API를 의미합니다.

 

[3] RESTful API 란?

REST의 원칙을 따르는 웹 서비스를 구현하는 방식이며 웹 서비스를 개발하는 방식입니다. 

클라이언트-서버 아키텍처를 따르고 클라이언트와 서버 간의 분리와 독립성을 유지해야 합니다. 이를 통해 각각의 역할이 분명하게 구분되어 서로에게 영향을 미치지 않는 장점을 가집니다. 

 

3-1. RESTful API를 설계하는 과정

 

1. 자원(Resource)을 정의합니다. 

endpoint로 url을 설계합니다. 

 

2. 행위(HTTP Method)를 정의합니다.

Restful API의 행위는 HTTP Method를 이용한 자원에 대한 행위(조회, 생성, 수정, 삭제)를 의미합니다. 

GET, POST, PUT, DELETE를 지정합니다.

 

3. 표현(Representation)을 정의를 합니다.

클라이언트에서 서버로 전송하는 전송 방식(GET, POST)과 전송 데이터 형식(JSON)을 지정합니다.

 

4. 상태 코드(Status Code)를 정의를 정의합니다.

 

5. API 문서화를 정의합니다.

 

 

3-2. JSON 데이터 형식의 전송 방식 

Annotation	설명	예시
@PathVariable	‘URL 경로의 일부’를 매개변수로 전달받는 어노테이션	@GetMapping("/users/{id}")public ResponseEntity getUserById(@PathVariable Long id) {}
@RequestParam	‘HTTP 요청 파라미터’를 매개변수로 전달받는 어노테이션	@GetMapping("/users")public ResponseEntity<list> getAllUsers(@RequestParam("age") int age) {}</list
@RequestBody	HTTP 요청의 ‘본문(body)’을 매개변수로 전달받는 어노테이션	@PostMapping("/user")public ResponseEntity createUser(@RequestBody User user) { }
@ResponseBody	HTTP 응답의 본문(body)을 생성하는 메소드에 적용하는 어노테이션	@GetMapping("/data")public @ResponseBody Map<string, object=""> getData() { }</string,>
@ResponseStatus	HTTP 응답의 상태 코드를 지정하는 어노테이션	@GetMapping("/users/{id}")@ResponseStatus(HttpStatus.NOT_FOUND)public void getUserById(@PathVariable Long id) { }

 

3-3. 상태 코드를 정의합니다.

클라이언트의 데이터 전송이 완료/실패 처리 되었을 때 서버에서 클라이언트로 전달하는 상태 코드를 정의합니다. 

상태 코드	상태 정보	의미
400	Bad Request	클라이언트 요청이 잘못되었음을 의미합니다.
401	Unauthorized	클라이언트가 인증되지 않았음을 의미합니다.
403	Forbidden	클라이언트가 요청한 리소스에 접근하 권한이 없음을 의미합니다.
404	Not Found	요청한 리소스를 찾을 수 없음을 의미합니다.
500	Internal Server Error	서버에서 오류가 발생하여 요청을 처리할 수 없음을 의미합니다.

 

401과 403 차이 정리

• 401
  • 상태: 클라이언트가 인증되지 않았거나 유효한 인증 정보가 부족하여 요청이 거부됨
  • 예시: 사용자가 로그인되지 않은 경우
• 403 
  • 상태: 서버가 해당 요청을 이해했지만, 권한이 없어 요청이 거부됨
  • 예시: 사용자가 권한이 없는 요청을 하는 경