HTTP API란?

1) 한 줄 정의

HTTP API는 “HTTP 요청/응답”으로 서버의 데이터와 기능을 사용하도록 만든 인터페이스다.

• 클라이언트는 서버에 요청을 보냄
• 서버는 처리 결과를 응답으로 돌려줌
• 이때 “어떤 URL로,  어떤 형식으로, 어떤 응답이 오는지”가 API 계약(Contract)

2) 구성요소 4가지

HTTP API는 보통 아래 4개로 정의된다.

1. Endpoint(엔드포인트): URL 경로
   • 예: /api/users, /api/users/1
2. Method(메서드): 요청의 의도
   • GET: 서버에서 자원을 조회한다.
   • POST: 서버에 데이터를 보내 생성하거나 특정 처리를 요청한다.
   • PUT: 지정한 자원을 전체 교체(전체 수정) 한다.
   • PATCH: 지정한 자원을 부분 수정한다.
   • DELETE: 지정한 자원을 삭제한다.
3. Request/Response Format(형식): 헤더/바디, JSON 등
   • 예: Content-Type: application/json
4. Status Code(상태코드): 결과의 의미
   • 예: 성공 200/201, 클라 오류 400/401/404, 서버 오류 500

---

3) HTTP API는 보통 JSON을 주고받는다

요즘 백엔드 API는 대부분 요청/응답 바디가 JSON이다.

• 요청: 클라이언트 → 서버
• 응답: 서버 → 클라이언트

예시:

Content-Type: application/json
Accept: application/json

 

4) API 설계에서 “자원(Resource)”와 “식별(URI)”이 핵심

HTTP API를 깔끔하게 만들려면 무엇을 다루는지(자원) 를 먼저 잡는다.

• 자원: users, orders, products 같은 “대상”
• 식별: /users/1 처럼 “어떤 자원인지”를 URI로 표현

보통 규칙은:

• 복수형 명사로 자원을 표현: /users, /orders
• 특정 대상은 ID로 식별: /users/{id}

메서드로 동작을 표현하고 URL은 “대상”을 표현하는 게 깔끔하다.

5) Query String vs Path Variable(구분만 잡기)

• Path Variable: “대상 1개를 딱 집는다”
  • 예: /users/1
• Query String: “조건/필터/정렬/검색”
  • 예: /users?role=admin&page=2

6) 상태코드는 “성공/실패” 이상의 의미다

HTTP API는 응답 바디뿐 아니라 상태코드로도 의미를 준다.

• 성공:
  • 200 OK (일반 성공)
  • 201 Created (새 리소스 생성 성공)
  • 204 No Content (성공했는데 응답 바디 없음)
• 실패:
  • 400 Bad Request (요청 형식/검증 실패)
  • 401 Unauthorized (인증 필요/실패)
  • 403 Forbidden (권한 없음)
  • 404 Not Found (리소스 없음)
  • 500 Internal Server Error (서버 오류)

7) HTTP API “계약서(스펙)”는 이런 걸 약속한다

API 문서(스펙)에 최소로 들어가야 하는 것들:

• URL(엔드포인트)
• 요청 메서드
• 요청 헤더(필요 시 Authorization 등)
• 요청 바디 스키마(JSON 필드)
• 응답 상태코드
• 응답 바디 스키마(성공/실패 에러 형식)
• 예시 요청/응답

마무리 요약

• HTTP API는 서버 기능/데이터를 HTTP로 호출하는 인터페이스
• 핵심 구성은 Endpoint + Method + Format + Status Code
• URL은 “자원”, 조건은 query, 결과는 상태코드+바디로 전달
• 다음 글에서 메서드(GET/POST/PUT/PATCH/DELETE)를 더 깊게 파면 전체가 완성됨