[초급] Dart RESTful API 설계 기초/RESTful API의 기본 원칙과 설계

 

웹 개발에서 데이터와 기능을 서버와 클라이언트 간에 안전하고 효율적으로 전달하기 위해 RESTful API를 사용하는 것이 일반적입니다. RESTful API는 클라이언트와 서버 간의 통신을 규칙에 따라 구조화하여 데이터를 쉽게 주고받을 수 있게 해줍니다.

이번 글에서는 RESTful API의 기본 원칙과 설계 방법을 초보자도 쉽게 이해할 수 있도록 설명하겠습니다.

1. RESTful API란?

RESTful API는 Representational State Transfer (REST) 원칙을 따르는 API입니다.

REST는 웹에서 자원을 관리하는 아키텍처 스타일로, 클라이언트와 서버 간의 통신을 간단하고 일관되게 만듭니다.

RESTful API는 주로 HTTP 프로토콜을 사용하여 데이터를 요청하고 응답합니다.

1.1 REST의 기본 원칙

1. Stateless: 각 요청은 독립적이어야 하며, 서버는 요청을 처리하는 데 필요한 모든 정보를 요청 자체에서 제공받아야 합니다.
2. Client-Server Architecture: 클라이언트와 서버는 서로 독립적이며, 서버는 데이터 처리와 저장을 담당하고, 클라이언트는 사용자 인터페이스를 제공합니다.
3. Uniform Interface: 통일된 인터페이스를 사용하여 클라이언트와 서버 간의 통신을 단순화합니다. 자원의 URL, HTTP 메서드 등을 통일된 방식으로 사용합니다.
4. Resource-Based: API는 자원(resource)을 중심으로 설계됩니다. 자원은 URI(Uniform Resource Identifier)로 식별됩니다.
5. Layered System: 서버는 여러 계층으로 나눌 수 있으며, 각 계층은 클라이언트가 직접적으로 인식하지 못하도록 설계됩니다.

2. RESTful API의 기본 설계 원칙

RESTful API를 설계할 때는 다음의 원칙을 따르는 것이 좋습니다:

2.1 자원의 식별

• URI 설계: 자원은 URI를 통해 식별됩니다. URI는 명확하고 일관되게 설계해야 합니다. 예를 들어, 사용자를 나타내는 URI는 /users, 특정 사용자를 나타내는 URI는 /users/{id}와 같이 설계합니다.

GET /users             // 모든 사용자 목록을 가져옴
GET /users/123         // ID가 123인 사용자의 정보를 가져옴
POST /users            // 새로운 사용자 생성
PUT /users/123         // ID가 123인 사용자 정보를 수정
DELETE /users/123      // ID가 123인 사용자 삭제

2.2 HTTP 메서드 사용

HTTP 메서드는 자원에 대해 수행할 작업을 정의합니다:

• GET: 자원을 조회합니다.
• POST: 새로운 자원을 생성합니다.
• PUT: 기존 자원을 업데이트합니다.
• DELETE: 자원을 삭제합니다.

2.3 응답 상태 코드

서버는 클라이언트의 요청에 대한 응답으로 HTTP 상태 코드를 반환합니다. 주요 상태 코드는 다음과 같습니다:

• 200 OK: 요청이 성공적으로 처리됨
• 201 Created: 자원이 성공적으로 생성됨
• 204 No Content: 요청이 성공적이지만 반환할 데이터가 없음
• 400 Bad Request: 요청이 잘못됨
• 404 Not Found: 요청한 자원을 찾을 수 없음
• 500 Internal Server Error: 서버 오류

3. Dart에서 RESTful API 구현하기

Dart에서는 HTTP 패키지를 사용하여 RESTful API를 구현할 수 있습니다. 기본적인 서버 구현 예제를 통해 RESTful API를 어떻게 구현하는지 알아보겠습니다.

3.1 HTTP 패키지 추가

pubspec.yaml 파일에 shelf 패키지를 추가하여 HTTP 서버를 구현할 수 있습니다.

dependencies:
  shelf: ^1.4.0
  shelf_router: ^1.1.0

3.2 서버 구현 예제

간단한 RESTful API 서버를 Dart로 구현해보겠습니다.

import 'package:shelf/shelf.dart';
import 'package:shelf/shelf_io.dart' as io;
import 'package:shelf_router/shelf_router.dart';

void main() async {
  final router = Router();

  // 사용자 목록 조회
  router.get('/users', (Request request) {
    return Response.ok('{"users": ["Alice", "Bob"]}', headers: {'Content-Type': 'application/json'});
  });

  // 특정 사용자 조회
  router.get('/users/<id>', (Request request, String id) {
    return Response.ok('{"user": "$id"}', headers: {'Content-Type': 'application/json'});
  });

  // 서버 시작
  final server = await io.serve(router.handler, 'localhost', 8080);
  print('Server running on http://${server.address.host}:${server.port}');
}

설명

• Router를 사용해 엔드포인트를 정의합니다.
• /users와 /users/<id> 엔드포인트를 정의하여 사용자 목록과 특정 사용자 정보를 반환합니다.
• 서버는 localhost:8080에서 실행됩니다.

3.3 클라이언트에서 API 호출하기

클라이언트에서 API를 호출할 때는 http 패키지를 사용할 수 있습니다.

import 'package:http/http.dart' as http;

void main() async {
  // 사용자 목록 요청
  final response = await http.get(Uri.parse('http://localhost:8080/users'));

  if (response.statusCode == 200) {
    print('Response body: ${response.body}');
  } else {
    print('Request failed with status: ${response.statusCode}.');
  }
}

설명

• http.get 메서드를 사용해 서버에서 사용자 목록을 요청합니다.
• 상태 코드가 200인 경우, 응답 본문을 출력합니다.

RESTful API는 웹 애플리케이션에서 데이터와 기능을 클라이언트와 서버 간에 효율적으로 주고받기 위한 중요한 도구입니다.

이 글에서는 RESTful API의 기본 원칙과 설계 방법을 살펴보고, Dart에서 API를 구현하는 방법을 소개했습니다.

이 기본 개념을 바탕으로 더 복잡한 API를 설계하고 구현해보세요!

구독!! 공감과 댓글은 저에게 큰 힘이 됩니다.

Starting Google Play App Distribution! "Tester Share" for Recruiting 20 Testers for a Closed Test.

Tester Share [테스터쉐어] - Google Play 앱