웹 서비스 개발 – API 개발 기초 – 1 – API 설계 원칙

작성자 wooah
웹 서비스 개발 - API 개발 기초 - 1 - API 설계 원칙
웹 서비스 개발 – API 개발 기초 – 1 – API 설계 원칙

웹 서비스 개발 – API 개발 기초 – API 개념과 REST 아키텍처

안녕하세요! 😊
웹 개발을 시작하면서 가장 많이 듣는 단어 중 하나가 바로 **”API”**예요.
앱과 웹, 서버와 클라이언트가 서로 데이터를 주고받을 수 있도록 도와주는 소통의 다리라고 할 수 있어요.

이번 글에서는 API가 무엇인지, 그리고 요즘 대부분의 웹 서비스가 채택하고 있는 REST 아키텍처에 대해 알기 쉽게 풀어드릴게요!

API란 무엇인가요?

**API (Application Programming Interface)**는
서로 다른 소프트웨어끼리 **데이터나 기능을 주고받기 위한 약속(인터페이스)**입니다.

비유하자면,

“카페에서 커피를 주문할 때 바리스타에게 메뉴판을 보고 주문하는 것”과 같아요!
우리가 커피 종류(기능)를 골라 요청하면 바리스타(API)는 정확하게 만들어서 돌려주죠. ☕📋

예시

  • 날씨 앱: 기상청 API를 통해 오늘 날씨를 받아옴
  • 유튜브 앱: 영상 정보, 댓글, 좋아요 등 모두 API로 통신
  • 쇼핑몰: 결제, 상품 검색, 주문 내역 조회 등 API로 처리

API의 기본 동작 구조

  1. 요청(Request): 사용자가 어떤 데이터를 요청하거나, 작업을 수행해달라고 요청
  2. 처리(Processing): 서버에서 요청받은 내용을 이해하고 처리
  3. 응답(Response): 결과를 사용자에게 전달 (보통 JSON 형식)

REST란 무엇인가요?

REST는 REpresentational State Transfer의 약자로
웹에서 자원을 다루기 위한 표준 아키텍처 스타일이에요.

REST의 핵심 개념

구성 요소 설명
자원(Resource) URL로 표현되는 대상 (예: /users, /products/3)
행위(Method) HTTP 메서드로 표현 (GET, POST, PUT, DELETE 등)
표현(Representation) JSON, XML 등 데이터 표현 방식

REST 아키텍처의 원칙 6가지

  1. 클라이언트-서버 구조

    • 클라이언트는 UI, 서버는 데이터 관리

  2. 무상태성 (Stateless)

    • 요청 간에 상태를 저장하지 않음 (요청마다 필요한 정보 포함)

  3. 캐시 가능(Cacheable)

    • 응답은 캐시가 가능하도록 명시

  4. 계층화된 시스템

    • 중간 서버(프록시, 로드밸런서)를 사용할 수 있음

  5. 일관된 인터페이스

    • API는 동일한 규칙을 따름

  6. 요청에 따른 코드 실행 (선택 사항)

REST API 예시

작업 HTTP Method URL 예시 설명
사용자 목록 조회 GET /users 모든 사용자 조회
사용자 정보 조회 GET /users/5 ID 5번 사용자 조회
사용자 추가 POST /users 새 사용자 등록
사용자 수정 PUT /users/5 ID 5번 사용자 수정
사용자 삭제 DELETE /users/5 ID 5번 사용자 삭제

REST는 URL은 자원, HTTP Method는 행위를 나타냅니다!

RESTful API란?

REST 원칙을 잘 지켜서 만든 API를 RESTful API라고 부릅니다.

예를 들어:

  • GET /products → 상품 목록 조회
  • POST /products → 상품 등록
  • GET /products/10 → ID 10번 상품 보기

RESTful한 구조는 명확하고, 직관적이며, 재사용성이 좋습니다.

REST API의 장점

✅ 표준화된 구조: 누구나 쉽게 이해하고 사용할 수 있어요
✅ 유지보수 용이: 기능 추가나 변경이 간편
✅ 플랫폼 독립적: 웹, 앱, IoT 등 어디서든 사용 가능
✅ 확장성 우수: 마이크로서비스 등 다양한 구조에 유리

REST API의 응답 형식

보통 JSON 포맷으로 응답을 주고받습니다.

{
  "id": 5,
  "name": "홍길동",
  "email": "gildong@example.com"
}

에러가 날 경우:

{
  "error": true,
  "message": "잘못된 요청입니다."
}

JSON은 가볍고, 구조가 명확해 다양한 언어에서 쉽게 사용 가능합니다.

REST 외의 다른 API 방식

방식 특징
SOAP XML 기반, 보안이 강화됨, 무겁고 복잡
GraphQL 원하는 데이터만 요청 가능, 클라이언트 유연성 ↑
gRPC 고속 통신, 이진 포맷 사용, 복잡한 구조

하지만 현재는 REST가 대부분의 웹 서비스 표준으로 자리잡았답니다!

REST API 설계 시 주의할 점 ✅

항목 주의사항
URL 동사 사용 X, 자원 중심 (/getUser ❌ → /users ✅)
메서드 GET은 데이터 조회만! POST/PUT/DELETE 구분 정확히
상태코드 200, 201, 404, 400, 500 등 상황에 맞게 응답
데이터 포맷 JSON으로 통일하고, 일관된 구조 유지
인증 토큰 기반 인증 (JWT, OAuth 등) 적용 필요

마무리하며 😊

지금까지 API가 무엇인지, 그리고 RESTful API가 왜 중요한지를 함께 살펴보았습니다.
웹 개발자라면 반드시 이해하고, 능숙하게 다뤄야 할 핵심 개념이죠!

앞으로는 REST 아키텍처를 기반으로
실제 API를 어떻게 만들고, 테스트하고, 보안까지 챙기는지 하나씩 배워볼 예정이에요!

다음 시간에는 API 요청과 응답 처리 방법에 대해 자세히 알려드릴게요.
우리 모두 탄탄한 백엔드 개발자로 한 발짝 더 나아가 볼까요? 🚀💪

감사합니다~ 🙌✨

답글 남기기