REST API 설계 원칙과 구조, JSON

1. REST API란?

REST(REpresentational State Transfer) 아키텍처 스타일의 디자인 원칙을 준수하는 API로, RESTful API라고도 한다.

REST 디자인 원칙

REST API는 거의 모든 프로그래밍 언어를 사용해 개발이 가능하며, 다양한 데이터 포맷을 지원한다. REST API는 6가지 REST 디자인 원칙에 부합해야 한다.(아키텍처 제한사항)

1. 균일한 인터페이스(Uniformed Interface)

• 요청이 어디에서 오는지와 무관하게, 동일한 리소스에 대한 모든 API 요청이 동일하게 보여야 함.
• 사용자의 동일한 데이터 조각이 오직 하나의 URI(Uniform Resource Identifier)에 속함을 보장해야 함.
• 클라이언트가 필요로 하는 모든 정보를 포함해야 함.
• ⭐Self-descriptiveness(자체 표현 구조)를 가지고, REST API 메시지만 보고도 이를 쉽게 이해할 수 있는 구조로 되어 있어야 함.

2. 클라이언트-서버 디커플링(Client Server Architecture)

• REST API 디자인에서 클라이언트와 서버 애플리케이션은 서로 간에 완전히 독립적이어야 함.
• 클라이언트 애플리케이션이 알아야 하는 유일한 정보는 요청된 리소스의 URI이며, 다른 방법으로 서버 애플리케이션과 상호작용 불가함.
• 서버 애플리케이션은 HTTP를 통해 요청된 데이터에 전달하는 것을 제외하고 클라이언트 애플리케이션을 수정하지 않아야 함.

⭐3. 무상태

• 서버가 요청 간에 클라이언트 데이터를 저장하지 않음
• 각 요청에서 처리에 필요한 모든 정보를 포함해야 함
• 서버측 세션을 필요로 하지 않음

4. 캐싱 가능성

• 리소스를 클라이언트 또는 서버 측에서 캐싱할 수 있어야 함.
• 서버 응답에는 전달된 리소스에 대해 캐싱이 허용되는지 여부에 대한 정보가 포함되어야 함.
• 서버 측의 확장성 증가와 클라이언트 측의 성능 향상을 동시에 얻을 수 있음.

5. 계층 구조 아키텍처(Layered System)

• REST API에서는 호출과 응답이 서로 다른 계층을 통과하므로 앤드 에플리케이션 또는 중개자와 통신하는지 여부를 클라이언트나 서버가 알 수 없도록 설계되어야 함

(옵션) 6. 코드 온디맨드

• 일반적으로 정적 리소스를 전송하지만 특정한 경우에는 응답에 실행 코드를 포함할 수 있음(요청 시에만 실행되어야 함)

---

REST API의 작동 방식

1. HTTP URI를 통해 자원을 명시
2. 해당 자원(URI)에 대한 CRUD Operation 적용

• REST API는 HTTP 요청을 통해 통신함으로써 리소스 내에서 작성, 읽기, 업데이트, 삭제 등의 표준 데이터베이스 기능을 수행함.(CRUD)
  e.g. PUT 요청을 사용해 레코드 업데이트
  e.g. DELETE 요청을 사용해 레코드 삭제
• 특정 순간 또는 타임스탬프의 리소스 상태를 리소스 표현이라고 하는데, 이 정보는 JSON, HTML, XLT, Python, PHP 또는 일반 텍스트를 포함해 다양한 형식으로 클라이언트에 전달될 수 있음.

• Best Practices for good REST API Design

REST의 구성 요소

자원(Resource) : HTTP URI

• 모든 자원에 고유한 ID가 존재하고, 이 자원은 Server에 존재함
• 자원을 구별하는 ID는 ‘/groups/{group_id}’와 같은 HTTP URI
• Client는 URI를 이용해서 자원을 지정하고 해당 자원의 상태(정보)에 대한 조작을 Server에 요청함

행위(Verb) : HTTP Method

• HTTP 프로토콜의 Method를 사용
  e.g. GET, POST, PUT, DELETE...
  

표현(Representation of Resource)

• 클라이언트가 자원의 상태(정보)에 대한 조적 요청 시 서버가 이에 적절한 응답을 보냄. 하나의 자원은 JSON, XML, TEXT, RSS 등 여러 형태의 응답을 받을 수 있음
• JSON 혹은 XML을 통해 데이터를 주고 받는 것이 일반적임

---

2. JSON이란?

JSON(JavaScript Object Notation)의 약자로 data format 중 하나이다. 사람과 기계가 모두 읽을 수 있고 프로그래밍 언어에 구애받지 않기 때문에 가장 자주 사용되는 리소스 표현 전달 형식이다.

{
  "name": "John Doe",
  "email": "john@example.com",
  "age": 30,
  "hobbies": [
  	"Reading",
    "Traveling",
    "Swimming"
   ]
}

• 배열과 중첩객체 구조 지원
• 쉬운 사용법과 경량화된 언어
• 다양한 언어와 플랫폼에서 지원

---

참고자료

IBM - REST API란?
AWS - 애플리케이션 프로그래밍 인터페이스(API)란 무엇인가요?
JSON으로 작업하기
REST API란 무엇인가?