RESTful 웹 서비스 개발

전자정부프레임워크에서 RESTful 웹 서비스를 구현하는 방법을 학습합니다. RESTful 웹 서비스는 HTTP 프로토콜을 기반으로 하여 클라이언트와 서버 간 데이터를 주고받는 구조입니다. 이를 통해 보다 간결하고 유연한 API를 설계할 수 있습니다.

---

1. RESTful 웹 서비스 개념

REST (Representational State Transfer)

• REST는 자원을 URL로 표현하고, HTTP 메서드를 사용하여 자원에 대한 CRUD 작업을 수행하는 아키텍처 스타일입니다.
• 주요 HTTP 메서드:
  • GET: 자원 조회
  • POST: 자원 생성
  • PUT: 자원 수정
  • DELETE: 자원 삭제

---

2. RESTful 컨트롤러 작성

RESTful 웹 서비스를 구현하기 위해 @RestController를 사용합니다. 이 어노테이션은 @Controller와 @ResponseBody를 결합한 것으로, JSON 형식의 데이터를 반환합니다.

2-1. 기본 REST API 작성

RestApiController.java

import org.springframework.web.bind.annotation.*;
import java.util.*;

@RestController
@RequestMapping("/api/v1")
public class RestApiController {

    // 자원 조회 (GET)
    @GetMapping("/items")
    public List<String> getItems() {
        return Arrays.asList("Item1", "Item2", "Item3");
    }

    // 자원 생성 (POST)
    @PostMapping("/items")
    public String createItem(@RequestBody String newItem) {
        return "새로운 아이템 생성: " + newItem;
    }

    // 자원 수정 (PUT)
    @PutMapping("/items/{id}")
    public String updateItem(@PathVariable("id") int id, @RequestBody String updatedItem) {
        return "아이템 ID " + id + " 수정됨: " + updatedItem;
    }

    // 자원 삭제 (DELETE)
    @DeleteMapping("/items/{id}")
    public String deleteItem(@PathVariable("id") int id) {
        return "아이템 ID " + id + " 삭제됨";
    }
}

---

3. RESTful API 테스트

3-1. Postman을 이용한 테스트

1. GET 요청
   • URL: http://localhost:8080/api/v1/items
   • 결과: ["Item1", "Item2", "Item3"]
2. POST 요청
   • URL: http://localhost:8080/api/v1/items
   • Body (JSON):

     "NewItem"
     

   • 결과: 새로운 아이템 생성: NewItem
3. PUT 요청
   • URL: http://localhost:8080/api/v1/items/1
   • Body (JSON):

     "UpdatedItem"
     

   • 결과: 아이템 ID 1 수정됨: UpdatedItem
4. DELETE 요청
   • URL: http://localhost:8080/api/v1/items/1
   • 결과: 아이템 ID 1 삭제됨

3-2. 브라우저 테스트

• 브라우저 주소창에서 http://localhost:8080/api/v1/items를 입력하여 GET 요청 결과를 확인합니다.

---

4. RESTful 웹 서비스 구현 시 고려 사항

4-1. URI 설계 원칙

1. 자원은 명사로 표현하고 동사는 사용하지 않습니다.
   • 올바른 예: /api/v1/items
   • 잘못된 예: /api/v1/getItems
2. 계층적 구조를 사용하여 관계를 표현합니다.
   • 예: /api/v1/users/123/orders/456

4-2. HTTP 상태 코드 사용

• 성공: 200 OK, 201 Created
• 클라이언트 오류: 400 Bad Request, 404 Not Found
• 서버 오류: 500 Internal Server Error

4-3. JSON 응답 형식 통일

JSON 응답 형식을 표준화하여 일관성을 유지합니다.

@GetMapping("/standard")
public Map<String, Object> getStandardResponse() {
    Map<String, Object> response = new HashMap<>();
    response.put("status", "success");
    response.put("data", Arrays.asList("Item1", "Item2"));
    return response;
}

4-4. CORS 설정

Ajax 클라이언트가 다른 도메인에서 API를 호출할 수 있도록 CORS를 설정합니다.

@Configuration
public class WebConfig implements WebMvcConfigurer {
    @Override
    public void addCorsMappings(CorsRegistry registry) {
        registry.addMapping("/**").allowedOrigins("*");
    }
}

---

5. 마무리

RESTful 웹 서비스는 다양한 클라이언트(웹, 모바일, 데스크톱 등)와의 통신을 가능하게 합니다. 오늘 학습한 내용을 바탕으로 효율적인 RESTful API를 설계하고 구현할 수 있습니다. 다음에서는 Spring Security를 활용한 인증 및 권한 관리에 대해 학습합니다.