1. REST란 무엇인가?
REST (Representational State Transfer)는 웹의 리소스를 정의하고, 해당 리소스에 대한 주소(URI)를 통해 접근하는 아키텍처 스타일입니다. RESTful API는 이 원칙을 준수하여 설계된 API를 의미합니다.
2. REST의 핵심 원칙:
- 클라이언트-서버 구조: 서버와 클라이언트의 역할을 분리
- 무상태(Stateless): 서버는 클라이언트의 상태를 저장하지 않음
- 일관된 인터페이스(Uniform Interface): URI와 HTTP Method를 통한 일관성 있는 접근 방식
- 캐시 가능(Cacheable): 리소스는 캐시가 가능해야 함
- 계층화된 시스템: 여러 중간 서버를 통해 리소스를 전달할 수 있음
3. RESTful한 URL 설계 원칙
| 명사 기반 리소스 표현 |
URL은 동사 대신 명사를 사용 (예: /users/1 X /getUserById?id=1 X) |
| 복수형 명사 사용 |
리소스를 표현할 때는 복수형 명사를 사용 (예: /books, /users) |
4. @Param, @Query, @Body 차이점 (NestJS 데코레이터)
| 데코레이터 |
받아오는 위치 |
예시 URL |
사용처 |
| @Param() |
경로(주소) |
/users/123 |
리소스를 식별할 때 (ID 등) |
| @Query() |
URL 뒤 ?조건 |
/users?role=admin&page=2 |
검색, 필터, 정렬 등 옵션 전달 |
| @Body() |
HTTP 요청 본문 |
(POST/PUT 시 JSON 데이터) |
리소스 생성, 수정 시 필요한 데이터 전달 |
5. 오늘 만든 계산기 API 예시 (스마트 컨트랙트 + RESTful 설계 적용)
| API 엔드포인트 |
설명 |
HTTP Method |
데코레이터 |
| /calculator/last-result/:address |
특정 계정의 마지막 계산 결과 조회 |
GET |
@Param |
| /calculator/history/:address |
특정 계정의 전체 계산 이력 조회 |
GET |
@Param |
| /calculator/calculate |
계산 요청 (덧셈, 뺄셈 등) |
POST |
@Body |
6. 스마트 컨트랙트 연계 시 주의 사항
- Solidity에서 반환되는 데이터를 JS에서 처리할 때 BigInt → Number 변환 처리 필요.
- 트랜잭션 후 이벤트 로그를 파싱(parseLog)하여 결과값을 받아오는 방식.
- RESTful 설계 원칙(단일 조회 vs 컬렉션 조회)를 명확히 구분해서 API를 설계해야 유지보수가 쉽다.