[Network] RESTful API

1. RESTful API?

https://mannhowie.com/rest-api

• REST(Representational State Transfer)라는 아키텍처 스타일을 따르는 API
• 자원의 URI(Uniform Resource Identifier)와 HTTP 메서드를 활용하여 자원에 접근하고 조작하는 규약
• 자원(Resource):
  웹에서 관리하고자 하는 데이터 (예: 사용자, 게시물, 상품 등)
• HTTP 메서드: 자원에 대한 동작을 정의하는 메서드
  • GET: 자원의 조회
  • POST: 자원의 생성
  • PUT: 자원의 전체 수정
  • PATCH: 자원의 부분 수정
  • DELETE: 자원의 삭제

[c.f.] URI?

• 인터넷에서 자원을 식별하는 고유한 문자열
• 모든 URL은 URI지만, 모든 URI가 URL은 아님!

용어	설명	예시
URI	자원을 식별하는 모든 문자열 (포괄적 개념)	https://example.com/index.html urn:isbn:0451450523
URL	자원의 위치를 알려주는 URI (주소 역할)	https://example.com/index.html
URN	자원의 이름을 지정하는 URI (위치 불명)	urn:isbn:0451450523

2. RESTful API 설계원칙

• 일관된 인터페이스 사용: 자원 기반 설계 & HTTP 메서드(동사) 활용
• URI와 HTTP 메서드를 규칙적으로 사용해 누구나 쉽게 이해하고 사용할 수 있음
• API 설계가 표준화되고 예측 가능함

1. 자원의 명확한 식별 (Resource Identification)

• RESTful API에서 자원은 고유한 URI(Uniform Resource Identifier)로 식별됨

• 자원은 명사로 표현해야 하며, URI는 대체로 복수형으로 사용함

• 자원의 표현 (Representation)
  자원의 표현을 JSON이나 XML과 같은 포맷으로 클라이언트에 전달
  클라이언트는 이 표현을 받아 자원의 상태를 표시하거나 처리할 수 있음

• 자원의 상태나 행동은 HTTP 메서드를 통해 정의됨

• e.g.

  • /users → 사용자 목록
  • /users/{id} → 특정 사용자
  • /products → 상품 목록
  • /products/{id} → 특정 상품

2. HTTP 메서드를 이용한 작업 정의

• RESTful API에서는 HTTP 메서드를 사용하여 자원에 대한 작업을 정의함

• GET: 자원을 조회
  e.g. GET /users → 모든 사용자 조회
  [+] 필터링, 정렬, 페이징
  클라이언트가 대량의 데이터를 요청할 때, 효율적인 데이터 처리가 가능
  /users?age=25&sort=name&limit=10&page=2

• POST: 새로운 자원을 생성
  e.g. POST /users → 새 사용자 생성

• PUT: 자원의 전체 수정
  e.g. PUT /users/1 → ID가 1인 사용자 정보 수정

• PATCH: 자원의 부분 수정을 할 때 사용
  e.g. PATCH /users/1 → ID가 1인 사용자 이름 수정

• DELETE: 자원을 삭제
  e.g. DELETE /users/1 → ID가 1인 사용자 삭제

3. 무상태성 (Stateless)

• 각 HTTP 요청은 독립적이어야 하며, 서버는 클라이언트의 상태를 저장하지 않음

4. HTTP 상태 코드

• 요청의 결과를 표현함

• 상태 코드는 클라이언트가 요청에 대한 응답을 쉽게 이해할 수 있도록 도움

  • 200 OK: 요청이 성공적으로 처리되었을 때
  • 201 Created: 새로운 자원이 성공적으로 생성되었을 때
  • 400 Bad Request: 잘못된 요청이 있을 때
  • 401 Unauthorized: 인증이 필요한 요청에 대해 인증이 없는 경우
  • 404 Not Found: 요청한 자원이 존재하지 않을 때
  • 500 Internal Server Error: 서버 오류가 발생했을 때

5. 계층적 시스템 (Layered System)

• RESTful 아키텍처는 계층적 시스템을 지원함
• 클라이언트는 서버와 직접 통신하지 않고, 중간 계층을 통해 통신할 수 있음
  e.g. 프록시 서버, 로드 밸런서, 캐시 서버 등

6. 캐시 처리 (Cacheable)

• 서버에서 반환되는 자원은 캐시 가능한 자원으로 설정하여 성능 향상을 도울 수 있음
• 클라이언트가 자원에 대한 변경을 요청할 때만 서버에 요청을 보내고, 변경되지 않으면 캐시된 자원을 사용할 수 있음
• HTTP 헤더에 캐시 관련 정보를 포함시켜 클라이언트가 자원을 재사용하도록 할 수 있음
• e.g.
  Cache-Control: max-age=3600 → 해당 자원을 1시간 동안 캐시