REST API

<학습 전 생각>

1. 대체 REST API가 뭐길래 REST API 노래를 하는 거지?

2. 이미 REST API 하게 코드를 작성했는데 이 개념만 모르는 걸까 아니면 잘못 활용했던 걸까?

Q. REST API 실제 예시 들어주면서 이럴 때는 어떠한 메서드를 써야 하는지 고민해본 적이 있는가?

 

REST API 구현하기 위해서는 HTTP 프로토콜, 메서드 종류, 라우팅에 대한 이해가 필요하다.

 

<REST API 정리해야 할 사항>

• 개념 설명
• REST의 탄생 배경
• RESTful의 의미는?
• 샘플 REST API 작성
• 통신 과정 설명
• document 뭘로 작성했는지? 왜 작성했는지?
• 자동 문서 도구 툴들 사용해 봤는지?
• 이미지 업로드 어떻게 하는지?

 

# REST API란 (Representational State Transfer API)

• REST 아키텍쳐 스타일을 따르는 API

 

# REST란

웹에 존재하는 모든 자원(이미지, 동영상, DB 자원)에 고유한 URI를 부여해 활용하는 것이며

리소스 지향 아키텍쳐 스타일*

*아키텍쳐 스타일 - 제약 조건의 집합

 

• 리소스, 메서드, 메시지로 구성

아래의 sample REST API 작성한 것을 가져와봤습니다.

// HTTP POST, http://tistory.com/users
{
    "users": {
        "name": "bruno"
    }
}

리소스

• 모든 자원에는 고유한 ID가 있습니다.
  이 ID가 URI 입니다.
• 클라이언트가 이 URI를 이용하여 서버에 해당 자원에 대한 정보를 요청합니다.
• 위에서는 /users 가 리소스가 됩니다

 

메서드

• 위의 예시에서는 POST 메서드를 활용했습니다.

의미	메서드	IDEMPOTENT (멱등성)
CREATE	POST	NO
READ	GET	YES
UPDATE	PUT	YES
DELETE	DELETE	YES

 

메시지

• 주로 JSON 이나  XML 을 쓰는 것이 일반적입니다.
• 위의 예시에서는
  {"name": "bruno"} 이 부분이 메시지가 됩니다.

 

# REST는 어떻게 탄생하게 된 걸까?

SGML -> XML -> HTML

90년대 중반쯤부터는 XML을 사용했는데 사용자가 직접 태그를 지정해서 정보를 표현하던 방식이었습니다.

 

이 XML을 SOAP이라는 프로토콜을 통해서 전달했는데

이 SOAP의 단점만 나열하자면 (SOAP 외에도 있었지만 대표적인 SOAP을 예로 들어)

복잡해서 작성이 어렵고 전문 Tool이 필요할뿐더러 무겁기 때문에 느렸다고 합니다.

 

그래서 이런 단점들을 해결하고자 나온 것이 REST입니다.

 

# RESTful이란?

REST 원리를 따르는 시스템

 

# sample REST API 작성

HTTP POST, http://tistory.com/users
{
    "users": {
        "name": "bruno"
    }
}

HTTP GET, http://tistory.com/users/1
{
    "users": {
        "id": 1
    }
}

// PUT은 해당 데이터가 있을 경우 업데이트하고 없으면 생성함
HTTP PUT, http://tistory.com/users/2
{
    "users": {
        "name": "arteta"
    }
}

HTTP DELETE, http://tistory.com/users/1

 

# REST의 특성

1. Uniform Interface

리소스(URI)에 대한 요청을 통일되고 한정적으로 수행하는 아키텍쳐 스타일을 의미합니다.

HTTP 표준에만 따른다면 특정 언어나 기술에 국한되지 않고 모든 플랫폼에서 사용할 수 있으며 (느슨한 결합)

URI로 지정한 리소스에 대한 조작이 가능한 아키텍처 스타일을 의미합니다.

 

제약조건은 아래와 같습니다.

• identification of resources
  리소스가 URI로 식별되어야 한다.
• manipulation of resources through representations
• self-descriptive messages
  서버나 클라이언트가 변경되더라도 메세지만 가지고도 해석이 가능하다는 의미입니다.
  그래서 서버가 계속 변할 수 있기에 (서버 확장) 커뮤니케이션이 확장 가능합니다.
  REST API 메시지만 보고도 어떤 용도로, 어떤 방식으로 사용되는지 그 의미를 바로 알 수 있습니다.

• hypermedia as the engine of application state (HATEOAS)

 

2. Stateless (무상태성)

상태 유지로 통신할 경우의 단점*을 극복하고자 Stateless 방식으로 통신을 하는데

요청할 때마다 필요한 모든 정보를 전달하기에 서버에서 따로 저장할 필요가 없고

그렇기에 해당 서버에 장애가 생겨서 서버가 바뀌어도 다시 요청만 하면 되기에 큰 지장이 없습니다.

그래서 상태 유지보다 많은 요청을 처리할 수 있고 필요시 서버를 증설(스케일 아웃)할 때도 용이합니다.

 

* 상태 유지로 통신할 경우의 단점

이 경우에는 요청할 때마다 해당 서버가 그 내용을 저장해두는데

해당 서버에 문제가 생겨서 서버를 바꾸게 될 경우 처음부터 다시 요청해야 되는 문제가 있습니다.

 

3. Cacheable

웹 페이지와 REST API 모두 HTTP 프로토콜을 사용하기에

웹의 기존 인프라 또한 활용할 수 있습니다.

 

그중에 캐싱 기능이 있는데

클라이언트는 자체 캐쉬에 저장된 값을 사용하는데

거기서 활용할 수 있는 경우에는 서버에 다시 요청하지 않도록 하는 것입니다.

 

그래서 이미지나 문서들이 클라이언트 캐시에 저장되고

동일한 요청을 반복할 경우 서버에 재요청하지 않고 캐시에 저장된 데이터를 재사용합니다.

 

이를 통해 불필요한 자원 낭비를 막을 수 있습니다.

 

4. Client - Server 구조

클라이언트와 서버를 분리해서 의존성을 줄이고 이를 통해 보다 쉽게 관리하고 개발할 수 있습니다.

그래서 핸드폰의 앱과 달리 클라이언트의 버전을 업데이트했을 경우에

서버의 버전 업데이트가 필수가 아닐 수 있는 것입니다.

• 클라이언트 - 사용자 인증, 컨텍스트(세션, 로그인 정보) 등을 직접 관리
• 서버 - 비즈니스 로직, 데이터 관리

이처럼 클라이언트와 서버의 역할을 명확하게 구분 지어 의존성을 줄일 수 있습니다.

 

5. Layered System (계층형 구조)

HTTP 프로토콜 이외의 계층을 API 요청 처리를 위한 객체 안에 정의하여 보안, 유저 인증, 암호화 등을 유연하게 추가할 수 있습니다. 클라이언트는 서버에 단지 요청을 보내고 이 안의 동작을 알 필요가 없기 때문에 이런 설계가 가능합니다.

 

 

# HTTP 메서드

HTTP 메소드	RFC	요청에 Body가 있음	응답에 Body가 있음	안전	멱등(Idempotent)	캐시 가능
GET	RFC 7231	아니요	예	예	예	예
HEAD	RFC 7231	아니요	아니요	예	예	예
POST	RFC 7231	예	예	아니요	아니요	예
PUT	RFC 7231	예	예	아니요	예	아니요
DELETE	RFC 7231	아니요	예	아니요	예	아니요
CONNECT	RFC 7231	예	예	아니요	아니요	아니요
OPTIONS	RFC 7231	선택 사항	예	예	예	아니요
TRACE	RFC 7231	아니요	예	예	예	아니요
PATCH	RFC 5789	예	예	아니요	아니요	예

*Idempotent (멱등성) - 여러 번 수행해도 결과는 같은 것을 의미

 

Q. 그런데 여기서 멱등성이 왜 중요한 거고 어떻게 구분하는 걸까?

REST는 각각의 API를 Stateless로 처리하기에 실행 도중 에러가 발생할 경우

멱등성이 유지되는 것과 아닌 것의 처리가 달라집니다.

멱등성이 유지되는 것은 몇 번을 실행하더라도 결괏값이 같기에 별다른 처리 과정이 필요하지 않겠지만

멱등성이 유지되지 않는 것은 값이 달라진 것을 다시 되돌리는 처리 과정이 필요하기에 그 과정을 처리해주는 로직을 짜서 처리해야 함을 유의해야 합니다.

 

처음에 DB 측면에서 이해해야 하는 걸까 싶어서

POST는 할 때마다 새로운 데이터가 생성되니 멱등성이 유지되지 않고

GET은 조회만 하는 것이기에 멱등성이 유지된다고 생각했습니다.

PUT은 한번 하든 여러 번 하든 같은 데이터가 될 것이기에 멱등성이 유지된다고 생각했습니다.

그런데 DELETE는 2번째부터는 에러가 발생할 것이고 그러면 결과는 다른 게 아닌가...?라고 생각을 했습니다.

 

Dion 님의 말씀처럼 공식문서를 보니 "메서드는 오류 또는 만료 문제를 제외하고" 멱등성 여부를 따지는 것을 알 수 있었습니다.

<메서드 정의 - HTTP 1.1 RFC 문서(RFC-2016)>

공식문서 분명 어렵고 익숙해지기도 어렵지만 이렇게 친절하게 링크와 설명을 함께 써주실 때라도 한 번씩 읽다 보면 공식문서와도 친해질 수 있는 날이 오겠죠..?!ㅎㅎ (한글로도 굉장히 잘 써져 있어서 영어라고 너무 겁먹지 마셔요~)

 

<멱등성 요약>

오류나 만료 문제를 제외하고 생각해볼 때 "몇 번을 실행하든 그 결과가 같은가?"가 포인트입니다.

POST, GET, PUT은 위에서 설명한 것과 동일하고

DELETE는 몇 번을 하든 결과는 "이제는 해당 데이터가 없다" 여서 멱등성이 유지됨을 알 수 있습니다.

 

# REST하지 않은 것의 예시

• 동작 내용과 메서드가 일치하지 않는 경우 (이렇게 쓰면 자체 표현 구조에도 적합하지 않게 된다)
• HTTP Response code를 사용하지 않거나 혹은 통신 성공과 실패의 응답 코드만 쓰는 경우 또는 적합하지 않은 응답 코드를 쓰는 경우

 

Q. API의 본질이 DECOUPLING (탈동조화)라고 하는데 어떤 의미일까?

위에서 다뤘던 것처럼 클라이언트와 서버를 분리함으로써 의존성을 줄일 수 있고 이 덕분에 각자 개발을 진행할 수 있습니다.

API가 클라이언트와 서버 사이에서 연결고리 역할을 하는 것인데 이 API를 통해서 클라이언트와 서버의 의존성을 줄일 수 있고 이를 DECOUPLING이라고 합니다.

 

# REST API 설계 규칙

• URI는 동사가 아닌 명사 사용
  나쁜 예 - /getUsers
• 슬래시(/)로 계층 관계 표현
• URI의 마지막 문자를 슬래시(/)로 쓰지 않는다.
• underscore(_)를 사용하지 않고 하이픈(-)을 사용한다.
• 대문자가 아닌 소문자를 사용할 것
• HTTP 응답 상태 코드 사용
• URI에 파일 확장자를 표기하지 말 것

 

<추가적으로 학습해야 할 부분>

1. Uniform Interface의 제약조건 중 특히 HATEOAS에 대한 이해 부족

2. Layered System (계층형 구조)에 대한 이해 부족

 

 

<참고 자료>

조대협 님께서 초보자들도 읽기 쉽게 잘 써주셔서 아래의 글을 먼저 읽으시는 걸 추천드립니다.

https://bcho.tistory.com/953

REST API의 이해와 설계-#1 개념 소개

 

그 후 좀 더 자세하게 보고 싶으시다면 아래의 글을 읽어보시는 것을 추천드립니다.

https://ijbgo.tistory.com/20

REST API 란 ?

 

Rest가 발표되기 이전인 90년대에는 어떤 방식으로 데이터를 표현하고 어떤 방식으로 전송했는지가 궁금하시다면 HwanSehll 님께서 그 스토리를 잘 정리해주신 글이 있어 공유드립니다. 

https://hwan-shell.tistory.com/140

Restful에 대한 이해하기(xml, soap란?) - 2

 

HTTP에 대한 전체적인 내용이 정리되어 있습니다.

https://ko.wikipedia.org/wiki/HTTP

HTTP - 위키백과, 우리 모두의 백과사전

 

그리고 HTTP 멱등성에 대해서는 아래의 글이 도움이 많이 돼서 공유드립니다.

https://velog.io/@dion/HTTP-%EB%A9%94%EC%86%8C%EB%93%9C%EC%9D%98-%EB%A9%B1%EB%93%B1%EC%84%B1-%EA%B7%B8%EA%B2%8C-%EB%AD%94%EB%8D%B0

HTTP 메소드의 멱등성? 그게 뭔데?

 

어느 정도 개념이 잡히셨다면 이 영상을 보시는걸 추천 드립니다.

https://www.youtube.com/watch?v=RP_f5dMoHFc