REST API (2)

REST API(1)에 이어서 Uniform Interface에 대한 내용을 살펴보겠습니다.

 

2020/07/17 - [Study/Java(OOP) & others] - REST API (1)

REST API (1)

 

Uniform Interface

1. Identification of resources
2. Manipulation of resources through representations
3. Self-descriptive message
4. Hypermedia as the engine of application state (HATEOAS)

우선 여기서도 위의 두 가지(1, 2번)는 꽤 잘 지켜지고 있는데요.

어떤 규칙에 대한 이야기인지 자세히 알아보겠습니다.

 

 

Identification of resources

resource의 식별이라는 의미로, URI로 resource를 식별할 수 있어야 한다는 조건입니다.

URI 지정시 아래 7가지 규약을 잘 지킨다면 REST API를 따르는 URI라고 이야기할 수 있습니다.

 

후행 '/'는 URI에 포함되지 않아야 합니다.(1) 즉, URI가 끝나는 부분은 아래와 같이 들어가선 안됩니다.

(실제로 네이버로 접속해보면 첫 번째 주소와 동일한 것을 알 수 있습니다.)

https://www.naver.com                     ---------- (O)

https://www.naver.com/                   ---------- (X)

 

계층 관계를 나타낼 땐 '/'로 구분합니다.(2)

네이버에서 티스토리를 검색한다면, 아래와 같은 주소가 주어집니다.

https://search.naver.com/search.naver?sm=top_hty&fbm=1&ie=utf8&query=티스토리

네이버 검색창 -> 티스토리 검색 (계층 구분)

 

가독성을 위해 URI에 '-'을 사용합니다.(3) '_'는 글자 폰트로 인한 이슈로 인해 사용하지 않습니다.(4)

(서로 이유는 다르지만 비슷한 모양새를 가지고 있어 묶어두었습니다.)

https://exponential-e.tistory.com                 ---------- (O)

https://exponential_e.tistory.com                    ---------- (X)

-> exponential e라는 단어의 가독성을 위한 구분 및 구분자로 '_'를 사용하지 않음.

 

URI 작성시 소문자를 사용합니다.(5)

Window에선 아래 두 개를 같은 주소로 나타내기도 하지만, Linux에선 두 번째 주소에서 404 에러를 띄우는 경우도 있다고 합니다.

즉, 운영체제마다 처리하는 방식이 다르니 특이한 경우를 제외하곤 통일해서 쓴다고 생각하시면 될 것 같습니다.

https://exponential-e.tistory.com/category                 ---------- (O)

https://exponential-e.tistory.com/Category                 ---------- (X)

 

URI에는 복수형을 사용합니다.(6)

keep-it-simple 규칙(?)에 의해 결정되었다고 합니다. 

/customers/1/orders                 ---------- (O)

/customer/1/orders                 ---------- (X)

 

URI에 파일 확장자를 포함하지 않습니다.(7)

요청 응답 시 json 데이터로 주고받으실 텐데, 이러한 정보를 제공하기 위해 URI에 확장자를 붙이면 안 됩니다.

실제로도 URI에 표시하지 않고 대신 헤더에  Content-type을 지정해서 보내곤 합니다.

json header

Content-type: application/json;

/customers/data                 ---------- (O)

/customers/data.json                 ---------- (X)

 

 

Manipulation of resources through representations

representation 전송을 통해서 resource를 조작해야 한다는 뜻입니다.

간단히 설명하자면,

resource란 응답으로 받은 메시지를 의미하며, representation은 메세지 내부에서 메세지의 의미를 나타내는 요소들입니다.

더 정확하게 설명은 아래 참고 자료의 이응준님 블로그 링크를 참고해주세요.

내용을 이해하고 설명을 쓰려했는데, 막상 쓰려고 보니 이응준님의 블로그 내용을 모두 갖다 붙이는 결과가 나타날 것 같습니다.. ㅎㅎ

 

 

Self-descriptive message

스스로 설명 가능한 메시지라는 뜻인데 표현해보면 아래와 같습니다.

GET / HTTP/1.1

Host: www.example.com

 

이렇게 GET을 표시해 어떤 처리를 요청하는 메시지인지 표현해야 하며

또한 해당 메시지의 목적지를 명시해주어야 합니다.

 

이 요청에 대한 완전한 응답 메시지 또한 가정으로 만들어 보겠습니다.

HTTP/1.1 200 OK
Content-Type: application/json-patch+json

[
	{
	"op": "remove", 
	"path": "/a/b/c"
	}
]

여기서 header의 Content-Type에 대한 내용이 없으면 아래 본문이 어떤 문법으로 사용되었는지 알 수 없습니다.

또한 문법을 알더라도 각 op, path 등의 의미를 알 수 있도록 명세를 patch+json와 같이 포함합니다.

 

이러한 내용들이 요청/응답 메시지에 반드시 포함되어야 Self-descriptive message 조건을 만족할 수 있습니다.

 

 

HATEOAS (Hypermedia As The Engine Of Application State)

Application의 상태는 Hyperlink를 통해 전이되어야 한다는 의미입니다.

달리 말해, HTTP 응답에 hypermedia를 통해 다음 행동에 대한 선택지를 client에 제공하는 것

(아래 이미지는 그런 REST API로 괜찮은가 영상에서 가져왔습니다.)

HATEOAS example

그림과 같이 각 페이지를 hyperlink를 통해 요청을 하고 응답받아 읽거나 생성하는 모습을 확인하실 수 있습니다.

 

이를 표준으로 나와있는 Link 헤더를 통해 json 방식으로 아래와 같이 표현할 수 있습니다.

HTTP/1.1 200 OK
Content-Type: application/json-patch+json
Link: </articles/1>; rel="prev",
      </articles/3>; rel="next";

[
	{
	"title": "The second article", 
	"contents": "second"
	}
]

즉, HATETOAS는 hypermedia를 통해 독자적인 움직임을 보조하는 것입니다.

독자적인 진화 즉, 서로 독립적인 서버와 클라이언트가 필요

 

 

 

 

이렇게 REST API의 구성 스타일과 방법에 대해서 알아봤습니다.

특히, Uniform Interface는 서버와 클라이언트의 독립적 진화를 가능하게 해 줍니다.

서버의 기능이 변경되어도 클라이언트에는 영향을 미치지 않도록 하기 위함이라는 것이죠.

처음에 봤던 Web에 영향을 미치지 않고 HTTP를 향상하기 위한 방법입니다.

다른 스타일과 함께 반드시 지켜야 하는 핵심적인 스타일이라 생각하시고, 개발 시 꼭 지켜서 REST API를 만드시길 바랍니다.

 

 

REST API에 대한 내용은 여기까지입니다. 말씀드렸던 Deview2017 영상은 꼭 한 번쯤 보시길 바랍니다.

잘못된 내용이나, 이해가 잘 안 되는 부분은 댓글로 알려주시면 늦지 않게 답변드리겠습니다. 감사합니다.

 

 

 

 

참고 자료

Paper: Representational State Transfer - Roy Fielding

이응준님 블로그 - REST의 Representation이란 무엇인가

Deview2017 - 그런 REST API로 괜찮은가