RESTful API
: REST(Representational State Transfer) 아키텍처 스타일의 설계 원칙을 준수하는 API이다.
REST
그렇다면 REST란?
인터넷과 같은 복잡한 네트워크에서의 통신을 관리하기 위한 소프트웨어 아키텍처이다.
구체적으로는 자원(Resource을 이름(Name)으로 구분하여 해당 자원의 상태(정보)를 주고받는 것을 의미한다.
- HTTP를 기반으로 URI를 통해 자원에 접근할 수 있음
HTTP Method(POST, GET, PUT, DELETE 등)를 통해 해당 자원에 대한 CRUD Operation을 적용하는 것을 의미한다.
✅ REST 아키텍처의 장점
- 높은 성능의 신뢰할 수 있는 통신을 대규모로 지원
- 구현과 수정이 손쉬움
REST 설계 원칙
1. 균일한 인터페이스
- HTTP 표준에만 따른다면 모든 플랫폼에서 사용이 가능
- 주로 URL, HTTP 메서드(
POST,GET,PUT,DELETE등) 를 통해 리소스를 조작 - 클라이언트-서버 간 상호작용을 단순화, 표준화 하여 데이터를 주고 받으므로 특정 언어나 플랫폼에 종속되지 않음
2. 무상태 (Stateless)
- 각 요청은 독립적이며 서버는 클라이언트의 상태를 저장하지 않는다.
3. 클라이언트-서버 분리
- 클라이언트와 서버는 독립적으로 존재
- 클라이언트는 서버에 자원을 요청하고, 서버는 요청을 처리하여 응답
4. 캐시 처리 가능 (Cacheable)
- 응답은 클라이언트는 서버에서 받은 데이터를 로컬에 저장하고 재사용 가능하다(캐시 가능)
- 캐시를 사용함으로써 성능을 향상시키고 서버의 부하를 줄일 수 있다
5. 계층화 시스템 아키텍처
- 클아이언트와 서버는 독립적이며, 서버는 여러 계층으로 구성될 수 있다
- 시스템을 확장 가능하게 하고 보안성을 높여준다
6. 코드 온디맨드(선택 사항)
- 서버는 클라이언트에게 실행할 수 있는 코드나 애플리케이션 로직을 전달할 수 있다
- ex) JavaScript ...
- ex) JavaScript ...
REST API
REST API 동작 방식
REST API는 HTTP 요청을 통해 통신하여 CRUD(생성/조회/업데이트/삭제) 작업과 같은 표준 데이터베이스 기능을 수행한다.
| HTTP 메소드 | 동작 |
|---|---|
GET | 조회 |
POST | 리소스 생성 |
PUT | 리소스 업데이트 |
DELETE | 리소스 삭제 |
RESTful API 설계 원칙
- 리소스는 명사를 사용해야 한다.
- ✅ 예시:
/users,/products
- 단수가 아닌 복수 형태를 사용해야 한다.
- ✅ 예시:
/users,/products - ❌ 잘못된 예시:
/user,/product
- 만약, REST만으로 해결하기 어려운 경우라면 동사를 허용한다.
- 예시:
/users/{id}/activate,/orders/{id}/cancel
- 자원의 계층 관계를 슬래시(/)로 표현한다.
- 예시:
/users/{userId}/orders(특정 사용자에 대한 주문 목록)
- 마지막 문자에는 슬래시(/)가 있으면 안된다.
- ✅ 예시:
/users - ❌ 잘못된 예시:
/users/
- 언더바(_)가 아닌 하이픈(-)을 사용해야 한다.
- ✅ 예시:
/user-details,/product-list - ❌ 잘못된 예시:
/user_details,/product_list
- 소문자를 사용해야 한다.
- ✅ 예시:
/users,/products - ❌ 잘못된 예시:
/Users,/PRODUCTS
- URI에 파일 확장자를 포함하면 안된다.
- ✅ 예시:
/users,/products - ❌ 잘못된 예시:
/users.json,/products.xml
- CRUD 함수명은 사용하지 않고, HTTP Method를 활용해야 한다.
- CRUD(Create, Read, Update, Delete) 작업은 HTTP 메서드(
POST,GET,PUT,DELETE)를 사용하여 수행 - ✅ 예시:
POST/users: 사용자 생성GET/users/{id}: 사용자 조회PUT/users/{id}: 사용자 수정DELETE/users/{id}: 사용자 삭제
- ❌ 잘못된 예시:
/createUser,/getUser,/updateUser,/deleteUser
- 정렬, 필터링, 페이징은 신규 API를 만드는것이 아닌 Query Parameter를 사용해야 한다.
- ✅ 예시:
- GET /users?sort=name: 이름으로 정렬
- GET /users?filter=active: 활성 사용자만 필터링
- GET /users?page=2&limit=10: 페이지네이션
- ❌ 잘못된 예시:
/users/sortByName,/users/filterActive
RESTful한 API 설계를 위해서는?
-
URL을 통해 자원을 명시하기
-
데이터에 대한 메타정보 제공
- 응답 데이터에는 해당 데이터가 어떤 형식인지, 어떻게 해석해야 하는지에 대한 메타정보가 포함 필요
-
CRUD 작업에 필요한 HTTP 메서드를 적절히 활용
POST,GET,PUT,DELETE
-
적절한 HTTP 상태 코드 반환
-
JSON을 기본 응답 형식으로 사용
2XX: 성공4XX: 클라이언트 측 문제5XX: 서버측 문제
-
일관적인 엔드포인트 사용
📌 요약
- RESTful API는 HTTP를 기반으로 REST 아키텍처 설계 원칙을 준수하는 API이다.
- RESTful API는 일관적인 규칙을 통해 이해하기 쉽고 사용이 용이하다.
- 자원을 명시적으로 식별하는 URL을 사용하며, HTTP 메서드(
POST,GET,PUT,DELETE)를 활용하여 CRUD 연산을 수행한다.
💡RESTful API 원칙을 준수함으로써 유지보수하기 쉽고 확장성이 뛰어난 RESTful API를 설계할 수 있다.
참고
https://restfulapi.net/
https://www.ibm.com/kr-ko/topics/rest-apis
https://velog.io/@somday/RESTful-API-%EC%9D%B4%EB%9E%80
백엔드 개발도 락이다