[네트워크]REST API

지난 포스팅에서는 클라이언트-서버의 아키텍쳐가 무엇이고 웹에서 클라이언트와 서버가 통신하는 것과 관련된 규약인 HTTP 프로토콜에 대해서 정리했습니다.

REST(Representational State Trnasfer) API는 로이 필딩(Roy Fielding)의 박사학위 논문에서 HTTP의 장점을 최대한 활용할 수 있는 아키텍쳐로 처음 소개 되었습니다.

REST API는 웹 에서 사용되는 데이터나 자원을 HTTP URI로 표현하고, HTTP 프로토콜을 통해 요청과 응답을 정의하는 방식을 말합니다.

Rest API를 디자인 하는 방법

레오나르드 디차드슨(Leonard Richardson)은 REST API를 잘 적용하기 위해 4단계 모델을 만들었습니다. API가 높은 단계의 조건을 충족 시킬 수록 Restful한 API라고 할 수 있습니다.

0단계(HTTP 사용)

0단계에서는 HTTP 프로토콜을 사용하여 API를 만들면 됩니다. 하지만 이 단계가 충족 된다고해서 REST API라고 할 수 없습니다. 그저 REST API를 작성하기 위한 기본 단계라고 할 수 있습니다.

// <요청>
// Start line
GET /user HTTP/1.1
// Header
// [헤더 생략]

// <응답>
// Status line
HTTP/1.1 200 OK
// Header
// [헤더 생략]
// Body
{
    { 'id' = 1, "nmae" : "Kein", "age" : 15, 'job' : "student"}
    { 'id' = 13 "nmae" : "Kein", "age" : 30, 'job' : "progamer" }
}

1단계(개별 리소의와의 통신 준수)

REST API는 웹에서 사용되는 모든 데이터와 자원을 HTTP URI로 표현하고 모든 자원은 개별 리소스에 맞는 엔드포인트(Endpoint)를 사용해야 합니다.

예를 들어 사용자 중에 'kein' 이라는 이름을 가진 사람이 여러명인 경우 각각의 'kein'은 개별 리소스로 이를 구분할 수 있는 엔드포인트가 존재해야 합니다.

엔드포인트 작성 시에는 동사, HTTP 메소드와 같은 단어 사용은 지양하며, 리소스를 나타낼 수 있는 명사를 작성하는 것이 좋습니다.

예를 들어, id값이 1인 사용자의 정보를 요청하는 경우에 다음과 같이 나타낼 수 있습니다.

// <요청>
// Start line
GET http://locallhost:8080/user?id=1 HTTP/1.1
// Header
// [헤더 생략]

// <응답>
// Status line
HTTP/1.1 200 OK
// Header
// [헤더 생략]
// Body
 { 'id' = 1, "nmae" : "John", "age" : 15, 'job' : "student" }

그리고 id값이 13인 사용자의 정보를 요청하는 경우는 아래와 같이 나태 낼 수 있습니다. 예시처럼 각 자원마다 URI를 사용하여 구분해야하며 더블어 사용한 리소스에 대한 정보와 함께 리소스 사용에 대한 성공/실패 여부를 반환해야합니다.

// <요청>
// Start line
GET / http://locallhost:8080/user?id=13 HTTP/1.1
// Header
// [헤더 생략]

// <응답>
// Start line
HTTP/1.1 200 OK
// Header
// [헤더 생략]
// Body
 { 'id' = 13 "nmae" : "Kein", "age" : 30, 'job' : "progamer" }

2단계

모델 2단계를 충족하기 위헤서는 CRUD에 맞게 적절한 HTTP 메소드를 사용하는 것에 중점을 둡니다.

조회(READ)를 위해서는 GET 메소드를 사용해야 하며, GET 메소드는 Body를 가지기 않기 때문에 query parameter를 사용하여 필요한 리소스를 전달 합니다.

생성(CREATE)를 위해서는 POST 메소드를 사용해야 하며, POST 요청에 대한 응답이 어떻게 반환되는지가 중요합니다. 이 경우 응답은 새롭게 생성된 리소스를 보내주기 때문에, 응답 코드는 201 Created 로 명확하게 작성해야 하며, 관련 리소스를 클라이언트가 Location 헤더에 작성된 URI를 통해 확인할 수 있도록 하면 완벽하게 REST 성숙도 모델의 2단계를 충족한 것이라고 볼 수 있습니다.

// <요청>
// Start line
POST / http://locallhost:8080/user HTTP/1.1
// Header
// [헤더 생략]
 { 'id' = 15 "nmae" : "Jane", "age" : 27, 'job' : "teacher" }

// <응답>
// Start line
HTTP/1.1 201 Created
Location : http://locallhost:8080/user
// Header
// [헤더 생략]
// Body 
[
 { 'id' = 1, "nmae" : "Jhon", "age" : 15, 'job' : "student" },
 { 'id' = 13 "nmae" : "Kein", "age" : 30, 'job' : "progamer" },
 { 'id' = 15 "nmae" : "Jane", "age" : 27, 'job' : "teacher" }
]

3단계

마지막으로 3단계는 HATEOAS(Hypermedia As The Engine Of Application State)라는 약어로 표현되며 하이퍼 미디어 컨트롤을 적용합니다. 3단계는 2단계와 동일하지만 리소스를 포함한 링크요소를 삽입해야 합니다.

아래의 코드는 GET 메소드를 통해 user 정보를 조회할 경우 응답의 Body에 user 정보를 추가하는 메소드와 URI를 표현한 링크로 포함시켜 새로운 기능에 접근 가능하도록 합니다.

클라이언트 개발자들이 응답에 담겨 있는 링크들을 눈여겨본다면, 이러한 링크들은 조금 더 쉽고, 효율적으로 리소스와 기능에 접근할 수 있게 하는 요소가 될 수 있습니다.

// <요청>
// Start line
GET / http://locallhost:8080/user HTTP/1.1
// Header
// [헤더 생략]

// <응답>
// Start line
HTTP/1.1 201 Created
Location : http://locallhost:8080/user
// Header
// [헤더 생략]
// Body 
[
 { 'id' = 1, "nmae" : "Jhon", "age" : 15, 'job' : "student" },
 { 'id' = 13 "nmae" : "Kein", "age" : 30, 'job' : "progamer" },
 { 'id' = 15 "nmae" : "Jane", "age" : 27, 'job' : "teacher" }
],
  "links" : {
  	addUserInfo : {
      "href" : http://locallhost:8080/user
  	  "methode" : "POST"
    }
  }

정리

위에서 정리한 성숙도 0~3단계가 모두 충족되어야 REST API라고 할 수 있겠지만 "어떤 프로젝트는 RESTful한 API를 사용하고 어떤 프로젝트는 그렇지 못한 API를 사용한다."라고 이야기하기에는 어려움이 있습니다. 주변의 웹 사이트를 보면 2단계 까지의 수준을 충족까지 만족 시키는 API도 쉽게 찾아 볼 수 있었습니다.

저는 개발 과정에서 클라이언트와 서버와의 통신에서 더 안정적이고 효율적으로 정보를 주고 받을 수 있고 이를 사용하는 다른 개발자가 이해하기 쉽도록 API를 설계하는 것이 REST API본질이며 개발자는 항상 이점을 염두해 두고 개발을 진행해야 한다고 생각합니다.

reference : https://developer.mozilla.org/ko/docs/Glossary/REST