1) REST / RESTful API
💡 REST(Representational State Transfer)란?
- 웹 애플리케이션을 개발하기 위한 아케텍처 스타일 중 하나로 클라이언트와 서버 간의 통신 방식을 규정한 것이다.
- 해당 통신 방식은 HTTP 프로토콜을 기반으로 하며 자원, 행위, 표현 세 가지 요소로 구성된다.
💡 REST API(Representational State Transfer)란?
- REST 아키텍처 스타일에 따라 구성한 API를 의미한다.
💡 RESTful API(Representational State Transfer)란?
- HTTP를 위한 아케텍처 스타일 중 하나로 REST의 원칙을 따르는 웹 서비스를 구현하며 개발하는 방식이다.
- 클라이언트와 서버 간 자원을 주고받을 때 일괄적인 방식을 제공하며 이를 통해 서버와 클라이언트의 역할을 명확하게 분리하고 서로 독립적으로 개발할 수 있게 된다.
💡 REST API와 RESTful API의 차이점은?
- REST API는 REST 아케텍처 스타일을 따르는 API이며 RESTful API는 REST API를 제공하는 웹 서비스를 의미한다.
- RESTful API는 자원을 URL로 표현하고 HTTP Method를 이용해 해당 자원에 대해 CRUD 작업을 수행하며 리소스와 행위를 명시적으로 분리하여 사용함으로써 URL만 보고도 어떤 동작을 수행하는지 알 수 있도록 구성한 것을 의미한다.
2) RESTful API Annotation
1. 설정 관련 Annotation
| Annotation | 설명 | 비고 |
|---|---|---|
| @SpringBootApplication | - 스프링 부트 애플리케이션의 시작점을 나타내는 어노테이션입니다. | |
| @Controller | - HTTP 요청을 처리하는 컨트롤러 클래스를 정의하는 어노테이션입니다. | Spring MVC 뷰를 반환하는데 사용됩니다. |
| @RestController | - RESTful 웹 서비스를 위한 컨트롤러를 정의하는 어노테이션입니다. | RESTful 웹 서비스의 JSON, XML 등의 응답을 반환하는 데 사용됩니다. |
💡 @Controller와 @RestController의 차이
- @Controller는 일반적으로 HTTP 요청을 처리하고 뷰를 반환하는 데 사용된다.
- @RestController는 HTTP 요청에 대한 RESTful 웹 서비스의 JSON, XML 등의 응답을 반환하는 데 사용된다.
2. 행위 Annotation
| Annotation | HTTP | Method 역할 | 비고(예시) |
|---|---|---|---|
| @GetMapping | GET | 클라이언트가 리소스를 조회할 때 사용 | @GetMapping(value="/users") |
| @PostMapping | POST | 클라이언트가 리소스를 생성할 때 사용 | @PostMapping(value="/users") |
| @PutMapping | PUT | 클라이언트가 리소스를 갱신할 때 사용 | @PutMapping(value="/users") |
| @PatchMapping | PATCH | 클라이언트가 리소스 일부를 갱신할 때 사용 | @PatchMapping(value="/users") |
| @DeleteMapping | DELETE | 클라이언트가 리소스를 삭제할 때 사용 | @DeleteMapping(value="/users") |
| @RequestMapping | ALL | 요청 메서드(GET, POST, PUT, DELETE 등)와 URL 매핑을 함께 지정할 수 있다. | @RequestMapping(value="/users", method=RequestMethod.GET) |
💡 @RequestMapping과 @XXXMapping 사용
- 간단한 HTTP 요청에 대해서는 @XXXMapping을 사용하는 것이 코드 가독성과 유지보수성을 높일 수 있다. 하지만 여러 개의 HTTP 요청 메서드에 대해 하나의 메서드로 처리해야 하는 경우는 @RequestMapping을 사용해야 한다.
3. 표현 Annotation
| Annotation | 설명 | 예시 |
|---|---|---|
| @PathVariable | ‘URL 경로의 일부’를 매개변수로 전달받는 어노테이션 | @GetMapping("/users/{id}") public ResponseEntity getUserById(@PathVariable Long id) {} |
| @RequestParam | ‘HTTP 요청 파라미터’를 매개변수로 전달받는 어노테이션 | @GetMapping("/users") public ResponseEntity getAllUsers(@RequestParam("age") int age) {} |
| @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) { } |
💡 @RequestParam과 @PathVariable의 차이점
- @RequestParam 어노테이션은 HTTP 요청 파라미터를 메소드의 매개변수와 바인딩한다.
- @PathVariable 어노테이션은 URL 경로 변수를 메소드 매개변수와 바인딩한다.
클라이언트에서 API로 데이터를 전송하는 방식으로는 GET 방식과 POST 방식이 있다.
| 구분 | GET 방식 | POST 방식 |
|---|---|---|
| 전송 데이터 | URL 끝에 파라미터를 붙여서 서버에 요청을 보내는 방식 | HTTP Body에 담아서 서버에 요청을 보내는 방식 |
| 전송 데이터 크기 제한 | 데이터의 양에 제한 있음 | 데이터의 양에 제한 없음 |
| 캐싱 가능 여부 | 가능 | 불가능 |
| 보안 | 데이터 노출 가능성 있음 | 데이터 노출 가능성 낮음 |
| 사용 예시 | 검색어 전송, 페이지 요청 | 로그인, 회원가입, 게시글 작성 |
💡 캐싱이란
- 이전에 요청한 데이터를 저장해 두었다가 다음 요청 시에 바로 제공한다. 이를 통해 네트워크 대역폭을 절약하고, 서버의 부하를 줄일 수 있다.
2) RESTful API의 제약조건
1. 클라이언트-서버 아키텍처
RESTful API는 클라이언트와 서버 간의 엄격한 분리와 독립성을 유지해야 한다. 이를통해 각각의 역할이 분명하게 구분되어 서로에게 영향을 미치지 않는 장점을 가진다.
2. 상태 없음(Stateless)
RESTful API는 상태를 관리하지 않는다. 클라이언트의 요청에 따라 서버가 응답을 반환하며 이때 클라이언트의 상태나 세션 정보를 서버에서 관리하지 않는다. 이를 통해 서버의 확장성이 높아지고 클라이언트와 서버 간의 의존성이 낮아지는 장점을 가진다.
3. 캐시 가능(Cacheable)
RESTful API는 캐시를 사용할 수 있어야 한다. 서버의 응답이 캐시 가능하다면 클라이언트는 서버에 요청하여 응답을 받는 대신 캐시에서 바로 응답을 받을 수 있다.
4. 계층 구조(Layered System)
RESTful API는 계층구조로 구성되어야 한다. 이를 통해 서버와 클라이언트 간의 미들웨어를 추가하여 보안, 로드밸런싱, 공유캐시 등의 기능을 추가할 수 있다.
5. 인터페이스 일관성(Uniform Interface)
RESTful API는 인터페이스 일관성을 유지해야 한다. 이를 통해 서버와 클라이언트 간의 상호작용이 단순화되고 의존성이 낮아지는 장점을 가진다.
6. 자체 표현성(Self-descriptiveness)
RESTful API는 자체 표현성을 가지고 있어야 한다. 이를 통해 클라이언트는 서버로부터 받은 응답을 해석하여 처리할 수 있으며 서버는 클라이언트의 요청을 이해하고 처리할 수 있다.
3) RESTful API 설계
💡 RESTful API 설계 과정
1. 자원(Resource)을 정의
2. 행위(HTTP Method)를 정의
3. 표현(Representation)을 정의
4. 상태 코드(Status Code)를 정의
5. 구성 예시
6. API 문서화를 정의
1. 자원
웹 상에 존재하는 데이터나 정보와 같은 모든 것을 의미한다. 사용자, 게시글, 댓글, 이미지 등이 모두 자원이 될 수 있다.
자원의 이름 구성은 동사가 아닌 명사를 사용하는 것을 권장한다.
2. 행위
HTTP Method를 이용한 자원에 대한 행위(조회, 생성, 수정, 삭제)를 의미한다.
| HTTP Method | 행위 | 설명 | 예스 |
|---|---|---|---|
| GET | 자원을 조회 | URI로 지정된 정보를 검색합니다. | 사용자 정보 조회: GET /users/{user_id} |
| POST | 자원을 생성 | URI로 지정된 위치에 새로운 자원을 생성합니다. | 사용자 정보 생성: POST /users |
| PUT | 자원을 수정 | URI로 지정된 위치의 자원을 갱신합니다. | 사용자 정보 수정: PUT /users/{user_id} |
| DELETE | 자원을 삭제 | URI로 지정된 위치의 자원을 삭제합니다. | 사용자 정보 삭제: DELETE /users/{user_id} |
| PATCH | 자원 일부를 수정 | URL로 지정된 위치의 리소스의 일부를 수정하는데 사용이 됩니다. | 사용자 이메일 수정 : PATCH /users/{user_id} |
3. 표현
RESTful에서 클라이언트와 서버 간의 데이터 통신을 위해 주고받는 데이터 형식(JSON, XML, HTML)을 의미한다.
| 분류 | JSON(JavaScript Object Notation) | XML(Extensible Markup Language) | HTML(HyperText Mark-up Language) |
|---|---|---|---|
| 문법 | 가볍고 간결하며 쉽게 읽고 쓸 수 있음 | JSON과 비교해 더 많은 데이터를 필요로하며 상세함 | 데이터 교환을 위한 것이 아니라 웹 페이지 렌더링을 위해 설계됨 |
| 가독성 | 읽고 구문 분석하기 쉽고 복잡한 데이터 구조와 배열을 지원함 | 읽고 구문 분석하기 쉽고 복잡한 데이터 구조와 스키마 유효성 검사를 지원함 | 읽고 구문 분석하기 쉽고 기본 데이터 구조와 링크를 지원함 |
| 유연성 | 쉽게 확장하고 사용자 정의할 수 있으며 대부분의 프로그래밍 언어를 지원함 | 이름 공간과 사용자 정의 태그를 지원하지만 확장하는 데 더 많은 노력이 필요함 | 제한된 유연성으로 복잡한 데이터 교환에는 적합하지 않음 |
| 인기도 | 웹 개발, 모바일 앱 및 API에서 널리 사용됨 | 기업 응용 프로그램 및 레거시 시스템에서 널리 사용됨 | 웹 개발에서 널리 사용됨, 그러나 API에는 권장하지 않음 |
4. 상태 코드
RESTful API에서는 HTTP 상태코드를 사용하여 클라이언트에게 요청의 성공 또는 실패를 알려준다.
상태코드는 3자리 숫자로 표현되며 각각의 숫자는 특정한 의미를 가지고 있다.
| 상태코드 | 상태 정보 | 의미 |
|---|---|---|
| 1xx | Informational | 요청이 수신되었으며 처리가 계속됨을 의미합니다. |
| 2xx | Success | 요청이 성공적으로 처리되었음을 의미합니다. |
| 3xx | Redirection | 요청이 완료되기 위해 추가 작업이 필요함을 의미합니다. |
| 4xx | Client Error | 클라이언트 오류로 인해 요청이 실패함을 의미합니다. |
| 5xx | Server Error | 서버 오류로 인해 요청이 실패함을 의미합니다. |
5. 구성 예시
| 자원 : Endpoint | 행위 : HTTP Method | 표현 : 데이터 전송 방식 | 상태 코드 | 설명 | 구성 예시 |
|---|---|---|---|---|---|
| user | GET | GET 전송방식, parameter or URL 경로 | 성공 시 HttpStatus.OK 반환 | 사용자를 조회하는 API입니다. | GET /user/{userId} |
| user | POST | POST 전송방식, JSON 데이터 전송 | 성공 시 HttpStatus.OK 반환 | 사용자를 등록하는 API입니다. | POST |
| /user | |||||
| user | PUT | POST 전송방식, JSON 데이터 전송 | 성공 시 HttpStatus.OK 반환 | 사용자를 수정하는 API입니다 | PUT |
| /user | |||||
| user | DELETE | POST 전송방식, JSON 데이터 전송 | 성공 시 HttpStatus.OK 반환 | 사용자를 삭제하는 API입니다 | DELETE |
| /user |
6. API 문서화
RESTful API를 사용하는 클라이언트 개발자나 다른 개발자들이 API를 쉽게 이해하고 사용할 수 있도록 문서화가 필요하다.
API 문서는 API URL, 자원, 행위, 표현, 상태코드, 응답 형태 등을 상세하게 기술해야 한다.
- API Endpoint 정의하기
💡 API Endpoint란
- 클라이언트가 서버에게 요청을 보내어 통신을 하는 URL을 의미한다. “https://example.com/users”에서 users는 엔드포인트를 의미하며 엔드포인트는 HTTP Method(GET, POST, PUT, DELETE 등)와 함께 사용된다.
| 고려 사항 | 설명 |
|---|---|
| URL 구조 | 일관성 있는 URL 구조를 유지해야 합니다. |
| HTTP Method | 각 Endpoint에 대해 지원하는 HTTP Method(GET, POST, PUT, DELETE 등)을 정의해야 합니다. |
| Request와 Response 포맷 | Request와 Response의 데이터 형식(JSON, XML, CSV 등)을 정의해야 합니다. |
- API Endpoint 문서화
API Endpoint의 기능과 사용 방법에 대해서 문서를 구성한다.
| 번호 | 문서화 포함 내용 |
|---|---|
| 1 | Endpoint의 URL과 HTTP Method |
| 2 | Endpoint의 기능과 목적 |
| 3 | 요청(Request)과 응답(Response)의 데이터 형식 |
| 4 | Request와 Response의 필수/선택적 매개변수 및 예시 |
| 5 | 에러 메시지와 상태 코드 |
