API 개념과 원리

API란?

API(Application Programming Interface)는 프로그램이나 시스템끼리 정보를 주고받을 수 있도록 미리 정한 약속입니다. 쉽게 말해 서로 다른 시스템이 대화하는 방법과 규칙을 정한 것입니다.

예를 들어, 웹이나 앱에서 날씨 정보를 가져오거나, 사용자의 정보를 받아올 때 API를 통해 서로 데이터를 주고받게 됩니다.

---

API의 동작 방식 (클라이언트-서버 구조)

API는 기본적으로 클라이언트(Client)와 서버(Server)가 서로 요청(Request) 과 응답(Response) 을 주고받으며 통신합니다.

클라이언트(Client)와 서버(Server)

• 클라이언트(Client)
  데이터를 요청하는 주체입니다.
  예시: 브라우저, 모바일 앱, 다른 서비스 등.
• 서버(Server)
  클라이언트의 요청을 받아 처리하고 데이터를 제공하는 주체입니다.
  예시: 웹 서버, API 서버, 데이터베이스를 연결한 서버 등.

이 둘이 서로 소통하는 과정에서 사용하는 것이 바로 API입니다.

---

요청(Request)과 응답(Response)

클라이언트와 서버는 API를 통해 데이터를 주고받으며 통신합니다.
이때 클라이언트가 서버에게 보내는 것을 요청(Request), 서버가 처리 후 돌려주는 것을 응답(Response)이라고 합니다.

---

요청(Request)

클라이언트가 서버에 특정 자원을 얻거나 생성, 수정, 삭제하기 위해 전달하는 메시지입니다.

요청(Request)의 세부 구성 요소

요청은 크게 시작 줄(Start Line), 헤더(Header), 바디(Body) 로 구성됩니다.

① 시작 줄(Start Line)

HTTP메소드 URI HTTP버전

예시:

GET /users/1 HTTP/1.1

• HTTP 메소드: 요청의 목적을 나타냅니다.

메소드	의미	사용 예시
GET	데이터 조회	GET /users
POST	데이터 생성	POST /users
PUT	데이터 전체 수정	PUT /users/{id}
PATCH	데이터 일부 수정	PATCH /users/{id}
DELETE	데이터 삭제	DELETE /users/{id}

• URI(Uniform Resource Identifier): 요청 대상 자원을 나타냅니다.
• HTTP 버전: 대부분 HTTP/1.1 또는 HTTP/2 사용.

② 헤더(Header)

헤더는 요청에 대한 추가적인 정보를 전달합니다.

자주 사용되는 헤더 예시:

헤더(Header) 이름	설명	예시
Host	요청하는 서버의 도메인	Host: api.example.com
Accept	클라이언트가 받을 수 있는 데이터 타입	Accept: application/json
Content-Type	요청의 바디에 담긴 데이터의 형식	Content-Type: application/json
Authorization	인증을 위한 토큰이나 자격증명 전달	Authorization: Bearer eyJ...

헤더 예시:

GET /users/1 HTTP/1.1
Host: api.example.com
Accept: application/json
Authorization: Bearer eyJ...

③ 바디(Body)

바디는 주로 POST, PUT, PATCH 같은 메소드로 데이터를 생성하거나 수정할 때 사용합니다.

바디 예시(JSON):

{
  "username": "홍길동",
  "email": "hong@example.com"
}

• GET, DELETE 요청은 일반적으로 바디를 사용하지 않습니다.
• PUT 요청은 대부분 모든 필드를 보내는 전체 수정
• PATCH 요청은 필요한 필드만 보내는 부분 수정

---

응답(Response)

서버가 클라이언트의 요청을 처리한 결과를 클라이언트에 전달하는 메시지입니다.

응답(Response)의 세부 구성 요소

응답은 상태 줄(Status Line), 헤더(Header), 바디(Body) 로 구성됩니다.

① 상태 줄(Status Line)

HTTP버전 상태코드 상태메시지

예시:

HTTP/1.1 200 OK

• 상태 코드: 서버가 요청을 어떻게 처리했는지를 나타냅니다.

코드	의미	설명
200	OK	성공적으로 처리됨
400	Bad Request	요청에 문제가 있음
401	Unauthorized	인증되지 않음
403	Forbidden	권한 없음
404	Not Found	요청한 자원이 존재하지 않음
500	Internal Server Error	서버 내부 오류 발생

② 헤더(Header)

응답 데이터에 대한 정보나 지시사항을 담습니다.

헤더(Header) 이름	설명	예시
Content-Type	응답의 데이터 형식	Content-Type: application/json
Content-Length	데이터의 길이(byte)	Content-Length: 256
Date	응답 생성 시간	Date: Mon, 25 Mar 2025 12:00:00 GMT
Set-Cookie	클라이언트에 쿠키 전달	Set-Cookie: sessionId=abc123

응답 헤더 예시:

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 128
Date: Mon, 25 Mar 2025 12:00:00 GMT

③ 바디(Body)

바디는 실제 클라이언트가 요청한 데이터를 담고 있습니다. 

예시(JSON):

{
  "id": 1,
  "username": "홍길동",
  "email": "hong@example.com"
}

 

• 응답 바디는 보통 JSON 형식을 사용하며,
• 상태 코드에 따라 에러 메시지 등을 담기도 합니다.

 

 

 

---

요청과 응답 흐름 예시

다음은 날씨 정보를 요청하는 클라이언트와 서버 간 통신 예시입니다.

클라이언트 → 서버 (요청 예시)

GET /weather/today?city=Seoul HTTP/1.1
Host: api.weather.com
Accept: application/json
Authorization: Bearer [token값]

 

• 메소드: GET (데이터 조회)
• URI: /weather/today?city=Seoul
• 헤더: Accept(받고 싶은 데이터 타입), Authorization(인증 정보)

서버 → 클라이언트 (응답 예시)

HTTP/1.1 200 OK
Content-Type: application/json

{
  "city": "Seoul",
  "date": "2025-03-25",
  "temperature": 18,
  "weather": "맑음"
}

• 상태 코드: 200 (정상 처리)
• 헤더: Content-Type (응답 데이터 형식)
• 바디: 실제 날씨 데이터(JSON 형식)

---

API와 REST API의 연관성

API는 데이터 교환의 일반적인 개념을 의미하고, REST API는 API를 설계하는 구체적인 방식을 나타냅니다.

즉, REST API는 API를 만드는 다양한 방법 중에서 가장 널리 쓰이는 스타일입니다.

• 자원(Resource): REST API는 URL로 자원을 표현합니다. (예: /users, /products)
• HTTP 메소드: REST API는 자원을 처리하기 위해 HTTP 메소드(GET, POST 등)를 적극적으로 활용합니다.
• 상태 코드: 클라이언트는 응답의 상태 코드를 통해 요청 결과를 이해합니다.

REST API 개념과 예시 (스프링부트)

 

---

JSON과 XML, 그리고 API와의 연관성

데이터를 주고받을 때, JSON이나 XML이 주로 사용됩니다.
API의 응답(Response)은 대부분 JSON을 사용하며, 요청(Request)의 본문(Body)도 JSON을 사용하는 경우가 많습니다.

• JSON은 API 통신에서 가장 보편적으로 사용되는 데이터 형식입니다.
• XML은 과거에는 주류였으나, 최근에는 JSON이 더 많이 사용됩니다.

예를 들어 REST API 요청과 응답은 대부분 JSON 형식을 취하게 됩니다.

데이터 교환 형식

 

---

API의 주요 개념들의 관계를 정리하면 다음과 같습니다.

• 클라이언트가 서버에 요청(Request)을 보낸다.
• 요청에는 메소드(GET, POST), URI(/users), 헤더, 바디 등이 포함된다.
• 서버는 요청을 받아 처리하고, 결과를 담아 응답(Response)을 보낸다.
• 응답에는 상태 코드(200), 헤더, 바디(JSON) 등이 포함된다.
• 이러한 요청과 응답의 과정을 통해 클라이언트와 서버는 API를 사용하여 데이터를 주고받는다.
• REST API는 이 API 설계 방법 중 가장 널리 쓰이는 형태로, 자원 중심적이고 직관적이며 HTTP 메소드와 상태 코드를 적극 활용한다.
• 데이터의 표현 방식으로 주로 JSON을 사용한다.