[HTTP API 설계] Spring HTTP API란? - 개발 지식

항상 어디서 많이 들어봤던 HTTP API.
하지만 정확히 이해하지는 못했었던 HTTP API.
오늘은 HTTP API 설계에 대해서 알아보도록 하겠습니다.

 

목차

01. HTTP API

02. REST API 란?

03. HTTP API vs REST API 차이점
	03-1. HTTP vs REST
    	03-2. HTTP API vs REST API
        
04. REST API 디자인
	04-1. 디자인 해야할 것들!
    	04-2. URI 디자인
        
        
05. HTTP Method
	05-1. HTTP Method의 의미
    	05-2. 추가적인 HTTP  Method의 사용법 [참고]
        05-3. URI  QUERY 디자인
            
06. 일반적으로 좋은 API 디자인

 

---

01. HTTP API 란?

01-1. HTTP (Hyper Text Transfer Protocol)

정의 : 웹에서 데이터를 주고 받기 위한 통신 규약을 말합니다.

• 웹 브라우저와 서버가 요청/응답 시에 사용하는 프로토콜을 말합니다.
• get, post와 같은 방식으로 요청 보내고 받는 방식을 말합니다.

01-2. API (Application Programming Interface)

정의 : 소프트웨어 간 통신할 수 있게 도와주는 약속된 인터페이스

• 프로그램끼리 대화할 수 있는 방법을 말하며 요청하면 결과를 반환합니다.

01-3. HTTP API

정의 : HTTP 프로토콜을 통해 제공되는 API를 말합니다, 즉 API 규칙입니다.

• URL + HTTP 방식(GET/POST 등)으로 요청을 보내고 JSON 같은 응답을 받는 구조/규칙

 

 

---

02. REST API 란?

02-1. REST(Representational State Transfer)

정의 : 웹에서 데이터를 주고 받는 지침서를 말합니다. (규칙보다 약한 느낌)

• 웹의 자원을 URL로 표현하고, HTTP 방식으로 자원을 처리하는 아키텍처 스타일을 말합니다.

02-2. REST API

정의 : REST 원칙을 지켜서 설계된 HTTP API

• URL은 '명사(자원)'로, GET/POST/PUT/DELETE로 '행동'을 구분해서 설계한 API!

 

 

---

03. HTTP API vs REST API 차이점

✔️  HTTP vs REST 

구분	REST	HTTP
정의	아키텍처 스타일 (설계 원칙)	프로토콜 (통신 규약)
역할	리소스를 어떻게 표현하고 조작할지를 정의	클라이언트와 서버 간 통신 방법을 정의
예	GET /users/1 ← REST 원칙에 따른 설계	GET, POST, PUT 등 ← HTTP 메서드
관계	HTTP 위에서 REST 원칙을 적용해 RESTful하게 사용	REST를 구현할 때 많이 쓰이는 수단
강제성	원칙 중심 (자유로움)	명확한 규격 (RFC로 표준화됨)

✔️ HTTP API   vs  REST API

항목	HTTP API	REST API
개념	HTTP를 사용하는 모든 API	REST 원칙을 따르는 HTTP API
URL 설계	자유롭게 URL 사용	자원을 명사로 표현 (예: /users/1)
HTTP 메서드 사용	POST 하나만 써도 무방	GET/POST/PUT/DELETE를 의미 있게 구분
상태 유무	상태 유지 가능	Stateless (서버는 상태를 기억하지 않음)
예시	/doLogin (POST)	/users (POST), /users/1 (GET) 등

※ 핵심은 모든 REST API는 HTTP API에 속하지만 모든 HTTP API가 RESTful하지는 않는다!

※ RESTful이란? :  쉽게 REST 원칙을 잘 지켜서 만든 API 디자인 스타일을 말한다

 

정리를 해보면 :

REST API는 HTTP API의 한 형태로, 자원 중심 설계를 강조하는 더 구체적이고 일관된 방식의 HTTP API입니다.

 

 

 

---

 

지금까지 이제 HTTP API와 REST API 등 HTTP API에 대해서 알아보았으니 
REST API의 디자인에 대해서 깊이 있게 알아보도록 하겠습니다.

 

04. REST API 디자인

04-1. 디자인 해야할 것들!

• URI (or URL)
• 메세지 (Representation of Resource)

04-2. URI (Uniform Resource Identifier)

정의 : 리소스(자원)을 식별하는 경로!

설계 방법  :   REST에서 예측 가능하고 가독성 높은 URI 설계가 필요합니다.

 

✔️ URI 설계 원칙

원칙	설명
/ 사용	계층적 구조 표현
소문자 사용	leagues/seattle ← 대문자 지양
- 사용	가독성 향상: team-members
_ 사용 금지	지양: 구분자로 혼란 초래
확장자 생략	.json, .xml 등 붙이지 않음
단수 vs 복수	컬렉션은 복수, 도큐먼트는 단수
컨트롤러 이름	동사나 동사구를 사용
변하는 값은 ID로 대체	/{userId} 형태 사용
CRUD 표현은 Method로	DELETE /users/1234 (O), DELETE /deleteUser/1234 (X)

✔️ URI 구조 패턴

URI 패턴	설명	예시
Collection	리소스 모음 (복수 명사) [서버에서 관리하는 디렉토리, 저장소 ]	/users, /teams
Document	단일 리소스 (단수 명사 + ID)	/users/123, /teams/42
Nested	계층 구조 표현	/leagues/seattle/teams/trebuchet
Controller	행위 표현 (동사 사용) [ CRUD 외의 표현이 필요한 경우 → 마지막에 동사를 붙여준다]	/alerts/245743/resend, /students/morgan/register

 

 

 

 

---

HTTP API를 좀 더 구체적이고 일관된 방식으로 만든 API가 REST API입니다.
그렇기 때문에 기존의 HTTP API의 경우에는 POST, GET의 Method를 주로 이용했는데
REST API는 다양한 HTTP Method를 더 의미있고 규칙에 맞게 사용하는데 집중하였습니다.
각 Method마다 사용의 의미를 잘 나눈다면 깔끔하고 유지보수하기 좋은 설계가 가능합니다.
지금부터 HTTP Method의 사용법을 알아보도록 하겠습니다. 

 

05. HTTP Method

 

05-1. HTTP Method의 의미

• GET : list or read : 읽기, 불러오기
• POST : create : 등록
• PUT : update or create : 업데이트 or 등록
• DELETE : delete : 제거
• PATCH : partial update : 일부 업데이트

POST   /users          # 새 유저 생성
GET    /users          # 전체 유저 조회
GET    /users/ne10001  # 특정 유저 조회
PUT    /users/ne10001  # 유저 정보 전체 수정
DELETE /users/ne10001  # 유저 삭제

ex) POST /users/add (X)
ex) POST /users/create (X)

 

05-2. 추가적인 HTTP  Method의 사용법 [참고]

• Safe Methods
  • 읽기 전용의 의미를 가지는 Methods
  • GET, HEAD, OPTIONS, TRACE

• Idempotant Methods
  • 한 번을 실행해도, 여러번을 실행해도 의도한 결과가 동일한 Methods
  • PUT, DELETE + Safe Methods

05-3. URI  QUERY 디자인

:  URI의 파라미터 값의 표현으로도  다양한 표현을 할 수 있습니다.

✔️ 쿼리 파라미터는 검색, 필터링, 페이징 등에 사용됨목적 예

목적	예시
필터링	/users?role=admin
페이징	/users?page=2&size=20
정렬	/users?sort=name,asc
검색	/articles?keyword=restapi

 

 

---

 

06. 일반적으로 좋은 API 디자인

1. 직관적인 API
   1. 이름 - URL,메세지
   2. 데이터 타입, 포맷
   3. 에러 피드백
2. 예측가능한 API - 일관성
   1. 이름, 타입, 경로구조, 호응 관계
   2. 일관성의 범위
3. 간결하고 체계적인 API
   1. API 구조화
      1. 데이타, 피드백
   2. API 사이징
4. 안전한 API
   1. 권한관리
   2. 접근제어
   3. 적절한 에러 피드백

 

 

---

 

오늘은 다음과 같이 HTTP API의 설계에 대해서 알아보았습니다.
어렵게 느껴졌던 개념들을 비교하면서 공부하다 보니 잘 정리가 되었던 것 같습니다.
오늘도 고생하셨습니다