감각을 잃지 않기 위한 Api 기초 정리

아무리 기초적인 내용일지라 하더라도, 다른 일에 집중하느라 관심이 소홀해지면 오랜만에 다시 봤을 때 정확한 기억이 나지 않을 때가 있다. GitHub의 공개 프로젝트들을 탐방하며 기본 아키텍쳐, API 명세 등을 둘러보다가 아주 기본적인 지식들이 가물가물하게 떠올라서 자존심이 상한 채 Chat GPT와 함께 다시 복기를 했는데, 이런 경험의 빈도가 꽤 잦았던 것 같아 그 빈도를 줄이기 위해 복기 내용을 포스팅해놓고 틈날때마다 한번씩 보는 습관을 들여 감을 잃지 않으려고 한다.

키워드 : curl, 요청 헤더, 쿼리 파라미터(?,&), REST API, URI과 URL, HTTP/HTTPS, FTP,SMTP

---

📌 curl 명령어 구조

먼저, 다음과 같은 API 요청들을 자주 보게 된다:

curl -X POST user -d '{
  "email": "user2@test.com",
  "name": "일반 유저2",
  "password": "1234"
}'

여기서 각각의 의미는 다음과 같다:

• curl: 터미널에서 HTTP 요청을 보내기 위한 명령어 도구

• X: HTTP 메서드 지정 (GET, POST, PUT, PATCH, DELETE 등) 옵션

• d: 서버로 전송할 데이터 (body)

• H: 요청 헤더 (ex. 인증 토큰, Content-Type 등)

🔐 Authorization 헤더는 언제 필요한가?

-H "Authorization: Bearer <토큰값>"

이 헤더는 인증이 필요한 API에 매번 붙여야 한다. 예를 들어 유저 정보 조회, 출석 체크, 이벤트 보상 요청 같은 보호된 API는 토큰이 없으면 401 에러를 반환한다.

• POST /authentication/sign-in: 로그인 → 토큰 발급 (❌ 토큰 필요 없음)

• GET /user/profile: 유저 정보 조회 (✅ 토큰 필요)

HTTP는 stateless이기 때문에 매 요청마다 토큰을 붙여야 한다.

📦 JSON 처리 시 Content-Type은 언제 필요할까?

-H "Content-Type: application/json"

이건 "내가 보내는 데이터는 JSON이야"라고 서버에 알려주는 용도다.

body에 JSON 데이터를 담는 요청(POST, PUT, PATCH)일 때만 붙이면 된다.

• ✅ 필요: JSON 데이터를 보낼 때 (예: 회원가입, 유저 정보 수정 등)

• ❌ 불필요: GET/DELETE 요청처럼 body가 없는 경우

예시

# 필요 O (JSON 데이터 전송)
curl -X POST user \\
  -H "Content-Type: application/json" \\
  -d '{"email": "user@test.com", "name": "홍길동"}'

# 필요 X (쿼리로만 전달)
curl -X GET user?page=1&take=10

---

?, &는 뭘 의미할까? (쿼리 파라미터)

GET /reward-claim/user?page=1&take=10&status=Pending

• ?: 쿼리 문자열 시작

• &: 여러 파라미터를 연결

• key=value 형식으로 필터 조건 전달

즉, 위 API는 다음과 같은 요청을 의미한다:

• 페이지: 1페이지

• 한 페이지당 10개씩

• 상태: Pending 상태만 필터

🌍 REST API란?

REST (Representational State Transfer)는 웹의 자원에 대한 URL과 HTTP 메서드를 조합해 동작을 설계하는 방식이다.

예시

REST의 핵심은 자원(resource)을 URL로 식별하고, 동작을 메서드로 구분하는 것이다.

URI vs URL 차이

많은 개발자들이 헷갈리는 개념 중 하나인데, 이 둘은 포함 관계에 있다.

• URI (Uniform Resource Identifier): 자원을 식별하는 모든 것 (포괄적 개념)

• URL (Uniform Resource Locator): 자원의 위치를 나타내는 URI의 하위 개념

예시 비교

🔑 모든 URL은 URI이지만, 모든 URI가 URL은 아니다.

HTTP, HTTPS, FTP, SMTP 차이