데이터를 그리기 위한 Front_End 언어 공부하기 : React _ 03 == API에 대해서 이해해보기.

Data-Forge : 데이터로 세상 이해해보기.·2025년 5월 8일
Reactnext개발공부프론트엔드

데이터를 그리기 위한 Front_End : React & Next

목록 보기
5/7

데이터를 그리기 위한 FrontEnd 언어 공부하기 : React 03 == API에 대해서 이해해보기.

▽ React _ 03 == API에 대해서 이해해보기.

 목  차
 
 1. API 기본 개념 이해
 
 2. API의 기본 구조와 작동 원리
 
 3. API 사용 시 꼭 알아야 할 핵심 요소
 
 4. API 형식과 선택 기준
 
 5. API 활용 방식에 따른 분류.
 
 6. 실무 중심 API 활용 전략.
 
 7. API 설계 철학 및 아키텍처 전략
 
 8. API 성능 최적화 및 확장성 대응
 
 9. API 테스트, 배포, 모니터링 자동화
 
 10. API 보안 심화 및 실제 보안 위협 대응.

1. API 기본 개념 이해.

1.1 API 정의와 목적.

API란 무엇인가? (Application Programming Interface)

  • 💡 API는 애플리케이션 프로그래밍 인터페이스(Application Programming Interface)의 줄임말로, '소프트웨어 구성 요소 간의 상호작용을 위한 명세'입니다.

  • 소프트웨어 '애플리케이션이 서로 통신하고 데이터나 기능을 교환할 수 있도록 하는 규칙이나 프로토콜'을 의미합니다.

  • 시스템 간의 '통신 방법'을 정의하는 '인터페이스'로,
    '특정 기능이나 데이터를 외부에 제공하는 규격'입니다.

  • API를 통해 개발자는 다른 애플리케이션의 기능을 '직접 구현하지 않고도 쉽게 활용' 가능하며, '애플리케이션 개발을 간소화하고 효율성을 높일 수 있습니다.'

  • 예를 들어, '웹 API'는 클라이언트(웹/앱)가 서버에서 데이터를 요청하고, 서버가 이를 응답하는 방식으로 동작합니다.

시스템 간 통신을 위한 명세 (Interface)

과거에는 프로그램 간 직접 통신이 매우 어려워, 개발자가 수작업으로 일일이 대응해야 했습니다.

  • API는 서버와 클라이언트, 또는 다른 시스템 간에 정보를 주고받을 수 있는 규칙을 정의합니다.

    • 예를 들어, 쇼핑몰에서 상품 정보를 요청하는 경우, 서버는 상품 목록을 API를 통해 반환합니다.

  • 현재는 API를 통해 일정한 구조와 규약을 설정하고 통신이 가능.

  • 훨씬 효율적이고 체계적인 시스템을 구축 가능.

    • 반복적인 코드 작성량을 줄이고,
    • 사용자별 데이터 접근을 보다 안전하게 제어 가능하며,
    • 내부 시스템 구축에도 활용 가능합니다.

추상화: 내부 구현과 사용자의 분리

  • API는 내부 구현을 숨기고 외부 사용자는 단순화된 인터페이스를 통해 원하는 기능을 사용 가능합니다.

  • '추상화'를 통해 개발자는 API의 세부 구현사항을 몰라도,
    필요한 작업을 API를 통해 쉽게 사용 가능합니다.

    • Ex) 트위터 API는 트위터의 복잡한 내부 로직을 숨기고,
      개발자가 '트윗하기', '팔로우' 등과 같은 기능들을 쉽게 호출 가능합니다.

즉, API는 개발 생산성과 보안성을 모두 향상시키는 핵심 수단.!

1.2 API의 역사와 발전.

초기 API: RPC, SOAP.

  • RPC (Remote Procedure Call):

    • 서버의 함수를 원격에서 호출할 수 있는 방법으로,
      서버와 클라이언트 간의 원격 함수 호출 방식입니다.

      • → 예: callServerFunction("data") 처럼, 서버에서 특정 함수를 실행하는 방식.

  • SOAP (Simple Object Access Protocol):

    • XML을 사용한 무겁고 복잡한 프로토콜로, 보안, 트랜잭션 등을 고려하여 설계되었습니다.
      • → XML 메시지 포맷을 기반으로 한 고전적인 API 방식.

REST의 등장.

  • REST (Representational State Transfer):

    • HTTP 프로토콜을 기반으로 자원(데이터)을 정의하고,
    • 이를 HTTP 메서드(GET, POST 등)로 조작하는 방식.

  • REST는 간결하고 직관적인 구조로 인해 웹 서비스의 표준으로 자리잡았습니다.

    • → 예: GET /users로 사용자 리스트 조회, POST /users로 사용자 생성.

최신 API: GraphQL, gRPC 등.

  • GraphQL:

    • 클라이언트가 필요한 데이터만 요청할 수 있도록 설계된 쿼리 언어입니다.
      → 예: GET /users?fields=name,email처럼 필요한 필드만 요청 가능.

  • gRPC:

    • Protocol Buffers를 사용하는 고성능 API로,
      바이너리 프로토콜을 기반으로 데이터를 빠르고 효율적으로 처리합니다.
      → 마이크로서비스 간의 빠르고 안정적인 통신에 주로 사용됩니다.

  • Web API:

    • 웹, 앱, IoT 등 다양한 기기들이 서로 통신할 수 있게 해주는 인터넷 기반 API로,
      다양한 프로토콜과 기술이 결합된 형태로 발전했습니다.

1.3 API를 왜 사용하는가?.

비즈니스 로직과 UI 분리

  • API를 사용하면 백엔드(서버)와 프론트엔드(클라이언트)가 독립적으로 개발될 수 있습니다.

    • → 예를 들어, 모바일 앱과 웹 앱이 같은 API를 사용하여,
      동일한 데이터를 처리하고 화면을 표시할 수 있습니다.

  • 비즈니스 로직은 서버에서 처리하고,
    사용자 인터페이스(UI)는 클라이언트에서 처리하는 분리된 구조로 시스템을 구축할 수 있습니다.

여러 플랫폼(웹/앱)에서 동일한 백엔드 사용

  • API를 통해 백엔드 서버는 다양한 플랫폼(웹, 모바일 앱 등)에서 동일하게 활용됩니다.

  • 예를 들어, 모바일 앱과 웹 애플리케이션은 같은 API를 호출하여 데이터를 가져옵니다.

    • → API의 재사용성 덕분에 코드 중복을 줄이고, 비즈니스 로직 변경이 서버에서만 처리됩니다.

오픈 API를 통한 기능 확장 (OAuth, 결제, 번역 등)

  • 오픈 API를 통해
    외부 개발자들이 특정 서비스에 기능을 추가하거나 새로운 서비스를 구축할 수 있습니다.

    • 예: OAuth를 통해 구글 로그인 기능을 외부 앱에 통합

    • 예: 결제 API를 이용해 쇼핑몰에서 결제 시스템을 구축

    • 예: 번역 API를 사용해 다국어 지원 기능을 추가

2. API의 기본 구조와 작동 원리.

2.1 클라이언트-서버 모델에서의 API.

RESTful 구조의 전형적인 흐름

  • API는 클라이언트-서버 아키텍처를 기반으로 동작합니다.

    • → 클라이언트(웹/앱)는 데이터를 요청하고, 서버는 데이터를 처리하여 응답합니다.

  • RESTful API는 URL(자원 식별)과 HTTP 메서드를 조합하여,
    데이터를 CRUD(Create, Read, Update, Delete) 방식으로 다룹니다.

역할 분리: 서버는 기능 제공자, 클라이언트는 소비자.

  • 서버: 비즈니스 로직 수행, DB 접근, 리소스 관리 등 기능 제공

  • 클라이언트: API를 통해 데이터를 요청하고 UI에 반영하는 소비자

    • 예: 프론트엔드는 /api/products를 요청해 상품 리스트를 받고, UI에 표시.

2.2 HTTP 기반 API의 구성 요소.

URL (엔드포인트).

  • API 호출 주소는 일반적으로 RESTful 경로로 구성됩니다.

    • 예: /api/users/1 → ID가 1인 사용자 정보

  • 명확한 리소스 구조로 표현해야 직관적입니다.

    • /api/orders/123/items → 주문 ID 123의 아이템 목록

HTTP Method: GET, POST, PUT, PATCH, DELETE

  • 동작의 목적에 따라 HTTP 메서드를 사용합니다.

Request/Response Header & Body 구조

  • API는 요청(request)과 응답(response)의 구조를 기반으로 동작합니다.

    • 요청(Request): 클라이언트(사용자)가 서버에 필요한 정보를 요구하는 것.

      • Request 예시.
GET /api/users/1 HTTP/1.1
Host: example.com
Authorization: Bearer <token>
Accept: application/json

  • 응답(Response): 서버가 요청을 처리한 후 클라이언트에게 결과를 돌려주는 것.

    • 응답 데이터는 대부분 JSON 형식을 통해 전달됩니다.

JSON (JavaScript Object Notation):
Key와 Value로 구성된 가볍고 직관적인 데이터 형식입니다.

  • Response 예시.
HTTP/1.1 200 OK
Content-Type: application/json

{
  "id": 1,
  "name": "Jane Doe",
  "email": "jane@example.com"
}

주요 HTTP 헤더.

2.3 요청-응답 사이클.

기본 흐름: 요청 → 처리 → 응답.

  1. 클라이언트가 요청을 보냄 (예: GET /api/products)

  2. 서버가 요청을 처리하고 필요한 데이터를 조회

  3. 처리 결과를 응답으로 전달 (예: JSON 형태)

HTTP 상태 코드.

  • 상태 코드는 '클라이언트가 결과를 해석'하고 대응하게 해주는 핵심 요소입니다.

REST의 Stateless 원칙

  • REST API는 Stateless(무상태)해야 합니다.

    • → 각 요청은 독립적이어야 하며, 서버는 이전 요청 상태를 기억하지 않음.

  • 모든 요청은 필요한 정보를 자체적으로 포함해야 합니다.

    • 예: 매 요청마다 Authorization 헤더로 인증 정보를 포함

2.4 API 문서와 자동화 도구

Swagger / OpenAPI

  • API 명세를 문서화하고 시각화할 수 있는 자동화 도구

  • OpenAPI 스펙을 기반으로 작성된 API 정의는 Swagger UI로 인터랙티브하게 테스트 가능

  • 백엔드 개발 시, API 명세와 개발이 동시에 이루어져 협업 및 유지보수에 유리

Postman, Insomnia, Thunder Client.

  • API 요청을 직접 테스트하고 자동화할 수 있는 API 클라이언트 툴

  • 실무에서 백엔드와 연동 테스트, 오류 확인, 문서화 등에 사용

2.5 CORS와 브라우저 보안 정책.

동일 출처 정책(Same-Origin Policy)이란?

  • 웹 브라우저는 '보안'을 위해 기본적으로 '다른 출처(origin)의 리소스에 접근을 제한' 합니다.

  • 출처(origin)는 "프로토콜 + 도메인 + 포트"로 구성됩니다.

  • '보안'의 이유로, 브라우저는 '동일 출처가 아닐 경우 요청을 제한'합니다.
    • 이를 Same-Origin Policy라고 합니다.

Cross-Origin 요청의 필요성.

하지만 현실 개발환경에서는 다양한 상황에서 출처가 다른 API 요청이 필요합니다.

이때 클라이언트가 백엔드 API에 요청을 보내면 Cross-Origin 요청이 발생합니다.

CORS가 막는 시나리오 예시.

브라우저는 다음과 같은 상황에서 요청을 차단(CORS 에러 발생)합니다:

  • 1.다른 출처에 POST 요청을 보냈지만, 서버가 CORS 설정을 안 함

  • 2.인증 헤더(Authorization)를 포함한 요청인데, 서버가 허용하지 않음

  • 3.Content-Type이 application/json인 요청인데, 서버가 미리 허용 안 함

서버가 명시적으로 "Access-Control-Allow-Origin" 헤더를 포함해 응답하지 않으면
브라우저가 응답을 차단합니다.

Preflight 요청과 OPTIONS 메서드.

  • 복잡한 요청(예: PUT, DELETE, Content-Type: application/json)은 실행 전에
    사전 검사 요청(Preflight Request)를 보냅니다.

  • 이때 OPTIONS 메서드를 사용하여 서버에 허용 여부를 확인합니다.

  • Preflight 요청 흐름:

    • 1.브라우저가 OPTIONS 요청을 먼저 전송

    • 2.서버가 허용 가능한 메서드, 헤더 등을 명시한 응답을 전송

    • 3.조건에 맞으면 브라우저가 실제 요청을 보냄

OPTIONS /api/data HTTP/1.1
Origin: http://localhost:3000
Access-Control-Request-Method: POST
Access-Control-Request-Headers: Content-Type

HTTP/1.1 204 No Content
Access-Control-Allow-Origin: http://localhost:3000
Access-Control-Allow-Methods: POST, GET, OPTIONS
Access-Control-Allow-Headers: Content-Type

서버가 위와 같이 응답하면, 브라우저는 POST 요청을 허용합니다.

정리 및 팁.

  • 프론트 개발 시 CORS 오류는 대부분 '백엔드 설정 문제' 입니다.

3. API 사용 시 꼭 알아야 할 핵심 요소.

🔐 3.1 인증(Authentication)과 인가(Authorization).

인증과 인가의 차이.

  • 인증(Authentication): "너는 누구니?"
    → 사용자의 신원을 확인

  • 인가(Authorization): "이 기능을 사용할 권한이 있니?"
    → 사용자가 특정 리소스에 접근할 수 있는지 확인

대표 인증 방식.

Access Token / Refresh Token 개념.

  • Access Token

    • 짧은 유효기간
    • 요청 시 인증 헤더에 포함 : Authorization: Bearer token
    • 탈취 시 위험 크기 큼 -> 만료 기간 짧게 설정.

  • Refresh Token

    • 긴 유효기간
    • Acess Token 갱신 용도로 사용
    • 서버 저장 or HttpOnly 쿠키 권장

  • 💡 Refresh Token은 절대로 클라이언트에서 노출되면 안 됩니다.!!

3.2 에러 처리 전략.

예외 상황의 응답 구조 예시

  • REST API는 일관된 에러 응답 구조가 중요합니다.
{
  "status": 400,
  "error": "Bad Request",
  "message": "username is required",
  "timestamp": "2025-05-07T12:34:56Z",
  "path": "/api/users"
}

에러 코드 + 메시지 표준화

  • 💡 프론트엔드는 이 에러 응답을 기반으로 사용자에게 적절한 메시지를 안내해야 합니다.

3.3 요청 제한 및 보안.

Rate Limiting 개념과 적용 방식

  • API 남용, DDoS 방지용으로 일정 시간 내 요청 수 제한.

    • 구현 예시.
      • IP당 1분에 100건
      • 토큰당 하루 1000건 등.
    • Express.js 적용 예시.
const rateLimit = require('express-rate-limit');
app.use(rateLimit({
  windowMs: 1 * 60 * 1000,  // 1분
  max: 100,                 // 최대 100건
  message: "Too many requests"
}));

사용자별/토큰별 요청 제한

  • 사용자 ID 또는 JWT sub 필드를 기준으로 제한 가능

  • Redis를 사용해 분산 환경에서도 관리 가능.

3.4 버전 관리 (API Versioning).

버전 관리가 필요한 이유.

  • 클라이언트가 예상하는 API 응답이 바뀔 경우, 오류 유발.

  • 새 기능 추가 시, 기존 사용자를 꺠지 않기 위해 버전 관리 필수.

버전 관리 방식.

하위 호환성 전략

  • v1을 유지하고, v2를 병렬 제공

  • 가능하면 기존 응답 구조는 변경하지 않기

  • 파라미터나 필드를 선택적으로 추가.

요약.

4. API 형식과 선택 기준.

4.1 REST API

자원 중심(Resource-Oriented) 설계

  • REST(Representational State Transfer)는 자원을 URL로 표현하고,
    HTTP 메서드로 동작을 정의하는 방식 입니다.

  • 예: /users/123 → 특정 사용자 리소스

URL + HTTP 메서드 조합.

HTTP 메서드의미예시 URL설명
GET조회/users/list사용자 목록 조회
POST생성/users/create사용자 생성
PUT/PATCH수정/users/update사용자 정보 수정
DELETE삭제/users/delete사용자 삭제

REST의 장점.

  • 구조가 단순하고 직관적

  • HTTP 기반이므로 모든 플랫폼에서 사용 가능

  • 다양한 캐싱, 보안, 로깅 도구와 호환

REST의 ⚠️ 단점.

  • 과도한 데이터 요청/전송 문제 ( 필요 없는 데이터까지 전송 )

  • 복잡한 관계형 데이터 표현에 한계.

💡 REST는 대부분의 CRUD 중심 시스템에 적합하며,
대다수 서비스 백엔드 기본 구조로 사용됩니다.

4.2 GraphQL

필요한 데이터만 쿼리하는 방식.

  • meta가 만든 쿼링 언어.

  • 클라이언트가 정확히 원하는 '데이터 구조를 요청' 가능.

query {
  user(id: "1") {
    name
    posts {
      title
    }
  }
}

✅ GraphQL의 장점.

  • Over-fetching, Under-fetching 해결

  • 하나의 요청으로 여러 리소스 데이터 통합 가능

  • API 버전 관리 불필요 (필드 단위 요청/응답 가능)

GraphQL의 ⚠️ 단점.

  • 러닝 커브 존재 (스키마 설계, Resolver 구현 등)

  • 캐싱이 어려움 (GET URL 기반 캐시 불가)

  • 파일 업로드, 인증 등 REST보다 구현 복잡

💡 모바일, SPA 환경에서 효율적이며, 복잡한 관계형 데이터 UI가 필요한 경우에 적합합니다.

4.3 gRPC

Protocol Buffers 기반의 고성능 RPC

  • 구글에서 만든 '이진 직렬화 기반 고속 API 프레임워크'

  • HTTP/2 기반 -> 멀티플렉싱, 바이너리 전송

gRPC의 특징.

  • REST보다 데이터 전송량 작고 속도 빠름.

  • 자동화된 클라이언트 SDK 생성.

  • 양방향 스트리밍 지원.

gRPC의 활용 사례.

  • 마이크로서비스 아키텍처 내부 통신

  • IoT, 게임 서버, 고성능 백엔드 서비스 등

gRPC의 단점.

  • 브라우저 직접 호출 불가 -> 중간 Proxy 필요

  • 디버깅 도구나 로딩 환경 제한적

  • 초기 설정 복잡 (IDL 정의, 스텁 생성 등)

💡 내부 서비스 간 고성능 통신이 필요한 B2B 시스템에 적합합니다.

4.4 WebSocket / SSE

실시간 양방향 통신 지원

  • HTTP 요청/응답 구조와 달리, 지속적인 연결 유지.

  • 서버 -> 클라이언트로 직접 데이터 푸시 가능.

두 가지 주요 방식.

사용 예시.

  • 채팅, 실시간 알림

  • 주식 시세, 게임 상태 전파

  • 협업 툴 (예: Google Docs 실시간 동기화)

💡 브라우저 환경, 연결 유지 전략, 네트워크 제한 등을 고려해 선택합니다.

API 형식 선택 기준 요약.

📌 마무리 팁
REST: 기본 CRUD 중심 서비스, 백오피스, 단순 API

GraphQL: 유연한 프론트엔드 데이터 제어, 모바일/SPA

gRPC: 내부 시스템 통신, 성능 중심 서비스

WebSocket/SSE: 실시간 알림, 채팅, 스트리밍 서비스

5. API 활용 방식에 따른 분류.

🌍 5.1 Public API (공개 API)

누구나 접근 가능 (ex. GitHub API)

  • 인증 없이 또는 간단한 API 키만으로 사용 가능.

  • 일반 대중 또는 개발자 커뮤니티에 서비스 기능을 개방.

대표 사례.

  • GitHub REST API

  • OpenWeatherMap API

  • Google Maps (제한 범위 내에서 공개 키로 사용 가능)

목적 및 장점.

  • 생태계 확장 ( 외부 개발자 유입 )

  • 브랜드 인지도 증가

  • 다양한 써드파티 앱과의 통합 촉진.

⚠️ 주의사항.

  • 남용 방지를 위한 Rate Limiting

  • 간단한 인증(Tokens), CORS 정책 등 필수

🤝 5.2 Partner API (제휴 API)

계약된 사용자만 접근.

  • 외부지만, 공식적으로 제휴를 맺은 파트너만 사용 가능.

  • 일반 사용자에게는 비공개.

특징.

  • API Key 또는 OAuth 기반 인증 필요

  • 문서 접근 및 사용 권한은 협약에 따라 제한됨

대표 사례.

  • 결제 게이트웨이 API (카카오페이, Toss 등)

  • 네이버 검색광고 API

  • 물류 연동 API (쿠팡 파트너사 배송 연동)

목적.

  • 비즈니스 협력 강화

  • 외부 기업과의 시스템 통합 자동화

  • 거래/인증 기반 서비스 제공.

🔐 5.3 Private API (사내 API)

내부 시스템 전용 API

  • 외부에는 전혀 노출되지 않음.

  • '사내 웹/앱, 백오피스, 마이크로서비스 간 통신'에 사용!

특징.

  • 인증, 권한 검증 로직 필수

  • 보안이 최우선!! (VPN, IP 화이트리스트 등 사용)

목적.

  • 내부 시스템 모듈화 및 재사용성 확보.

  • DevOps 배치 처리, 내부 자동화 툴 등에 활용.

  • 실시간 모니터링, 로깅 등 백엔드 통합.

💡 예: inventory.internal.company.com/api/stock-check

🧩 5.4 Composite API (조합 API)

여러 API 호출을 하나로 통합

  • 여러 리소스 또는 엔드포인트 호출을 묶어서 한 번에 응답.

  • 클라이언트 입장에서 API 호출 횟수를 줄이는 데 효과적.

예시.

  • /user-profile 호출 시, 사용자 정보 + 주문 이력 + 알림 설정 통합 반환

  • 마이크로서비스로 구성된 여러 개의 API 결과값을 서버에서 미리 합쳐서 반환.

장점.

  • 네트워크 비용 절감 (요청 횟수 줄임)

  • 프론트엔드/모바일에서 '로딩 속도 향상'

  • GraphQL과 유사한 효과를 REST 방식에서도 일부 구현 가능.

⚠️ 주의사항.

  • 복잡한 조합일수록 서버 측 구현 난이도 증가

  • 응답 실패 시 오류 원인 추적이 어려울 수 있음.

🧩 요약.

6. 실무 중심 API 활용 전략.

🖥️ 6.1 클라이언트에서 API 소비

기본 호출 방식 : fetch, axios

  • 'fetch' : 브라우저 기본 내장 함수.

    • 기본 내장 API로, Promise 기반의 HTTP 요청 처리.
    • fetch(url, options) 형식으로 사용되며, JSON 응답을 받기 위해 response,json() 호출 필요.
    • 에러 처리는 try/catch 또는 .catch()를 통해 수행.
    • 예시.
fetch('/api/user/1')
  .then(res => res.json())
  .then(data => console.log(data))
  .catch(err => console.error(err));

  • axios

    • 'fetch'보다 사용이 직관적이며, JSON 변환 불필요 ( 자동 처리 )
    • 요청/응답 인터셉터, 타임아웃, 응답 데이터 구조 정형화 등의 기능 제공.
    • 예시.
const response = await axios.get('/api/user/1');
console.log(response.data);

고급 호출 방식 : React Query / SWR

  • 데이터 패칭, 캐싱, 리페치, 에러/로딩 상태 관리를 추상화한 라이브러리.

  • 'React Query' : 강력한 캐시 정책, 백그라운드 리페치, 자동 리트라이 제공.

  • 'SWR' : 'Stale - While - Revalidate' / 전략 기반, 가볍고 빠른 경험 제공.

캐싱, 로딩, 에러 처리.

  • 캐싱.

    • 동일 요청 반복 시, 네트워크 낭비를 방지.
    • React Query의 cacheTime, SWR의 dedupingInterval 설정 등으로 제어.

  • 로딩 처리.

    • 데이터 불러오기 전 'Loading' 등 상태 UI 제공.
    • ex) isLoading, isFetching, isValidating 등 상태 값을 활용.

  • 에러 처리.

    • 서버 오류 메시지와 클라이언트 대응 분리 필요.
    • 사용자에게 명확한 피드백 제공 ( ex : 로그인이 필요합니다 등등 )

6.2 API 서버 개발 (Node.js, Nest.js, FastAPI 기준)

Express로 RESTful API 구현

  • 라우터 기반으로 각 URL에 기능 바인딩.

  • 기본 흐름

    • 요청(Request) → 미들웨어 → 라우터 → 컨트롤러 → 응답(Response).

  • 예시.

app.get('/api/users/:id', (req, res) => {
  const user = db.find(u => u.id === req.params.id);
  res.json(user);
});

  • 특징.

    • 구조 설계가 자유로워 소규모 프로젝트에 적합.
    • 미들웨어 패턴 중심 : 로깅, 인증, 예외 처리 등을 체인화 가능.
    • TypeScript 지원 가능하지만, 기본은 JS 중심.

Nest.js 기반 API 서버 개발.

Node.js + TypeScript 기반의 의존성 주입(DI), 모듈 구조, 데코레이터 기반 개발 방식 제공.

  • 장점.

    • Angular 아키텍처에서 영감을 받아 모듈화, 테스트 용이성, DI 컨테이너 제공.
    • REST, GraphQL, WebSocket 모두 대응 가능
    • Express/Fastify 어댑터 기반으로 확장성 확보.

  • 기본 구조.

    • Controller: 라우팅 정의 (@Get(), @Post() 등)

    • Service: 비즈니스 로직

    • Module: 각 기능 단위 묶음

  • 예시.

@Controller('users')
export class UserController {
  constructor(private readonly userService: UserService) {}

  @Get(':id')
  findOne(@Param('id') id: string) {
    return this.userService.findById(id);
  }
}

  • 기타 기능

    • Pipe(유효성 검사), Guard(권한 검사), Interceptor(응답 조작) 등 완성형 아키텍처 지원.
    • Swagger 자동 문서화(@nestjs/swagger)

FastAPI 기반 API 서버 개발 (Python).

Python 3.6+ 타입 힌트를 적극 활용하는 비동기 웹 프레임워크. 빠른 개발과 높은 성능이 특징.

  • 특징.

    • Pydantic을 기반으로 한 입력/출력 데이터 자동 유효성 검사

    • 자동 Swagger UI 문서 생성

    • 비동기 처리를 지원하는 async def 기반 구조

    • OpenAPI 및 JSON Schema 완전 지원

  • 기본 구조.

from fastapi import FastAPI

app = FastAPI()

@app.get("/users/{id}")
async def get_user(id: int):
    return {"id": id, "name": "John"}

  • 장점.

    • 개발자가 작성한 타입 힌트를 기반으로 문서와 데이터 검증 자동화.
    • Pythonic하고 직관적인 코드 작성.
    • 마이크로서비스/ML API 백엔드 구축에 최적화.

Router, Middleware, CORS 설정

CORS 설정 예시(Express / Nest.js / FastAPI )

  • Express에서 CORS 설정.

    • Express에서는 cors 미들웨어를 사용하여 간편하게 CORS 설정 가능.

    • 설치.

      • npm install cors

    • 기본 예시.

  • 옵션 설정 예시.

  • Nest.js에서 CORS 설정.

    • Nest.js는 내부적으로 Express (또는 Fastify)를 사용하므로, CORS는 main.ts에서 설정함.

    • 기본 설정 (main.ts)

  • 옵션 설정.

  • Fastify로 사용하는 경우.

    -Fastify CORS 플러그인 설치 후 NestFactory.create NestFastifyApplication으로 설정 필요.

  • FastAPI에서 CORS 설정.

    • FastAPI는 CORSMiddleware를 사용해 설정하며, add_middleware()를 통해 적용함.

 - allow_origins=["*"] → 모든 도메인 허용 (실제 서비스에서는 특정 도메인만 허용해야 보안상 안전)

 - allow_credentials=True → 쿠키 전송 허용 시 필요

💡 개발 팁: CORS는 보안 설정이다.

  • 프론트엔드 개발 중 CORS 오류는
    백엔드가 외부 출처 요청을 허용하지 않아서 발생하는 보안 정책 오류임.

  • 개발환경에서는 "*"로 허용 가능하지만,
    운영환경에서는 반드시 origin을 명시하고 인증 정책과 함께 설계해야 함.

  • OPTIONS 프리플라이트 요청이 발생하는 조건:

    • Content-Type이 application/json이 아닌 경우

    • Authorization 헤더가 포함된 경우

    • PUT, DELETE 등 "단순하지 않은 요청"

6.3 테스트 및 문서화

Swagger + Express 연동

  • OpenAPI 스펙 기반 문서 자동화 도구.
    • 사용 모듈: swagger-jsdoc, swagger-ui-express.

  • 장점.

    • API 구조 시각화
    • 테스트 기능 내장
    • 클라이언트/ 서버 협업 효율 증가.

Swagger + Nest.js 연동.

  • Nest.js는 @nestjs/swagger 모듈을 통해 Swagger 문서화를 간편하게 지원합니다.

  • 장점.

    • Nest의 Decorator 기반 구조와 자연스럽게 연동됨.
    • DTO, Controller, Enum, Response 등의 정보를 자동 문서화.

Swagger + FastAPI 내장 지원.

  • FastAPI는 OpenAPI (Swagger UI)를 기본 내장합니다. 설정 없이도 자동 문서화됩니다.

  • 접속 경로.

  • 예시.

  • 장점.

    • 문서 자동 생성 (Pydantic 기반)

    • 파라미터, 응답 타입, 설명 등 자동 인식

6.4 API 모니터링과 최적화

응답 속도 측정 & 실패율 추적.

Express.js

  • 성능 분석 : Date.now()로 요청/응답 시간 계산

  • 로그 시스템 : winston, morgan

Nest.js에서 성능 로깅.

  • Interceptor 기반 요청 시간 측정.

  • Logger는 기본 @nestjs/common에서 제공.

FastAPI에서 성능 측정.

  • X-Process-Time 헤더에 응답 시간 추가.

  • 외부 툴: Prometheus + Grafana, Sentry, Datadog 등 연동 가능.

API Gateway, BFF 패턴 적용

📌 공통 기능.

  • 인증/인가 처리

  • 라우팅 및 로깅

  • 트래픽 제한 (Rate Limiting)

  • Failover, Load Balancing

📦 주요 툴

  • API Gateway: AWS API Gateway, Kong, NGINX, Traefik

  • BFF (Backend for Frontend): 클라이언트별 최적화 백엔드 (예: React용 전용 API 라우터)

📌 Nest.js에서 BFF 구조

  • @Module 단위로 프론트엔드 별 분리 API 구성

  • 예: WebApiModule, MobileApiModule

📌 FastAPI에서 BFF 구현
  • 라우터 분기를 통해 클라이언트 환경별로 경로 분리.
app.include_router(web_router, prefix="/web")
app.include_router(mobile_router, prefix="/mobile")

7. API 설계 철학 및 아키텍처 전략.

7.1 RESTful 설계 원칙

💡 개념 이해.

  • REST(Representational State Transfer)는 HTTP 기반의 아키텍처 스타일로,
    자원을 명확히 정의하고 이를 HTTP 메서드로 처리하는 방식입니다.

  • 단순히 API를 만드는 기술이 아니라,
    "어떻게 하면 명확하고 일관된 규칙으로 API를 설계할 수 있을까"에 대한 철학적인 지침을 제공합니다.

💡 핵심 원칙.

  • 자원 중심(Resource-Oriented): URI는 자원을 식별합니다.

    • 예: /users/1, /products/42

  • 행위는 HTTP 메서드로 구분.

    • GET: 조회

    • POST: 생성

    • PUT: 전체 수정

    • PATCH: 부분 수정

    • DELETE: 삭제

  • Stateless:

    • 각 요청은 독립적으로 처리되며, 서버는 클라이언트의 이전 상태를 저장하지 않습니다.

  • 계층 구조의 URI 설계:

    • /users/1/orders는 사용자 1의 주문 목록이라는 계층적 관계를 표현합니다.

  • 표현의 전이(Representation):

    • 클라이언트는 자원의 상태를 다양한 포맷(JSON, XML 등)으로 받아봅니다.

7.2 응답 구조 표준화

💡 왜 필요할까?

API의 성공/실패 응답 구조가 통일되어 있으면, 클라이언트는 처리 로직을 단순화할 수 있고, 에러 처리도 일관되게 구현할 수 있습니다.

📦 표준 응답 예시.

  • 성공.
  • 실패.

7.3 API 버저닝 전략

💡 왜 버전이 필요한가?

  • 기존 사용자에게 영향을 주지 않으면서 새로운 기능을 추가하거나 구조를 변경하기 위해서다.

📌 방법 비교.

  • URL 기반 (가장 일반적): /api/v1/users

  • Header 기반: Accept: application/vnd.myapi.v2+json

  • Media Type 기반: REST 원칙에는 더 충실하지만 실무에서는 적용 복잡도가 있음

🧭 적용 시 고려사항.

  • 문서화 필요성 증가

  • Deprecated 버전 유지 기간 명시

7.4 확장 가능한 API 설계

🧪 클라이언트 요구를 반영한 API 설계.

  • 필터링: /products?category=shoes

  • 정렬: /products?sort=price_desc

  • 페이징: ?limit=10&page=2

  • 필드 선택(Field Masking): /users/1?fields=id,name,email

  • HATEOAS 적용 여부:

7.5 DDD 기반 설계 연계

📘 DDD란?

  • 도메인 주도 설계(Domain-Driven Design)는 복잡한 비즈니스 로직을 도메인 중심으로 구조화하는 방법론이다.

🏗️ 연계 전략

  • 도메인 모델 중심으로 API URI 설계

    • UserService → /users

    • OrderService → /orders

  • Bounded Context 단위 API 설계:

    • 각 서비스나 모듈은 독립된 경계를 가진다 → 마이크로서비스 설계와 연계

7.6 API Gateway와 BFF 패턴

🧩 API Gateway.

  • 모든 API 요청의 진입점 역할

  • 주요 기능: 인증, 라우팅, 속도 제한, CORS, 로깅

  • 예시 도구: AWS API Gateway, Kong, NGINX

🧩 BFF (Backend For Frontend).

  • 프론트엔드마다 맞춤형 API 제공

  • 모바일 vs 웹의 요청 양식이 다른 경우 효과적

  • 장점: 프론트 요구사항에 최적화 → 불필요한 데이터 제거

7.7 멀티팀/대규모 운영 전략

🧩 협업을 위한 명세 기반 개발.

  • Swagger/OpenAPI로 계약 기반 개발 → API 먼저 정의 → 구현 및 테스트 분리 가능

🧩 대규모 아키텍처 대응.

  • GraphQL Federation: 마이크로서비스 환경에서 GraphQL API 통합 전략

  • gRPC 정의서 관리: .proto 파일을 Git 저장소에서 버전 관리하며 코드 생성 자동화

8. API 성능 최적화 및 확장성 대응.

8.1 요청 최적화 전략

문제: N+1 쿼리 문제.

  • ORM 사용 시 반복된 DB 호출 발생 → 성능 저하

해결책

  • Join, Eager Loading, Batch Query 적용

  • DTO 사용으로 Projection 처리

8.2 응답 속도 개선

CDN, Redis, Reverse Proxy

  • CDN: 이미지/정적 리소스 분산 제공 → CloudFront, Cloudflare

  • Redis Cache: 빈번한 요청에 대한 API 응답 캐싱

  • Reverse Proxy: NGINX 활용 → 정적 리소스는 프록시 서버가 처리

  • ETag / Last-Modified: 변경 여부 체크 → 304 응답으로 불필요한 재전송 방지

8.3 Rate Limiting & Throttling

개념:

  • 과도한 요청 방지, 서비스 안정성 확보

적용 방식:

  • 사용자/토큰/IP 단위 제한

  • 구현 도구: NGINX, API Gateway, Redis + Express Rate Limit

limit_req_zone $binary_remote_addr zone=mylimit:10m rate=10r/s;
limit_req zone=mylimit burst=20;

8.4 비동기 큐 연계

왜 필요할까?

  • 요청-응답 과정에서 시간이 오래 걸리는 작업은 별도로 처리해야 성능이 유지됩니다.

적용 예시.

  • 이메일 전송, 이미지 리사이징, 통계 수집 등

  • 사용 도구: RabbitMQ, Kafka, AWS SQS

  • 방식: Producer → Queue → Consumer 처리

8.5 마이크로서비스 연동

API 간 통신 전략

  • RESTful, GraphQL, gRPC 등

장애 대응.

  • Circuit Breaker (Hystrix, Resilience4j 등): 장애 발생 시 자동 차단

  • Retry & Timeout 설정: axios-retry 등 클라이언트 레벨에서 설정 가능

profile
Data-Forge : 데이터로 세상 이해해보기.
Roll with the punches
이전 포스트

데이터를 그리기 위한 Front_End 공부하기 : React _ 02 == React.js vs Next.js [CSR vs SSR / SPA vs MPA / 리액트 라우터(React-Router)]

다음 포스트

데이터를 그리기 위한 Front_End 언어 공부하기 : JS _ 01 == 콜스택(CallStack)

0개의 댓글