[Winter Blog Challenge] 웹 API (Chapter Member 이하경)

안녕하세요! 😊 GDG on Campus SSWU Chapter Member 이하경입니다.

개발 공부를 하다 보면 API 설계, API 문서화, API 연동 등 API라는 단어를 자주 접하게 되죠.

이번 블로그에서는 그중에서도 "웹 API"에 대해 알아보려고 합니다! 🚀✨

 

1. API란?

• API(Application Programming Interface)는 서로 다른 소프트웨어 시스템이 상호작용 할 수 있게 해주는 인터페이스입니다.
• 데이터 처리 과정을 보면, 클라이언트는 사용자 인터페이스를 통해 데이터를 요청하고, 서버는 해당 요청을 처리하여 필요한 데이터를 응답으로 반환합니다.
  💡이때 API가 두 시스템이 데이터를 주고받을 수 있도록 다리 역할을 합니다.
  즉, 웹 API는 두 개 이상의 시스템이 서로 소통할 수 있게 해주는 다리 역할을 하여, 시스템 간에 필요한 데이터를 요청하고 받을 수 있게 해줍니다.
• 웹에서 사용되는 API는 HTTP를 통해 요청과 응답을 주고받으며, 가장 많이 사용되는 웹 API 중 하나는 RESTful API입니다.

2. API의 역할

1. 정보 교환
   • API는 데이터나 기능을 다른 시스템에서 가져오거나, 다른 시스템에 전달하는 역할을 합니다.
   • 예를 들어, 날씨 정보 API를 사용하면 다른 애플리케이션에서 실시간 날씨 데이터를 받아올 수 있습니다.
2. 시스템 간 연결
   • API는 서로 다른 시스템이나 플랫폼이 상호작용할 수 있도록 돕습니다. 이때 단순히 데이터를 주고받는 것에서 그치지 않고, 기능적 통합을 이루는 역할도 합니다.
   • 예를 들어, 구글 맵 API를 사용하면 애플리케이션은 위치 기반 서비스를 제공하는 기능을 구현할 수 있습니다.
     ⇒ 즉, 애플리케이션이 구글 맵의 기능을 호출해 시스템 간 연결이 이루어지게 되는 것입니다
3. 업데이트와 유지보수의 용이성
   • API를 사용하면 시스템을 업데이트하거나 변경할 때 외부 애플리케이션에 미치는 영향을 최소화할 수 있습니다.
   • 이는 추상화와 모듈화로 인해 실현됩니다.
   • 예를 들어, 날씨 정보를 제공하는 시스템이 내부 구조를 바꾸거나 데이터를 처리하는 방식을 변경하더라도, API를 사용하는 애플리케이션은 변화된 내부 구현에 대해 알 필요 없이 API 사용 방식만 알면 계속해서 작동할 수 있습니다.
     • 따라서 외부 애플리케이션은 API변경에 대해 받는 영향이 최소화될 수 있습니다.

3. API의 구성 요소

1. URL (Endpoint)

• 웹 API에서 리소스에 접근하는 주소입니다.

2. HTTP 메서드 (Request Method)

• 웹 API에서 수행할 작업을 정의하는 HTTP 메서드입니다.
  • GET: 리소스 조회
  • POST: 리소스 생성
  • PUT: 리소스 수정
  • DELETE: 리소스 삭제
  • PATCH: 리소스 부분 수정

3. 헤더 (Headers)

• 요청이나 응답에 대한 메타데이터를 포함합니다. 예를 들어, 인증 토큰이나 요청의 콘텐츠 유형 등을 정의할 수 있습니다.
  • 예: Content-Type: application/json, Authorization: Bearer <token>

4. 쿼리 파라미터 (Query Parameters)

• URL에 추가적인 정보를 전달하기 위한 파라미터입니다. 주로 GET 요청에서 사용됩니다.
  • 예: https://api.example.com/**users?page=2&limit=10**

5. 본문 (Request Body)

• POST, PUT, PATCH 요청 시 서버에 보낼 데이터입니다. 주로 JSON, XML, HTML, Form Data 형식으로 전송됩니다.
  • 예: { "name": "John", "email": "john@example.com" }

6. 응답 (Response)

• 서버가 클라이언트의 요청에 대해 반환하는 데이터입니다. 보통 JSON, XML 등의 형식으로 제공됩니다.
  • 예: { "id": 123, "name": "John", "email": "john@example.com" }

7. 상태 코드 (Status Code)

• 서버가 요청을 처리한 결과에 대한 상태를 나타내는 숫자 코드입니다.
  • 예:
    • 200 OK: 요청 성공
    • 201 Created: 리소스 생성 성공
    • 400 Bad Request: 잘못된 요청
    • 401 Unauthorized: 인증 실패
    • 404 Not Found: 리소스 없음
    • 500 Internal Server Error: 서버 오류

8. 응답 헤더 (Response Headers)

• 응답에 포함된 메타데이터로, 응답의 내용에 대한 정보나 추가적인 설정을 제공합니다.
  • 예: Content-Type: application/json, X-RateLimit: 1000

✔️ 추가로, 제가 웹 API를 공부하며 혼동이 왔던 “**API 설계”**와 “**API 사용”**에 대해서도 간략히 적었습니다 😊

• API 설계: 개발자가 자신의 애플리케이션을 위해 API를 설계하여 다른 시스템과의 데이터를 주고받는 것.
• 구글 맵 같은 외부 API 사용: 이미 설계된 외부 서비스(API)를 사용하여 그 서비스가 제공하는 데이터나 기능을 애플리케이션에서 활용하는 것.
  즉, 웹을 개발하면서 상황에 맞게 API 설계 & API사용을 적절히 하면 될 거 같습니다 ㅎ-ㅎ

4. API 설계 원칙

1. 일관성 (Consistency) 원칙

• URL 경로, HTTP 메서드, 응답 형식 등이 일관성 있게 유지되어야 사용자가 API를 쉽게 이해하고 활용할 수 있습니다.
  • 예)
    • GET /users: 사용자 목록을 조회합니다.
    • GET /users/{id}: 특정 사용자 정보를 조회합니다.
    • POST /users: 새 사용자를 생성합니다.
    • PUT /users/{id}: 특정 사용자의 정보를 업데이트합니다.
    • DELETE /users/{id}: 특정 사용자를 삭제합니다.

2. 명확한 문서화 (Clear Documentation)

• API 사용자가 API의 기능과 사용법을 정확히 이해할 수 있어야 합니다.
• 이를 위해 API는 명확하게 문서화되어야 하며, 각 엔드포인트가 어떤 작업을 수행하는지, 요청과 응답의 형식은 무엇인지 등 자세히 설명해야 합니다.

3. 버전 관리 (Versioning)

• API는 시간이 지나면서 변경될 수 있습니다.
• 따라서 버전 관리를 통해 이전에 사용하던 API가 중단되지 않고 계속 작동할 수 있도록 해야 합니다.

4. 보안 (Security)

• API는 중요한 데이터를 다루기 때문에 보안이 필수적입니다.
• 이를 위해 인증과 권한 부여를 사용해야 하며, 데이터 전송 시 암호화가 필요합니다.
  • API의 인증 방법
    • API Key: 간단한 인증 방식으로, 요청 시 고유한 키를 포함하여 API 접근을 인증합니다.
    • OAuth: API Key보다 강력한 인증 방식으로 사용자가 자신의 계정 정보를 제공하지 않고, 다른 서비스(구글, 네이버 등)를 통해 인증합니다.
      • 즉, , 권한 위임을 통해 특정 자원에 대한 접근 권한을 부여합니다.
    • JWT (JSON Web Token): 서버에서 발급한 토큰을 클라이언트가 보관하고, 이후 요청 시 이 토큰을 사용하여 인증하는 방식입니다.

5. RESTful API

• REST(Representational State Transfer): 웹에서 클라이언트와 서버가 데이터를 주고받는 방식(아키텍처)
  • REST의 6가지 원칙
    • 1️⃣ 클라이언트-서버 구조 (Client-Server)
      • 클라이언트: 요청을 보냄 (웹 브라우저, 앱 등)
      • 서버: 요청을 받아 처리하고 응답을 반환
    • 2️⃣ 무상태성 (Stateless)
      • 서버는 요청마다 "독립적"으로 처리해야 함
      • 즉, 이전 요청 상태를 기억하지 않음
  • 3️⃣ 캐시 가능 (Cacheable)
    • 동일한 요청에 대해 서버가 매번 새로 처리하면 비효율적
    • 따라서 클라이언트/서버에서 캐시를 활용 가능
  • 4️⃣ 계층적 시스템 (Layered System)
    • API 요청이 여러 계층(로드 밸런서, 인증 서버 등)을 거칠 수 있음
    • 사용자는 시스템 내부 구조를 몰라도 됨
  • 5️⃣ 일관된 인터페이스 (Uniform Interface)
    • 리소스(URL)와 HTTP 메서드 활용
  • 6️⃣ 코드-온-디맨드 (Code on Demand, 선택 사항)
    • 필요하면 서버에서 클라이언트로 실행 가능한 코드(JavaScript 등)를 전송 가능
    • 잘 사용되지는 않음 (REST 필수 요소 X)
    ⇒ 위 6가지 원칙을 지키면 RESTful API가 됩니다.
  • REST API vs RESTful API
         ✔RESTful API: REST의 모든 원칙을 충실히 지킨 API
         ✔REST API: 단순히 REST 스타일을 따른 API
• RESTful API의 장점과 단점
  • 장점:
    1. 설계가 간단하고 직관적입니다.
    2. HTTP 메서드를 그대로 사용하므로 이해하기 쉽고, 서버와 클라이언트 간의 명확한 분리가 가능합니다.
  • 단점
    1. RESTful API는 종종 하나의 작업에 필요한 여러 데이터를 각기 다른 API 엔드포인트에서 여러 번 요청해야 할 수 있습니다.
    • 예) 사용자의 기본 정보, 친구 목록, 최근 활동 요청
      • 사용자의 기본 정보, 친구 목록, 최근 활동을 각각 다른 API 엔드포인트에서 요청해야 할 수 있습니다.
        • /users/{id} (사용자 정보)
        • /users/{id}/friends (친구 목록)
        • /users/{id}/activities (사용자 활동)
        ⇒ 여러 번의 API 호출은, 네트워크 비용이나 응답 시간을 늘릴 수 있고, 특히 모바일 네트워크 환경에서는 성능 저하를 유발할 수 있습니다.
      📌 Under-fetching: 클라이언트가 필요한 데이터를 한 번의 요청으로 모두 받지 못하고, 여러 번의 요청을 추가로 보내야 하는 경우
    1. RESTful API는 고정된 형식으로 응답을 반환합니다.
    • 예를 들어 하나의 자원에 대한 응답이 항상 동일한 필드를 포함하고 있다면, 클라이언트가 그 중 일부만 필요하더라도 불필요한 데이터를 포함해 응답을 받게 됩니다.
    • 예)
      
      • /users/{id} 요청을 했을 때 응답으로 "사용자 정보"와 함께 불필요한 "활동 내역"이나 "친구 목록"까지 포함된 데이터를 반환하면, 클라이언트는 그 중 일부만 사용하게 됩니다.
        ⇒ 데이터 전송이 비효율적이고, 클라이언트 측에서 데이터를 파싱하는 데 불필요한 작업이 발생할 수 있습니다.
        
        • 📌 Over-fetching: 클라이언트가 실제로 필요한 데이터보다 많은 데이터를 받는 경우

6. API 사용 사례

• 몇 가지 API 주요 사용 사례
  1. 소셜 미디어 API: Twitter API나 Facebook API를 사용하여 다른 애플리케이션에서 사용자의 소셜 미디어 데이터를 가져오거나, 사용자가 소셜 미디어에 게시물을 올릴 수 있도록 할 수 있습니다.
  2. 날씨 정보 API: OpenWeatherMap API를 사용하여 애플리케이션에서 실시간 날씨 정보를 받아올 수 있습니다.
  3. 결제 시스템 API: Stripe API나 PayPal API를 통해 애플리케이션에서 결제 시스템을 통합할 수 있습니다.
  4. 지도 서비스 API: Google Maps API를 사용하여 애플리케이션에 지도 서비스를 통합할 수 있습니다.

결론!

API는 소프트웨어를 확장 가능하고 유연하게 만드는 핵심 요소로서 현대 소프트웨어 개발에서 중요한 역할을 하며, 서로 다른 시스템 간의 통신을 가능하게 해줍니다. API 설계 시 일관성, 문서화, 보안을 고려해야 하며, 이를 통해 효율적이고 안전한 시스템을 만들 수 있습니다.

 

이상으로 웹 API에 대한 포스팅을 마치겠습니다~~👋🏻