[용어] RESTful API 란??

[용어] RESTful API 란??

 

generated by Gemini

 

 

안녕하세요!

 

최근에 RESTful API 문서를 정리하다가

 

이 정의에 대해서 정확하게 모르는 분들이 있을수도 있겠다 싶어서

 

내용을 정리해서 공유해보려고 준비해봤습니다!

 

간순한 API 라고 봐도 되지만, 목적에 따라 정확하게 분류하고 관리하는게 중점을 둔거라고 보고

 

아래 내용을 참고하시면 도움이 되실듯 합니다!

 

 

---

 

📚 개요 — RESTful API란?

 

REST(Representational State Transfer)는 웹의 분산 시스템 설계를 위한 아키텍처 스타일입니다.

RESTful API는 HTTP 프로토콜을 이용해 자원(Resource)을 URI로 표현하고, HTTP 메서드(동사)로 자원에 대한 행위를 수행하는 API를 말합니다.

핵심 목표는 단순성, 확장성, 캐시 가능성, 클라이언트-서버 분리입니다.

 

---

 

🧭 핵심 원칙 (REST의 제약조건)

 

• 자원(Resource): 모든 것은 리소스(예: /users/123, /orders/456)로 표현됩니다.
• 명확한 식별(URI): 각 리소스는 고유 URI로 식별됩니다.
• 표현(Representation): 서버는 JSON, XML 등으로 리소스의 표현을 반환합니다(보통 JSON).
• 무상태성(Stateless): 각 요청은 필요한 모든 정보를 포함해야 하며, 서버가 요청 간 클라이언트 상태를 저장하지 않음.
• 캐시 가능(Cacheable): 응답은 캐시 가능 여부를 명시해야 하며, 캐시 사용으로 성능 개선.
• 계층화된 시스템(Layered System): 클라이언트는 중간계층(로드밸런서, 프록시)을 통해 서버에 접근 가능.
• (선택적) HATEOAS: 응답에 관련 리소스 링크를 포함하여 API 사용을 유도(실무에서는 선택적으로 사용).

 

 

 

---

 

 

---

 

🔧 HTTP 메서드와 의미 (표준 매핑)

 

• GET — 리소스 조회 (안전·멱등)
• POST — 리소스 생성(또는 서버의 처리행위) (비멱등)
• PUT — 리소스 전체 교체(멱등)
• PATCH — 리소스 부분 수정(대체로 멱등으로 설계)
• DELETE — 리소스 삭제(멱등)
• HEAD, OPTIONS — 메타정보/교차출처(CORS) 등

멱등성(idempotency): 같은 요청을 여러 번 해도 결과가 동일해야 함(예: PUT, DELETE). POST는 보통 비멱등.

 

 

---

 

🧭 리소스/URI 설계 원칙

 

• 명사 사용: /users, /orders/{orderId} (동사 금지)
• 계층적 표현: /users/{userId}/orders
• 복수형 사용 권장: /products vs /product (팀 컨벤션 통일)
• 행동은 HTTP 메서드로: 리소스의 행위는 메서드에 위임
• 필터·정렬·페이징은 쿼리스트링: GET /products?category=books&sort=price_desc&page=2&limit=20
• 버전 관리: URL 버전(/v1/) 또는 헤더(Accept) 방식 — 보통 /api/v1/... 권장(명확성).

 

---

 

📦 응답 형식 & 상태 코드

 

• 표준 응답: JSON (권장) — { "data": {...}, "meta": {...}, "errors": [...] }
• HTTP 상태코드 활용:
  • 200 OK — 성공(조회/수정)
  • 201 Created — 생성 성공(응답에 Location 헤더로 새 리소스 URI 포함)
  • 204 No Content — 성공(응답 본문 없음; DELETE 후 등)
  • 400 Bad Request — 잘못된 요청(검증 실패)
  • 401 Unauthorized — 인증 실패(로그인 필요)
  • 403 Forbidden — 권한 없음
  • 404 Not Found — 리소스 없음
  • 409 Conflict — 자원 충돌(예: 중복 생성)
  • 422 Unprocessable Entity — 의미는 있으나 처리 불가(검증 상세정보 전송)
  • 429 Too Many Requests — 레이트 리밋 초과
  • 500/502/503 — 서버 오류/서비스 불가
• 에러 응답 예시:

{
  "errors": [
    {
      "status": 400,
      "code": "INVALID_EMAIL",
      "message": "email 형식이 올바르지 않습니다.",
      "field": "email"
    }
  ]
}

 

 

---

 

 

---

 

🔐 인증·인가(AuthN/AuthZ)

 

 

• Bearer Token (JWT): 간단하고 널리 사용. 단, 토큰 탈취 시 문제 → 만료/리프레시 정책 필요.
• OAuth2: 제3자 접근 허용(Authorization Code 등) — 표준 프로토콜.
• API Key: 서버간 통신(간단); 노출 위험 고려.
• Mutual TLS: 고보안 환경에서 클라이언트 인증용.
• 권한(Authorization): 역할 기반(RBAC)·리소스 기반 권한 체크(세밀한 권한 모델 설계 필요).

 

보안 팁: 항상 HTTPS 사용, 토큰은 안전하게 저장(브라우저에서는 HttpOnly 쿠키 vs Authorization header 고려).

 

 

---

 

📐 페이징·필터·정렬 패턴

 

• Offset 기반: ?page=2&limit=20 또는 ?offset=20&limit=20 — 구현 간단하지만 대규모 데이터에서는 성능 저하.
• Cursor 기반(권장 대규모): ?limit=20&cursor=eyJpZCI6... — 안정적이고 효율적(중간 삽입/삭제에도 일관된 페이지 결과).
• 정렬: ?sort=created_at,-price (플러스/마이너스 표기)
• 필터: ?status=active&min_price=100&max_price=500 또는 복잡 필터링은 JSON 쿼리(특수 엔드포인트)에 위임.

 

 

 

---

 

⚡ 캐싱 & 성능

 

• HTTP 캐시 헤더 활용: Cache-Control, ETag, Last-Modified
• CDN 사용: 정적 리소스·캐시 가능한 응답은 CDN 통해 제공
• 응답 압축: gzip/deflate/Brotli
• DB 쿼리 최적화 & 인덱스: N+1 방지, 적절한 인덱스 설계
• 비동기 처리: 오래 걸리는 작업은 비동기(큐/워크플로)로 처리하고 상태 확인 API 제공

 

 

---

 

 

---

🧯 에러 처리 & 로깅

 

• 표준화된 에러 포맷로 클라이언트가 파싱·처리하기 쉽게 설계
• 클라이언트에 민감정보 노출 금지 (스택트레이스 등)
• 서버 로깅/모니터링: 요청 ID(trace id)를 응답 헤더에 포함(X-Request-Id) → 분산 추적 가능
• SLA·재시도 전략: 클라이언트는 5xx 또는 타임아웃 시 적절한 백오프(지수적 재시도) 적용

 

---

 

🔄 버전관리(Versioning)

 

 

• URI 버전: /api/v1/... — 가장 명확, 캐시·라우팅 편리
• Header 버전: Accept: application/vnd.company.v1+json — URI 깨끗하지만 구현 복잡
• 무버전(버전 없는): 하위호환성 엄격 유지 필요(대형 변화 시 문제)
• 권장: 명확한 버전 정책 수립 및 오래된 버전 유지 기간 문서화.

 

---

 

🌐 HATEOAS(옵션)

 

 

응답에 관련 링크 포함:

{
  "data": { "id": 1, "name": "Alice" },
  "links": {
    "self": "/users/1",
    "orders": "/users/1/orders"
  }
}

 

장점: 클라이언트가 서버 상태 전이를 링크로 따라갈 수 있음. 실무에서는 모든 엔드포인트에 적용하기보다 핵심 리소스에 선택 적용.

 

 

---

 

🔓 보안 모범 사례

 

• HTTPS 강제(모든 엔드포인트)
• 입력 검증(서버측) 및 출력 이스케이프
• Rate limiting 및 IP 블록/스로틀 정책
• 민감정보 마스킹/암호화(전송/저장 모두)
• CORS 정책 최소화(정해진 도메인만 허용)
• 의존성 취약점 주기적 점검(SCA 도구 사용)
• 세션 탈취 대비: 짧은 토큰 만료, 리프레시 토큰 별도 보관

 

---

 

 

---

 

🧪 테스트·운영·문서화

 

• 자동화된 테스트: 단위(단일 핸들러), 통합, 계약 테스트(Consumer-Driven Contract)
• API 모니터링: 가용성·응답시간·에러율 알람(예: Prometheus + Grafana, New Relic)
• 로드 테스트: k6·JMeter로 병목 식별
• 문서화: OpenAPI(Swagger) 스펙 자동 생성 → 개발·테스트·클라이언트 SDK 생성에 유용
• 버전별 릴리즈 노트 & 호환성 가이드 제공

 

간단한 OpenAPI(요약) 예시:

openapi: "3.0.1"
info:
  title: Sample API
  version: "1.0.0"
paths:
  /users:
    get:
      summary: "사용자 목록 조회"
      parameters:
        - in: query
          name: page
          schema:
            type: integer
      responses:
        '200':
          description: OK

 

 

---

 

✅ 실전 예시 (간단한 CRUD)

 

• GET /api/v1/products → 제품 목록 (페이징/필터/정렬)
• GET /api/v1/products/{id} → 단일 제품
• POST /api/v1/products → 제품 생성 (201 + Location 헤더)
• PUT /api/v1/products/{id} → 전체 교체
• PATCH /api/v1/products/{id} → 부분 수정
• DELETE /api/v1/products/{id} → 삭제 (204 No Content)

 

POST /api/v1/products 요청 예:

POST /api/v1/products
Content-Type: application/json
Authorization: Bearer <token>

{
  "name": "무선 마우스",
  "price": 25000,
  "category": "electronics"
}

 

성공 응답:

HTTP/1.1 201 Created
Location: /api/v1/products/123

{
  "data": { "id": 123, "name": "무선 마우스", "price": 25000 }
}

 

 

---

 

⚠️ 자주 발생하는 실수 & 피해야 할 점

 

• 리소스를 지나치게 행위 중심으로 설계(예: /getUserById)
• 상태(세션)를 서버에 저장해 무상태성 위반
• 에러 메시지에 내부 구현(스택트레이스·DB 쿼리) 노출
• 버전 관리 없이 breaking change 바로 배포
• 인증·인가를 경시하여 엔드포인트 노출

 

---

 

📋 체크리스트 (배포 전 꼭 확인)

 

• API 설계 문서(OpenAPI) 존재하는가?
• HTTP 상태코드 적절히 사용되는가?
• 입력·출력의 스키마(스펙)가 고정되어 있는가?
• 인증·인가(권한) 로직은 철저한가?
• HTTPS, CORS, Rate limit 적용되어 있는가?
• 캐시 정책(ETag, Cache-Control) 정의되었는가?
• 로깅·분산 추적(Request ID) 구현되었는가?
• 테스트(단위·통합·부하) 통과했는가?
• 모니터링·알람(에러·지연) 세팅되었는가?

 

---

 

이렇게

 

RESTful API 가 무엇인지 자세히 알아봤습니다!

 

보안, 목적에 따라 명확하게 동작하고,

 

버전관리가 용이하도록 만들어서 관리하는 API 라고 보시면 될거 같네요! ㅎㅎ

 

다들 API 를 구성하실일이 있으시면 한번씩 참고들 하셨다가, 

 

유지보수 및 디버깅, 업데이트를 수월하게 하도록 설계를 잘 하시고 작업하시는걸 추천드립니다!

 

도움이 되셨다면, 구독/공감/댓글 부탁드립니다!

 

감사합니다!