네이버검색 api (2)api 구성

Close-up of a dark, rough textured stone surface providing an abstract background.

API 통신에서 **메서드(Method)**와 **엔드포인트(Endpoint)**는 서버에 “무엇을(Endpoint)”, “어떻게(Method)” 할지를 알려주는 핵심 요소입니다.

이전의 네이버 검색광고 API 예시를 통해 각각의 개념을 쉽게 설명해 드리겠습니다.

1. 메서드 (Method)

메서드는 **”서버에 어떤 행동을 하라고 시킬 것인가?”**를 정의하는 **동사(Verb)**입니다. HTTP 프로토콜에서 약속된 단어들을 사용합니다.

GET (조회/가져오기): “정보를 보여줘.”
- 서버의 데이터를 변경하지 않고 읽어오기만 할 때 사용합니다.
- 예: 리포트 목록 보기 (list), 리포트 상세 내용 보기 (get)
POST (생성/보내기): “새로 만들어줘.”
- 서버에 새로운 데이터를 보내거나 작업을 요청할 때 사용합니다.
- 예: 새 리포트 생성 요청 (create)
DELETE (삭제하기): “지워줘.”
- 서버에 있는 데이터를 삭제할 때 사용합니다.
- 예: 리포트 작업 삭제 (delete)
PUT/PATCH (수정하기): “고쳐줘.”
- (이번 예시에는 없지만) 기존 데이터를 수정할 때 주로 사용합니다.

2. 엔드포인트 (Endpoint)

엔드포인트는 **”어디에 그 요청을 보낼 것인가?”**를 나타내는 **주소(Address)**입니다. API 서버 내에서 특정 자원(Resource)의 위치를 가리킵니다.

기본 주소:/master-reports
- ‘마스터 리포트’라는 업무를 담당하는 창구입니다.
변수가 포함된 주소:/master-reports/{id}
- 여기서 {id}는 가변적인 숫자나 문자가 들어가는 자리입니다.
- 특정 리포트 하나를 콕 집어서 말할 때 사용합니다. (예: /master-reports/RW-20230101-1234)

3. 쉬운 비유 (은행 창구)

은행에 가서 업무를 본다고 상상해 보겠습니다.

엔드포인트 (/master-reports): 은행의 “대출 상담 창구” (장소)
메서드 (GET/POST/DELETE): 창구 직원에게 하는 “말” (행동)

상황	메서드 (행동)	엔드포인트 (장소)	의미
목록 조회	GET (“신청 내역 보여주세요”)	/master-reports (대출 창구에서)	“여기 접수된 모든 대출 신청 내역을 보여주세요.”
생성	POST (“새로 신청할게요”)	/master-reports (대출 창구에)	“새로운 대출 신청서를 제출합니다.”
삭제	DELETE (“취소할게요”)	/master-reports/101 (대출 창구의 101번 서류)	“101번 대출 신청 서류는 폐기해 주세요.”

4. 질문하신 내용 다시 보기

작성해주신 내용에서 메서드와 엔드포인트를 구분하면 다음과 같습니다.

메서드 (Method)	엔드포인트 (Endpoint)	하는 일
`GET`	`/master-reports`	마스터 리포트 전체 목록을 가져와라
`GET`	`/master-reports/{id}`	특정 ID의 리포트 정보를 가져와라
`POST`	`/master-reports`	마스터 리포트를 생성해라
`DELETE`	`/master-reports`	모든 마스터 리포트를 삭제해라
`DELETE`	`/master-reports/{id}`	특정 ID의 리포트를 삭제해라

이 개념을 이해하면 API 문서를 볼 때 “어떤 주소(Endpoint)로 어떤 행동(Method)을 날려야 내가 원하는 결과가 나오는지” 바로 파악하실 수 있습니다.

앞서 설명한 메서드와 엔드포인트가 “은행 창구 가서 말하기”라면, 헤더와 인증은 “번호표 뽑고 신분증 보여주기”에 해당합니다.

1. 헤더 (Header): 편지 봉투와 배송 정보

API 요청을 보낼 때, 실제 데이터(Body) 외에 **”이 요청에 대한 부가 정보”**를 담는 곳입니다. 마치 택배 상자에 붙은 송장 스티커와 같습니다.

내용물 설명 (Content-Type): “이 상자 안에 든 건 JSON 형식의 데이터야”라고 알려줍니다.
보내는 사람 정보 (인증 정보): “이거 내가 보내는 거야”라는 신원 확인 정보가 여기에 들어갑니다.

2. 인증 (Authentication): 디지털 신분증

네이버 광고 서버는 아무나 들어와서 데이터를 조작하면 안 되기 때문에 철저한 신원 확인을 합니다. 네이버 검색광고 API는 4가지 핵심 정보를 헤더에 담아서 보내야 문을 열어줍니다.

헤더 이름 (Key)	설명 (비유)	실제 내용
X-Timestamp	“지금 몇 시야?”	요청을 보내는 현재 시간(밀리초). 오래된 요청은 보안상 거절됩니다.
X-API-KEY	“출입증 번호”	네이버 개발자 센터에서 발급받은 공개 라이선스 키입니다.
X-Customer	“광고주 ID”	실제 작업을 수행할 광고 계정의 ID입니다. (대행사라면 고객의 ID)
X-Signature	“인감 도장(서명)”	가장 중요합니다. 위 3가지 정보와 ‘비밀키(Secret Key)’를 섞어서 암호화(HMAC-SHA256)하여 만든 긴 문자열입니다.

⚠️ 주의: X-Signature는 고정된 비밀번호가 아닙니다. 보낼 때마다 시간(X-Timestamp)이 바뀌므로, 서명 값도 매번 새로 계산해서 만들어야 합니다.

3. 전체 그림으로 보기 (요청 구조)

이제 POST /master-reports (리포트 생성) 요청을 보낼 때, 실제로 날아가는 데이터의 모양을 시각화해 보겠습니다.

HTTP

POST /master-reports HTTP/1.1
Host: api.naver.com

// [헤더 영역: 신분증 및 배송 정보]
Content-Type: application/json
X-Timestamp: 1672531200000
X-API-KEY: 010000000003...
X-Customer: 123456
X-Signature: (암호화된 복잡한 문자열...)

// [바디 영역: 실제 업무 요청서]
{
  "item": "Keyword",
  "fromTime": "20230101",
  "toTime": "20230131"
}

해석:

POST: 생성해주세요.
Header: 저는 인증된 사용자(API Key, Signature)이고, JSON 데이터를 보냅니다.
Body: 키워드(Keyword)에 대한 1월 리포트를 만들어주세요.

요약

메서드/엔드포인트: 무엇을 할지 정의 (업무 내용)
헤더/인증: 내가 누구인지 증명 (신분증)

특히 X-Signature를 코드로 생성하는 부분이 초보자에게 가장 큰 진입 장벽입니다.