REST API 설계

1. 도입 (왜 배워야 하는가)

REST API(Representational State Transfer Application Programming Interface)는 현대 소프트웨어 개발에서 필수적인 요소입니다. 특히 클라이언트-서버 아키텍처를 사용하는 애플리케이션에서는 REST API를 통해 데이터 통신이 이루어집니다. 예를 들어, 모바일 애플리케이션이나 웹 애플리케이션에서 서버와 클라이언트 간의 데이터 교환이 필요할 때 REST API가 중심 역할을 합니다.

REST API를 설계하는 방법을 모른다면, 데이터 통신의 구조가 비효율적으로 설계될 수 있으며, 이는 결국 성능 저하, 유지보수의 어려움, 혹은 확장성 문제를 초래할 수 있습니다. 또한, 잘못된 설계는 보안 취약점으로 이어질 수 있으며, 클라이언트와 서버 간의 원활한 통신을 방해할 수 있습니다.

2. 핵심 개념 설명

REST란?

REST는 HTTP 프로토콜을 기반으로 한 아키텍처 스타일로, 자원의 상태를 전송하는 방식입니다. 예를 들어, 웹에서 정보를 검색하는 것은 RESTful하게 구현될 수 있습니다.

API란?

API는 Application Programming Interface의 약자로, 소프트웨어 구성 요소 간의 상호작용을 정의하는 인터페이스입니다. 예를 들어, 웹사이트에서 사용자 정보를 가져오는 기능이 API로 구현될 수 있습니다.

REST API의 주요 HTTP 메서드

REST API는 이러한 메서드를 통해 클라이언트가 서버에 요청을 보낼 수 있도록 합니다.

3. 기본 코드 예제

아래는 Dart를 사용하여 간단한 REST API 요청을 보내는 코드입니다.

import 'dart:convert'; // JSON 인코딩 및 디코딩을 위해 필요
import 'package:http/http.dart' as http; // HTTP 요청을 위해 필요

void main() async {
  final response = await http.get(Uri.parse('https://jsonplaceholder.typicode.com/posts/1'));

  if (response.statusCode == 200) {
    // 요청이 성공적으로 처리된 경우
    var jsonResponse = jsonDecode(response.body); // JSON 응답을 파싱
    print('제목: ${jsonResponse['title']}'); // 제목 출력
  } else {
    // 요청 실패 시 에러 출력
    print('서버 오류: ${response.statusCode}');
  }
}

실행 결과

제목: sunt aut facere repellat provident occaecati excepturi optio reprehenderit

코드 동작 설명

1. import 'dart:convert';: JSON 데이터를 다루기 위해 dart:convert 패키지를 가져옵니다.
2. import 'package:http/http.dart' as http;: HTTP 요청을 보내기 위해 http 패키지를 가져옵니다.
3. main() async: 비동기 함수로 메인 진입점입니다.
4. final response = await http.get(...): 지정된 URL에 GET 요청을 보냅니다.
5. if (response.statusCode == 200): 요청이 성공적으로 처리되었는지 확인합니다.
6. var jsonResponse = jsonDecode(response.body);: 응답을 JSON 형식으로 파싱합니다.
7. print('제목: ${jsonResponse['title']}');: 파싱한 JSON에서 'title' 값을 출력합니다.
8. print('서버 오류: ${response.statusCode}');: 요청 실패 시 에러 코드를 출력합니다.

4. 실전 활용 예제

예제 1: 쇼핑몰에서 장바구니를 구현할 때

void addToCart(int productId) async {
  final response = await http.post(
    Uri.parse('https://api.example.com/cart'),
    headers: <String, String>{
      'Content-Type': 'application/json; charset=UTF-8',
    },
    body: jsonEncode(<String, int>{
      'productId': productId,
    }),
  );

  if (response.statusCode == 201) {
    print('장바구니에 추가되었습니다.');
  } else {
    print('장바구니 추가 실패: ${response.statusCode}');
  }
}

예제 2: 사용자 정보를 업데이트할 때

void updateUser(int userId, String name) async {
  final response = await http.put(
    Uri.parse('https://api.example.com/users/$userId'),
    headers: <String, String>{
      'Content-Type': 'application/json; charset=UTF-8',
    },
    body: jsonEncode(<String, String>{
      'name': name,
    }),
  );

  if (response.statusCode == 200) {
    print('사용자 정보가 업데이트되었습니다.');
  } else {
    print('업데이트 실패: ${response.statusCode}');
  }
}

5. 흔한 실수와 주의사항

실수 1: HTTP 메서드 혼동

• 잘못된 코드:

  http.put(...); // 자원을 생성해야 하는데 PUT을 사용

• 올바른 코드:

  http.post(...); // 자원을 생성할 때는 POST 사용

실수 2: URL 경로 오류

• 잘못된 코드:

  Uri.parse('https://api.example.com/user'); // 사용자 정보 업데이트 시 잘못된 경로

• 올바른 코드:

  Uri.parse('https://api.example.com/users/$userId'); // 올바른 경로 사용

6. 정리

• REST API는 클라이언트와 서버 간 데이터 통신의 핵심입니다.
• HTTP 메서드(GET, POST, PUT, DELETE) 각각의 용도를 이해해야 합니다.
• Dart에서 REST API를 사용하려면 http 패키지를 활용할 수 있습니다.
• 요청의 성공 여부를 확인하고 적절한 에러 처리를 해야 합니다.
• REST API 설계를 잘못하면 성능 저하 및 보안 취약점이 발생할 수 있습니다.

다음에 학습하면 좋은 주제

• GraphQL API 설계
• JWT(JSON Web Token) 인증
• API 문서화 도구 (Swagger, Postman 등) 사용법