REST API

REST의 정의

"REpresentational State Transfer" 의 약자로, 

자원의 표현(representation)에 의한 상태(State) 전달(Transfer)을 뜻합니다.

REST의 구성 요소

1. 자원(Resource) - URI

• 자원의 고유한 ID, 이를 통해 Client가 Server에 있는 변경할 자원을 지정함
• URI 와 URL의 차이점
  • URL : Uniform Resource Locator로 인터넷 상 자원의 위치를 의미합니다.
  • URI : Uniform Resource Identifier로 인터넷 상의 자원 식별자, URI는 URL을 포함

2. 행위(Verb) - Method

• CRUD 연산을 위한 HTTP Method
  

  GET	Read
  POST	Create
  PUT	Update(데이터 전체를 바꿀 때)
  PATCH	Update(데이터 일부만 바꿀 때)
  DELETE	Delete

3. 표현 ( Representation of Resource )

• Client와 Server가 데이터를 주고받는 형태로 JSON, XML 등이 있습니다.

REST의 특징

1. Server-Client (서버-클라이언트 구조)

• 자원이 있는 쪽이 Server, 자원을 요청하는 쪽이 Client가 됩니다.
  • REST Server는 API를 제공하고 비즈니스 로직 처리 및 저장을 책임지고,
  • Client는 사용자 인증이나 context( 세션, 로그인 정보 ) 등을 직접 관리하고 책임집니다.
  • 역할을 확실히 구분시킴으로써 서로 간의 의존성을 줄입니다.

2. Stateless (무상태)

• HTTP 프로토콜은 Stateless Protocol이므로 REST 역시 무상태성을 갖습니다.
• Client의 context를 Server에 저장하지 않습니다.
  • 즉, 세션과 쿠키와 같은 context 정보를 신경쓰지 않아도 되므로 구현이 단순해집니다.
• Server는 각각의 요청을 완전히 별개의 것으로 인식하고 처리합니다.
  • 각 API 서버는 Client의 요청만을 단순 처리합니다.
  • 즉, 이전 요청이 다음 요청의 처리에 연관되어서는 안됩니다. ( DB에 의해 바뀌는 것은 허용 )
  • Server의 처리 방식에 일관성을 부여하기 때문에 서비스의 자유도가 높아집니다.

3. Cacheable (캐시 처리 기능)

• 웹 표준 HTTP 프로토콜을 그대로 사용하므로 웹에서 사용하는 기존의 인프라를 그대로 활용할 수 있습니다.
  • 즉, HTTP가 가진 가장 강력한 특징 중 하나인 캐싱 기능을 적용할 수 있습니다.
  • HTTP 프로토콜 표준에서 사용하는 Last-Modified Tag 또는 E-Tag를 이용해 캐싱을 구현합니다.
• 대량의 요청을 효율적으로 처리할 수 있습니다.

4. Layered System (계층 구조)

• Client는 REST API Server만 호출합니다.
• REST Server는 다중 계층으로 구성될 수 있습니다.
  • 보안, 로드 밸런싱, 암호화 등을 위한 계층을 추가하여 구조를 변경할 수 있습니다.
  • Proxy, Gateway와 같은 네트워크 기반의 중간매체를 사용할 수 있습니다.
  • 하지만 Client는 Server와 직접 통신하는지, 중간 서버와 통신하는지는 알 수 없습니다.

5. Uniform Interface (인터페이스 일관성)

• URI로 지정한 Resource에 대한 요청을 통일되고, 한정적으로 수행하는 아키텍처 스타일을 의미합니다.
• HTTP 표준 프로토콜에 따르는 모든 플랫폼에서 사용이 가능하며, Loosely Coupling(느슨한 결함) 형태를 갖습니다. 
  • 즉, 특정 언어나 기술에 종속되지 않음

6. Self-Descriptiveness (자체 표현)

• 요청 메시지만 보고도 쉽게 이해할 수 있는 자체 표현 구조로 되어있습니다.

---

REST API 란?

REST API의 정의

• REST의 특징을 기반으로 서비스 API를 구현한 것

REST API의 특징

• 각 요청이 어떤 동작이나 정보를 위한 것인지를 그 요청의 모습 자체로 추론이 가능한 것 입니다.

REST API 디자인 가이드

REST API 설계 시 가장 중요한 항목은 다음의 2가지로 요약합니다.

• 첫 번째, URI는 정보의 자원을 표현해야 한다.
• 두 번째, 자원에 대한 행위는 HTTP Method(GET, POST, PUT, PATCH, DELETE)로 표현한다.
  • 행위(Method)는 URI에 포함하지 않는다.

REST API의 설계 규칙

1. URI는 명사를 사용한다.(리소스명은 동사가 아닌 명사를 사용해야 한다.)

1-1. 아래와 같은 동사를 사용하지 말 것

• /getAllUsers
• /getUserById
• /createNewUser
• /updateUser
• /deleteUser

2. 슬래시( / )로 계층 관계를 표현한다.

 

3. URI 마지막 문자로 슬래시 ( / )를 포함하지 않는다.

 

4. 밑줄( _ )을 사용하지 않고, 하이픈( - )을 사용한다.

 

5. URI는 소문자로만 구성한다.

 

6. HTTP 응답 상태 코드 사용

- 클라이언트는 해당 요청에 대한 실패, 처리완료 또는 잘못된 요청 등에 대한 피드백을 받아야 한다.

HTTP 상태 코드 정리

 

7. 파일확장자는 URI에 포함하지 않는다.

Ex) http://dev-coco.tistory.com/restapi/220/photo.jpg (X)

 

RESTful API vs REST API

• RESTful API :  REST의 설계 규칙을 잘 지켜서 설계된 API를 RESTful한 API라고 합니다. 주소만으로도 어떤 것을 요청 하는지 파악이 가능합니다.
• REST API : REST의 특징을 기반으로 서비스 API를 구현한 것

{
"results" : [
{"idx": 1, "name": "1학년"},
{"idx": 2, "name": "2학년"},
{"idx": 3, "name": "3학년"}
]
}

https://school.com/grade/2 이렇게 idx, 고유번호가 붙는다면, idx가 2인 학년의 정보가 올 겁니다. 

그리고 https://school.com/grade/2/students 의 students가 붙으면 2반 학생들의 정보를 받아올 수 있습니다.

{
"results" : [
{"idx": 1, "name": "홍길동", "gender": "male"},
{"idx": 2, "name": "성춘향", "gender": "female"},
{"idx": 3, "name": "전우치", "gender": "male"},
{"idx": 4, "name": "나기백", "gender": "male"},
...
]
}

또, https://school.com/grade/2/students/15 라는 idx를 붙이면 그 학생들 중 15의 idx를 가진 학생의 정보가 오겠죠.

혹은 https://school.com/grade/2/students?gender=male 와 같이 조건을 붙여서 남학생들의 정보만 받아올 수도 있습니다.

한 페이지당 10명의 데이터를 받아오는 거라면 이런식으로도 표현이 가능합니다.

https://school.com/grade/2/students?page=2&count=10  

{

"results" : [

{"idx": 11, "name": "신짱구", "gender": "male"},

{"idx": 12, "name": "김지우", "gender": "female"},

{"idx": 13, "name": "김화석", "gender": "male"},

{"idx": 14, "name": "박수쳐", "gender": "male"},

...

]

}