[CS] REST, RESTful API란?

REST는 "Representational State Transfer"의 약자로, 웹의 장점을 최대한 활용하면서 분산 시스템을 설계하기 위한 원칙과 패턴을 제시한다.

 

REST의 주요 개념

1. 자원(Resource)
   - REST에서는 해당 소프트웨어가 관리하는 모든 것이 자원이다. 자원은 URI(Uniform Resource Identifier)로 식별한다.
   - 예를 들어, 사용자를 나타내는 자원은 `/users`와 같이 표현할 수 있다.

2. 표현(Representation)
   - 자원은 다양한 형태로 표현할 수 있다. 일반적으로 JSON, XML, HTML 등을 사용한다.
   - 클라이언트는 서버에서 자원의 표현을 받아 상태를 전송받는다.

3. 상태 전이(State Transfer)
   - 클라이언트는 서버로부터 자원의 상태를 전송받고, 이 상태를 바탕으로 다음 작업을 수행한다.
   - 상태 전이는 주로 HTTP 메서드를 사용하여 이루어진다. (GET, POST, PUT, DELETE 등)

4. HTTP 메서드
   - REST는 HTTP의 메서드를 활용하여 자원에 대한 CRUD 작업을 정의한다.
   - `GET, POST, PUT, PATCH, DELETE 등을 사용하여 작업을 정의한다.

 

5. 무상태(Stateless)
   - 서버는 각 요청을 독립적으로 처리하며, 이전 요청의 상태를 저장하지 않는다.
   - 클라이언트는 필요한 모든 상태 정보를 요청에 포함시켜야 한다.

6. 캐시 가능(Cacheable)
   - HTTP의 캐싱 메커니즘을 활용하여 응답을 캐시할 수 있다. 이를 통해 성능을 향상시킬 수 있다.

7. 계층화(Layered System)
   - 클라이언트와 서버 사이에 중간 계층(예: 프록시, 게이트웨이)을 사용할 수 있다. 각 계층은 독립적으로 발전할 수 있다.

8. 인터페이스 일관성(Uniform Interface)
   - REST의 가장 중요한 원칙 중 하나로, 클라이언트와 서버 간의 통신을 단순화하고 일관성 있게 유지한다.
   - 자원의 식별, 리소스의 조작을 통한 상태 변경, 자기 서술적 메시지, 하이퍼미디어(링크)를 통한 애플리케이션 상태 엔진을 포함한다.

 

REST의 장점

- 확장성(Scalability): 무상태 아키텍처와 캐싱을 통해 시스템 확장성을 높인다.
- 독립적 개발(Independent Development): 클라이언트와 서버가 독립적으로 업데이트 및 개발을 할 수 있다.
- 성능(Performance): HTTP 프로토콜의 기능을 활용하여 성능을 최적화할 수 있다.
- 유연성(Flexibility): 다양한 데이터 형식을 지원하고, URI를 통해 자원을 유연하게 식별할 수 있다.

 

 

 

REST를 준수하여 작성된 API를, RESTfulAPI라 한다.

RESTful API를 설계 시 지켜야 할 주요 규칙

1. 자원 (Resources)
  - URI는 자원을 나타내므로 명사를 사용해야 한다. 동사는 사용하지 않는다.
  - 예: `/users`, `/products`, `/orders`

 

2. HTTP 메서드
  -  CRUD (Create, Read, Update, Delete) 작업에 대해 적절한 HTTP 메서드를 사용해야 한다.
  - `GET`: 자원의 조회
  - `POST`: 자원의 생성
  - `PUT`: 자원의 전체 수정 (자원의 모든 필드 업데이트)
  - `PATCH`: 자원의 부분 수정 (자원의 일부 필드 업데이트)
  - `DELETE`: 자원의 삭제

 

3. URI 설계
  - 자원의 관계를 나타내기 위해 계층적 구조를 사용한다.
    - 예: `/users/{userId}/orders/{orderId}`
  - URI는 소문자로 작성한다. 가독성을 위해 언더바(_) 대신, 하이픈(-)을 사용할 수 있다.
    - 예: `/product-categories`

 

4. 상태 코드 (Status Codes)
  - 각 응답에 대해 적절한 HTTP 상태 코드를 반환해야 한다.
  - `200 OK`: 요청이 성공적으로 처리됨
  - `201 Created`: 새로운 자원이 성공적으로 생성됨
  - `204 No Content`: 요청이 성공적으로 처리되었으나 반환할 데이터가 없음
  - `400 Bad Request`: 잘못된 요청
  - `401 Unauthorized`: 인증 실패
  - `403 Forbidden`: 권한 없음
  - `404 Not Found`: 자원을 찾을 수 없음
  - `500 Internal Server Error`: 서버 내부 오류

5. 페이징, 필터링, 정렬
  - 페이징, 필터링, 정렬을 위해 쿼리 매개변수를 사용합니다.
  - 페이징: `GET /users?page=2&size=50`
  - 필터링: `GET /users?role=admin`
  - 정렬: `GET /users?sort=createdDate,desc`

6. 표현 (Representations)
- 응답 본문은 일반적으로 JSON 형식을 사용한다.
-  응답에 관련 링크를 포함하여 클라이언트가 가능한 다음 작업을 알 수 있도록 한다.

7. 보안
- 모든 API 통신은 HTTPS를 통해 암호화 하여야 한다.
- OAuth2, JWT 등 표준 인증 방식을 사용한다.

9. 일관성 및 문서화
- 일관성: API 전체에서 일관된 URI, 메서드, 응답 형식을 사용한다.
- 문서화: Swagger, OpenAPI 등 도구를 사용하여 API를 문서화한다.