[ 멋쟁이사자처럼부트캠프 그로스마케팅 부트캠프 ] API의 정의와 예시

1. API의 정의

• API( Application Programming Interface )는 애플리케이션 간의 데이터를 주고받고 기능을 호출할 수 있도록 하는 인터페이스임. 이를 통해 기업은 외부 서비스와 연동하여 데이터를 수집하고, 마케팅 자동화를 구현하며, 맞춤형 고객 경험을 제공할 수 있음.
  • 인터페이스는 서로 다른 프로그램이 데이터나 기능을 주고받을 수 있게 하는 약속임.
  • ex. 종업원은 고객과 주방 사이의 인터페이스임. 고객이 주문을 하면 종업원은 주문을 주방에 전달, 주방은 고객이 요청한 음식을 종업원을 통해 고객에게 다시 전달함. 
• API는 완결된 프로그램이 아닌, 프로그램 간 연결고리임. 즉 기능을 호출할 수 있는 명령어 집합이자 데이터를 주고받을때 사용하는 약속이자 형식임.

 

 

2. API의 구성 요소

 

1) 엔드포인트( EndPoint )

• API에서 호출할 수 있는 URL 주소임
• 클라이언트(고객)은 엔드포인트를 통해 서버(주방)에 요청을 보냄
  • https://example.com/users  =>  사용자 정보를 가져오는 엔드포인트 

 

2) HTTP 메서드

• HTTP는 웹에서 데이터를 주고받는 규칙(프로토콜)이고, HTTP 메서드는 HTTP가 지원하는 요청 방법임
• 클라이언트 요청부터 서버 응답까지 HTTP 규칙을 기반으로 진행되며, 따라서 서버에 요청하는 방식도 HTTP 메서드임
• HTTP 메서드 종류
  • GET: 데이터 조회
  • POST: 데이터 생성
  • PUT: 전체 데이터 수정
  • PATCH: 일부 데이터 수정
  • DELETE: 데이터 삭제

 

3) 요청( Request )

• 클라이언트가 API에 보내는 데이터
• 요청할 때 헤더( Header ), 본문( Body ), 파라미터( Parameter ) 등이 포함됨
• 특히 POST, PUT, PATCH 요청 시 본문( Body )에 보낼 데이터를 포함함
• 아래는 클라이언트의 GET 요청의 예

GET /image API/endpoint HTTP/1.1
Host: www.example.com
Accept: image/jpeg, image/png
User-Agent: Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/91.0.4472.124 Safari/537.36

 

• GET /image API/endpoint HTTP/1.1 : API에서 이미지를 제공하는 엔드포인트( image )로 GET 요청을 보냄
• HOST: www.example.com :  서버의 주소
• Accept : 클라이언트가 받을 수 있는 미디어 타입을 명시. 이미지 형식( image/jpeg, image/png 등)
• User-Agent: 요청을 보낸 브라우저에 대한 정보

 

 

4) 응답( Response )

• API가 클라이언트에게 보내는 결과임
• HTTP 상태 코드와 데이터(본문)으로 구성됨

200	요청 성공	400	잘못된 요청	404	요청한 리소스 없음
201	데이터 생성 성공	401	인증 실패 (로그인 필요)	500	서버 오류

 

 

 

5) 인증( Authentication )과 권한( Authorization )

• API 보안을 위해 사용됨
• API 키, 토큰 등을 통해 인증하고 권한도 설정

HTTP 형식의 구조(화살표를 가능하게 하는 것이 API)

 

 

 

3. API 예시

from flask import Flask, request, jsonify

app = Flask(__name__)   # Flask 객체 생성

# 데이터 (예시)
users = [
    {"id": 1, "name": "Mr.Kim", "email": "kimkim@example.com"},
    {"id": 2, "name": "Mr.Jung", "email": "jungjung@example.com"}
]

# GET 요청 - 사용자 목록 조회
@app.route('/users', methods=['GET'])   # /users에 대한 요청이 오면 아래 함수 실행
def get_users():
    # 요청 헤더 예시: Accept는 JSON 형식 요청
    if request.headers.get('Accept') == 'application/json':
        return jsonify(users), 200
    else:
        return "Accept header must be application/json", 400

if __name__ == '__main__':    # 직접 모듈이 실행될 때 아래 블록 실행
    app.run(debug=True)

 

 

위 코드에서의 API 구성 요소

 

1) 요청

• /users 엔드포인트에 GET 요청을 보내면 모든 사용자 목록을 응답으로 받음( jsonify(users) )

2) 응답

• 상태 코드 : 요청 처리 결과에 따라 응답에 포함됨. 예를 들어 200, 400 등이 있음
• 헤더 : 요청에서의 Accept: application/json 헤더를 확인하여 서버가 JSON 형식의 응답을 보내도록 함
• 본문: 응답 본문에 JSON 형식으로 데이터를 포함하여 클라이언트에게 보냄

 

 

동작예시

 

1) GET 요청(클라이언트 => 서버)(HTTP)

GET /users HTTP/1.1
Host: localhost:5000
Accept: application/json

 

 

2) API에 /users 엔드포인트 있는지 확인, 있으면 함수 실행, 없으면 404(요청한 리소스 없음) 오류 반환

return jsonify(users), 200

 

 

3) 서버 응답(서버 => 클라이언트)(json)

[
    {"id": 1, "name": "John Doe", "email": "john@example.com"},
    {"id": 2, "name": "Jane Smith", "email": "jane@example.com"}
]

 

 

 

정보 전달 과정

 

 

1) 클라이언트(브라우저)에서 주소 입력

• 사용자가 브라우저의 주소창에 http://30.20.10.10:5000/users를 입력. 이때 클라이언트는 서버로 HTTP 요청을 보내기 위한 준비를 시작함.

 

2) 브라우저에서 URL 분석

• 주소창에 입력된 http://30.20.10.10:5000/users를 바탕으로 브라우저는 다음과 같은 정보를 분석함.
  • 프로토콜: http:// (http 프로토콜을 사용)
  • 호스트: 30.20.10.10(이 요청은 로컬에서 실행되는 서버로 보내지며, 서버는 해당 포트를 통해 응답)
  • 포트: 5000(30.20.10.10:5000은 포트 5000에서 서버가 실행중임을 의미)
  • 경로: /users (서버에서 이 경로를 처리하는 엔드포인트가 있는지 확인)

 

3) 클라이언트가 서버에 HTTP 요청을 보냄

• 이제 브라우저는 HTTP 요청 메시지를 서버로 전송함. 여기서 요청 메서드는 기본적으로 GET 메서드로 처리됨.
• 아래는 브라우저가 서버로 보내는 메시지의 예시

GET /users HTTP/1.1
Host: 30.20.10.10:5000
User-Agent: Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/58.0.3029.110 Safari/537.36
Accept: application/json
Connection: keep-alive

 

• 첫 번째 줄: GET /users HTTP/1.1
  • GET: 요청을 의미하는 HTTP 메서드
  • /users: 요청하려는 서버의 리소스 경로(엔드포인트)
  • HTTP/1.1: HTTP 프로토콜의 버전
• Host: 요청을 보내는 서버의 호스트 이름과 포트 정보
• User-Agent: 브라우저 또는 클라이언트의 정보(이 정보로 서버는 브라우저 종류, 운영체제 등을 알 수 있음)
• Accept: 클라이언트가 수용할 수 있는 데이터 형식(여기서는 json으로 지정)
• Connection: 연결을 유지할지 끊을지를 결정하는 헤더

 

4) 서버에서 요청 처리

• 서버는 클라이언트의 요청을 받으면 요청된 URL인 /users 와 일치하는 엔드포인트가 있는지 확인하고 이 엔드포인트가 GET 요청을 처리하는 함수에 매핑되어 있다면 그 함수가 실행됨
• 예를 들어 Flask 서버에서 @app.route('/users', methods=['GET'])로 정의된 엔드포인트가 있다면, 그에 해당하는 함수가 실행되어 데이터를 반환. 예시의 경우 사용자 목록을 반환함

 

5) 서버에서 HTTP 응답 메시지 생성

• 서버는 클라이언트에게 응답을 보내기 위해 HTTP 응답 메시지를 생성함. 서버는 응답 본문에 JSON 형식으로 사용자 목록을 포함시켜 보내며, 상태 코드는 200 OK로 설정
• 아래는 HTTP 응답 메시지의 예시

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

[
    {"id": 1, "name": "John Doe", "email": "john@example.com"},
    {"id": 2, "name": "Jane Smith", "email": "jane@example.com"}
]

• 첫 번째 줄: HTTP/1.1 200 OK
  • HTTP/1.1: HTTP 프로토콜의 버전
  • 200 OK: 요청이 성공적으로 처리되었음을 나타내는 상태코드
• Content-Type: 응답 본문 데이터의 양식
• Content-Length: 응답 본문 데이터의 크기(바이트 단위)
• 본문: JSON 형식으로 변환된 사용자 목록 데이터(서버에서 반환)

 

6) 브라우저에서 응답 처리

• 브라우저는 서버에서 받은 HTTP 응답을 처리함. 이때 브라우저는 응답 본문이 JSON 형식임을 알고 있으므로, 이를 화면에 표시하는 대신 JavaScript로 처리할 수 있음

 

 

정리

• 사용자는 주소창에 http://30.20.10.10:5000/users를 입력하였고(사실상 주소창은 서버 명령창임)
• 클라이언트는 /users 경로로 GET 요청을 보냈으며
• 서버는 요청을 처리하여 JSON 형식의 사용자 목록을 응답으로 반환함
• 브라우저는 이 응답을 받아 화면에 표시하거나 다른 동작을 수행하기 위한 데이터로 사용할 수 있음