RESTful API의 설계 원칙

RESTful API란?

• 웹에서 정보를 주고 받는 약속(규칙)
• 서버와 클라이언트(웹 브라우저나 앱)가 정보를 예쁘게 정리된 방식으로 주고받는 것

REST 특징

특징	설명
Uniform	- Uniform Interface - URI로 지정한 리소스에 대한 조작을 통일되고 한정적인 인터페이스로 수행하는 아키텍처 스타일을 의미한다.
Stateless	- 무상태성 성격을 갖는다. 작업을 위한 상태 정보를 저장하고 관리하지 않는다. - 세션 정보나 쿠키 정보를 별도로 저장하고 관리하지 않기 때문에 API 서버는 들어오는 요청만을 단순히 처리하면 된다. 이러한 이유로 서비스의 자유도가 높아지고 서버에서 불필요한 정보를 관리하지 않음으로써 구현이 단순해진다.
Cacheable	- HTTP라는 기존 웹 표준을 그대로 사용하기 때문에, 웹에서 사용하는 기존 인프라를 그대로 활용할 수 있다. 따라서 HTTP가 가진 캐싱 기능 적용이 가능하다. - HTTP 프로토콜 표준에서 사용하는 Last-Modified 태그나 E-Tag를 이용해 구현할 수 있다.
Self-descriptiveness	- REST API 메시지만 보고도 이를 쉽게 이해할 수 있는 자체 표현 구조로 되어 있다.
Client - Server 구조	- REST 서버는 API 제공, 클라이언트는 사용자 인증이나 컨텍스트(세션, 로그인 정보) 등을 직접 관리하는 구조로 각각의 역할을 확실하게 구분한다. - 클라이언트와 서버에서 개발해야 할 내용이 명확해지고 서로 간 의존성이 줄어든다.
계층형 구조	REST 서버는 다중 계층으로 구성될 수 있으며 보안, 로드 밸런싱, 암호화 계층을 추가해 구조 상의 유연성을 둘 수 있고 PROXY, 게이트웨이 같은 네트워크 기반의 중간 매체를 사용할 수 있게 한다.

RESTful API의 6가지 설계 원칙

1. URL은 리소스를 나타낸다.

• URL은 주소이다.
• 예 : /users/1 -> 1번 사용자 라는 뜻
  • 잘못된 예 : /getUser?id=1
  • 올바른 예 : /users/1

2. HTTP 메소드를 제대로 사용

행동	의미	HTTP 메서드	예시( URL)
가져오기	읽기 (Read)	GET	/users/1
만들기	생성 (Create)	POST	/users
수정하기	전체 수정 (Update)	PUT	/users/1
부분 수정	일부만 변경 (Partial Update)	PATCH	/users/1
삭제하기	지우기 (Delete)	DELETE	/users/1

3. 리소스는 명사로 표현

• 주소에는 명사만 써야된다.
• 잘못된 예 : /createUser
• 올바른 예 : /users
• 사용자는 사람이지 만드는 행동이 아니니까 명사로 표현

4. 계층 구조로 표현하기 (계단식 구조)

• 만약 1번 사용자의 게시글이 궁금하다면?
  • /users/1/posts
    -> 1번 사용자의 게시글들 이란 뜻이 된다.

5. 상태(State)는 저장하지 않는다. (Stateless)

• 매 요청마다 서버는 새로운 요청처럼 받아들여야 한다.
• 서버는 모든 요청이 독립적이길 원하기 때문에 매번 요청마다 내가 누군지 알려줘야 한다.
• 즉, 로그인한 사용자라는 걸 계속 보내줘야 한다.(예 : JWT 토큰 같은 것)

6. 응답은 표준 포맷으로 (보통 JSON)

서버는 정보를 줄 때 보통 JSON 형태로 준다.

{
  "id": 1,
  "name": "강현",
  "email": "hyun@example.com"
}

 

리소스와 표현(Representation)은 다르다?

• REpresentational State Transfer
  표현을 주고 받는 방식

// 앱에서 받은 JSON
{
  "id": 1,
  "name": "강현",
  "email": "hyun@example.com"
}

• /users/1 이라는 리소스는 강현이라는 사용자를 뜻한다.
• 근데 이걸 웹에서는 HTML로 보여줄 수도 있고, 앱에서는 JSON으로 받을 수도 있다.
• 즉, 리소스는 같은데 표현은 다를 수 있다.

인증(Authentication) & 권한(Authorization)

• RESTful API는 Stateless하기 때문에 서버는 매번 누군지 확인해야 한다.
• 따라서 인증 토큰 같은 걸 요청할 때마다 함께 보내줘야 한다.
• 인증 : 너 누구?
  예 : 로그인
• 권한 : 너 이거 해도 됨?
  예 : 관리자만 수정 가능
• 예 : /admin/settings는 권리자 권한이 있는 사용자만 접근 가능

REST vs RESTful vs REST API

용어	뜻	비유
REST	개념 (이론)	"테이블 매너" 같은 규칙
REST API	REST를 따르는 API	규칙대로 밥 먹기
RESTful API	REST 원칙을 잘 지킨 API	예쁘게, 정확히, 깔끔하게 밥 먹는 사람

HATEOAS (하이토스) - 고급 REST 원칙

{
  "id": 1,
  "name": "강현",
  "email": "hyun@example.com",
  "_links": {
    "self": "/users/1",
    "edit": "/users/1/edit",
    "delete": "/users/1/delete"
  }
}

• 서버가 답장을 줄 때, 다음에 할 수 있는 행동을 함께 알려주는 것
• 위처럼 먼저 정보를 주고 수정하거나 삭제하고 싶으면 이 링크를 써라 하고 알려주는 것

API 설계할 때 주의할 점

• 명확한 리소스 이름
  -> /books vs /libraryBooks (되도록 단순하게)
• 동사의 사용 자제
  • POST/books (생성)
  • /createBook -> 이런 건 안 쓴다.

• 에러 응답도 정리해서 보내기

{
  "status": 404,
  "message": "해당 사용자를 찾을 수 없습니다"
}