API / RESTful API / GraphQL

API ( Application Programming Interface)

애플리케이션과 애플리케이션 간의 통신을 가능하게 해주는 인터페이스이다.

다른 말로 애플리케이션 간의 상호작용을 정의한 규격이다.

 

주요 특징은

- 추상화  

내부 동작을 숨기고, 필요한 기능만 노출하여 복잡성을 줄인다.

 

- 데이터 교환

데이터를 요청하고 응답하는 방식으로 소프트웨어 간의 통신을 가능하게 한다.

 

- 표준화

API를 통해 개밸자는 특정 규격에 따라 작업을 수행할 수 있다.

 

* Interface 정의는

컴퓨터 시스템이나 소프웨어 등 서로 다른 구성 요소들이 상호작용할 수 있도록 정의된 경계 나 접점을 의미한다. 인터페이스는 프로그래밍, 시스템 설계, 그리고 사용자 경험 등 다양한 맥락에서 사용되며, 입력과 출력의 명확한 규칙을 제공한다.

일반적으로 매개체 역할, 표준화, 그리고 추상화의 정의로 사용된다.

ex) UI : 사용자와 시스템 간의 상호작용 접점을 의미

GUI : 버튼 ,창 , 아이콘 등 시각적인 요소를 통해 상호작용

CLI : 텍스트 명령어를 통해 시스템과 상호작용

 

---

 

RESTful API 

REST (Representation State Transfer) 아키텍쳐 스타일을 따르는 API 를 의미한다.

REST 는 HTTP 프로토콜을 기반으로 클라이언트와 서버가 통신하는 방식을 정의한다.

 

REST 의 주요 원칙

1. Resource 기반 설계

Restful API는 모든 데이터나 기능을 " 자원 " 으로 간주한다.

그래서 각 자원은 고유한 URI (Uniform Resource Identifier ) 을 통해 식별된다

ex) /user/1 (1번 사용자 정보)

 

2. HTTP Method 사용

HTTP의 표준 방법을 사용하여 자원에 대한 작업을 정의한다.

- GET: 자원 조회.
- POST: 자원 생성.
- PUT: 자원 전체 업데이트.
- PATCH: 자원 일부 업데이트.
- DELETE: 자원 삭제.

 

3. Stateless ( 무상태성 )

서버는 클라이언트의 상태를 저장하지 않는다. 각각의 요청은 모두 독립적으로 처리되며, 필요한 모든 정보가 각 요청마다 포함되어야 한다.

ex) 인증 토큰은 매번 요청을 할 때마다 포함되어야 함.

 

4. Representation ( 표현 계층 )

자원은 다양한 형태 JSON, XML, HTML 등으로 표현될 수 있으며, 클라이언트가 요청한 방식에 따라 응답하게 된다.

 

5. 캐시 처리

자원에 대한 응답은 캐시 가능해야 하며, HTTP 캐시 헤더를 통해 이를 명시한다.

 

6. Layered System ( 계층화 시스템)

클라이언트는 중간 서버 (프록시, 로드 밸런서 등)을 통해 최종 서버와 통신할 수 있다.  

 

 

RESTful API 장점

- 유연성

JSON, XML 등 다양한 데이터 형식을 지원한다.

 

- 표준화

HTTP 방식과 상태 코드를 활용하여 직관적이고 이해하기 쉽다.

 

- 확장성

계층 구조를 활요하기 때문에 확장이 용이하다

 

ex)

요청 : 특정 사용자 정보 조회

GET /users/1 HTTP/1.1
Host: api.example.com
Authorization: Bearer <token>

 

응답 :

{
  "id": 1,
  "name": "John Doe",
  "email": "john.doe@example.com"
}

 

 

---

 

GraphQL

Facebook (Meta) 에서 개발한 데이터 쿼리 언어로 클라이언트가 필요한 데이터를 정확히 요청 할 수 있도록 설계되었다.

RESTful API 와는 다른 접근방식을 제공한다. 

 

GraphQL의 주요 개념

- 스키마 기반 설계
GraphQL 서버는 데이터 구조를 스키마로 정의하며, 클라이언트는 이 스키마를 참고해 쿼리를 작성한다.

- 단일 엔드포인트
RESTful API와 달리, GraphQL은 단일 엔드포인트(/graphql)를 통해 모든 요청을 처리합니다.

- 클라이언트 주도 쿼리
클라이언트가 필요한 데이터를 선택적으로 요청할 수 있습니다.
예: 사용자 정보와 함께 주문 목록만 요청.

- 유형(Type) 시스템
GraphQL은 엄격한 타입 시스템을 사용하여 API의 구조를 정의합니다.
예: User, Order와 같은 데이터 유형을 정의.

- 효율성
클라이언트가 필요한 데이터만 가져올 수 있어 Overfetching(불필요한 데이터 요청)과 Underfetching(필요한 데이터 부족) 문제를 해결합니다.

 

 

주요 요소

1. Query

데이터를 요청하는방식

 

query {
  user(id: 1) {
    name
    email
    orders {
      id
      total
    }
  }
}

 

2. Mutation 

데이터를 생성하거나 수정할 때 사용

mutation {
  createUser(name: "John Doe", email: "john.doe@example.com") {
    id
    name
  }
}

 

3. Subscription

서버에서 클라이언트로 실시간 데이터를 푸시

주로 WebSocket 을 통해 구현

 

GraphQL 의 장점

- 유연성

클라이언트가 필요한 데이터만 요청 가능

- 단일 요청

하나의 요청으로 복잡한 데이터 구조를 가져올 수 있음

- 실시간 데이터

Subscription 을 통해 실시간 데이터 제공

 

GraphQL의 단점

- 복잡성 증가

서버와 클라이언트 모두 스키마와 쿼리 설계를 신경 써야함

 

- 오버헤드

큰 데이터 구조를 요청하면 성능에 영향을 줄 수 있다.

 

 

GraphQL 예시   

요청 : 특정 사용자 정보와 주문 목록 조회

query {
  user(id: 1) {
    id
    name
    email
    orders {
      id
      product
      price
    }
  }
}

 

응답 :

{
  "data": {
    "user": {
      "id": 1,
      "name": "John Doe",
      "email": "john.doe@example.com",
      "orders": [
        { "id": 101, "product": "Laptop", "price": 1200 },
        { "id": 102, "product": "Mouse", "price": 20 }
      ]
    }
  }
}

 

 

결론적으로 

RESTful API 는 단순하고 표준화된 HTTP 기반 API 를 제공하며, 소규모 및 단순한 애플리케이션에 적합하다

GraphQL 은 데이터 요구 사항이 복잡하거나 실시간 데이터를 처리해야하는 프로젝트에 유용하다.

 

 

---

+ 추가적인 용어 정리

1. 캐시 ( Cache )

캐시는 자주 사용되는 데이터를 빠르게 제공하기 위해 저장하는 임시 저장소

이는 성능 향상, 응답 속도 개선, 서버 부하 감소 등의 목적으로 사용된다.

 

캐시의 주요 원리는

자주 사용되는데이터를 캐시에 저장하여 동일한 요청에 대해 빠르게 응답할 수 있게 한다.

그리고 일정 시간이 지나거나 변경이 발생하면 캐시를 갱신 (무효화) 한다.

 

 캐시의 종류

1) 클라이언트 캐시

브라우저에서 데이터를 저장하여 다시 요청하지 않도록 함 (ex : 웹 브라우저 캐시)

 

2) 서버 캐시 : 웹 서버에서 요청을빠르게 처리하기 위해 데이터를 저장 ( ex: Redis, Memcached)

 

3) CDN 캐시: 전 세계에 분산된 서버가 자주 요청되는 데이터를 저장하여 제공 ( ex: Cloudflare, Akamai)

 

 

2. HTTP Cache Header

HTTP 캐시 헤더는 웹 브라우저나 프록시 서버가 요청 및 응답을 캐싱하는 방법을 저장하는 헤더이다.

 

- 주요 HTTP 캐시 헤더

   1) Cache - Control 

캐시 동작을 제어하는 핵심 헤더

Cache-Control: no-cache → 캐시된 데이터를 사용하지 않고 서버에서 새로 가져옴.
Cache-Control: max-age=3600 → 3600초(1시간) 동안 캐시 유지.
Cache-Control: public → 누구나 캐시 사용 가능.
Cache-Control: private → 특정 사용자만 캐시 사용 가능.

 

2) Expires 

캐시 만료 날짜 지정 (HTTP / 1.0)

Expires: Wed, 21 Oct 2025 07:28:00 GMT

 

3) ETag

데이터 변경 여부를 확인하는 고유 식별자 제공

ETag: "5b9f8a3c-6c3f" (데이터가 변경되면 새로운 ETag 값이 생성됨)

 

4) Last - Modified 

마지막으로 수정된 날짜 제공

Last - Modified: Tue, 20 Jun 2023 15:29:00 GMT

 

 

3. 중간 서버 ( Intermediate Server)

중간서버는 클라이언트와 서버 사이에서 데이터 흐름을 관리하는 서버이다.

이를 통해 부하 분산, 보안 강화 그리고 성능 개선 등의 역할이 수행된다.

 

중간 서버의 역할

캐싱 : 자주 요청되는 데이터를 저장하여 빠른 응답 제공 

보안 강화 : 프록시 서버를 사용하여 직접적인 서버 접근 차단

부하 분산  :여러 서버에 요청을 나누어 처리

 

 

4. 프록시 (Proxy)

프록시는 클라이언트와 서버 사이에서 요청을 중계하는 서버이다.

 

- Forward Proxy

클라이언트가 직접 서버에 요청하는 대신  프록시 서버를 거쳐서 요청을 보낸다

보안, 콘텐츠 필터링 그리고 캐싱 등에 사용된다.

ex) 회사 내부망에서 외부 인터넷 접속 시 프록시 사용

 

- Reverse Proxy

클라이언트는 프록시 서버를 통해 백엔드 서버에 요청을 전달받는다.

로드 밸런싱, 보안 강화 캐싱 역할을 수행한다.

예: Nginx, Apache Reverse Proxy.

 

5. Load Balancer

다수의 서버에 요청을 균등하게 분배하는 역할을 한다.

즉, 서버에 과부하가 걸리는것을 방지하고 성능을 최적화 시킨다.

 

- 로드 밸런싱 방식

1) Round Robin

 요청을 순차적으로 여러 서버에 배분하는 방식

2) Weighted Load Balancing

성능이 더 좋은 서버에 더 많은 요청을 할당하는 방식 

3) IP Hashing

특정 클라이언트의 요청을항상 동일한 서버로 보내는 방식

4) Least Connection

현재 가장 적은 연결을 가진 서버로 요청을 분산

 

그외에도

소프트웨어 기반: Nginx, HAProxy.
하드웨어 기반: F5, Citrix.

이 있다. 

 

6. HTTP Status Code

클라이언트 요청에 대한 서버의 응답을 나타내는 코드

주요 상태 코드
1) 2xx (성공)
200 OK: 요청 성공.
201 Created: 새 리소스 생성 완료.

2) 3xx (리디렉션)
301 Moved Permanently: 리소스가 영구적으로 이동됨.
304 Not Modified: 캐시된 데이터를 사용하라는 응답.

3) 4xx (클라이언트 오류)
400 Bad Request: 잘못된 요청.
401 Unauthorized: 인증이 필요함.
403 Forbidden: 접근 권한 없음.
404 Not Found: 리소스를 찾을 수 없음.

4) 5xx (서버 오류)
500 Internal Server Error: 서버 내부 오류 발생.
502 Bad Gateway: 게이트웨이 또는 프록시 서버 문제.
503 Service Unavailable: 서버가 과부하 상태.

 

7. Schema (스키마)

데이터 구조를 정의하는 설계 문서 또는 규칙을 의미한다.

- 데이터베이스 스키마

데이터베이스에서 테이블, 컬럼, 데이터 타입을 정의하는 구조  

CREATE TABLE Users (
  id INT PRIMARY KEY,
  name VARCHAR(100),
  email VARCHAR(100) UNIQUE
);

 

8. Query

데이터를 검색하거나 조작하는 요청을 의미한다.

 

9. Endpoint

API 가 요청을 받을 수 있는 URL 주소를 의미한다

- RESTful API 엔드포인트 예시
GET /users → 모든 사용자 목록 조회.
GET /users/{id} → 특정 사용자 조회.
POST /users → 새 사용자 추가.

- GraphQL 엔드포인트 예시
POST /graphql → 모든 GraphQL 요청을 처리하는 단일 엔드포인트.

 

---

 

캐시는 데이터를 임시 저장하여 성능을 향상키려 하고
HTTP 캐시 헤더는 데이터를 캐싱하는 방법을 지정한다.
프록시는 클라이언트와 서버 간 중개 역할을 하며
로드 밸런서는 여러 서버로 트래픽을 분산시킨다.
HTTP 상태 코드는 요청 결과를 나타내며
스키마는 데이터 구조를 정의한다.
쿼리는 데이터를 요청하는 명령을 의미하며
엔드포인트는 API가 요청을 처리하는 URL이다.