[번역] 레스트란 무엇인가?

앞서 이야기 해두고 싶은 말이 있는데, REST API를 공부하다가 너무 이해가 안가서 CODECADEMY의 글을 전부 해석해보기로 했다. 전문 번역가가 아니니 오역이 많다. 하지만 나의 공부에 있어서는 많은 도움이 된거 같다. 시작한다.

레스트란 무엇인가?

레스트 패러다임을 이용하여 어떻게 웹을 디자인 하는지 배워보자

구상주의적인 상태 전달

레스트, 또는 구상주의적인 상태 전달은 웹에서 컴퓨터 시스템들 사이에 기준을 제공하고 시스템끼리 소통을 쉽게 만들어 주는 건축학적 구조이다. 종종 레스트풀 시스템이라 불리우는 레스트 컴플리언트 시스템은 어떻게 레스트 컴플리언트 시스템이 비상태가 되고 서버와 클라이언트의 문제에서 분리 되는지에 따라 특징 되어진다. 우리는 이 용어들의 의미와 왜 이 시스템이 웹 서비스에서 좋은 특성을 가졌는지 알아볼것이다.

서버와 클라이언트의 분리

건축학적 구조를 가진 레스트 스타일에서는 클라이언트의 실행과 서버의 실행이 각각에 대해 알 필요 없이 독립적으로 일어 날 수 있다. 이 말인즉슨 클라이언트 사이드에 있는 코드는 서버의 작동 영향 없이 아무 때나 바뀌어 질 수 있고 서버 사이드에 있는 코드도 클라이언트의 작동 영향 없이 아무 때나 바뀌어 질 수 있다.

각각의 사이드가 어떤 메세지 형식을 다른 사이드에 보내야 하는지 알고 있는 한 그것들은 나뉘어지고 모듈형식으로 유지 될 수 있다. 데이터 저장소의 문제로부터 유저 인터페이스를 분리하여, 우리는 서버 구성요소를 단순화 함으로써 플렛폼 간의 인터페이스의 유연성과 확장성을 개선한다. 게다가 분리는 각각의 구성요소의 능력을 독립적으로 발전시킬 수 있다.


레스트 인터페이스를 씀으로써 다른 클라이언트들은 같은 레스트 엔드포인트에 도달하고, 같은 액션을 행하며 그리고 같은 응답을 얻게 된다.

비기준

레스트 패러다임을 따르는 시스템을 비기준이다, 무슨 말이냐면 서버는 어떤 기준의 클라이언트가 들어 있는지 없는지 전혀 알 필요가 없기 때문이다. 그렇다는건, 서버와 클라이언트 둘다 이전에 메세지를 볼 필요없이 어떤 메세지를 받건 다 이해할 수 있다. 비기준의 제한은 명령들 보단 리소스의 사용을 통해 강제된다. 리소스들은 웹의 명사 같은 것이다. - 리소스는 객체나 문서 또는 당신이 저장해야 하거나 다른 서비스들에 보내어지는 것이다.

왜냐하면 레스트 시스템은 리소스에 있는 보통의 작업들을 통해 상호작용 하며 인터페이스 실행에 의존하지 않기 때문이다.


이 제한들은 레스트 어플리케이션이 신뢰성과 빠른 작동성 그리고 확장성을 갖도록 도와준다 또한 구성요소들은 전체 시스템의 영향이 없이도 관리되고 업데이트 되고 재사용 될 수 있다, 심지어 시스템이 작동중에도 말이다.


이제 우리가 레스트 인터페이스를 실행 했을 때 서버와 클라이언트가 어떻게 실제로 통신하는지 알아 보자.

클라이언트와 서버의 통신

레스트 구조에서는 클라이언트가 리소스를 검색하거나 수정하기 위한 요청을 보내고 서버는 이 요청에 대한 응답을 보낸다. 요청하고 응답을 보내는 표준적인 방법들에 대해 알아보자.

요청하기

레스트는 클라이언트가 서버에 있는 검색 또는 수정되어진 데이터를 위해 서버에 요청 보내기를 요구한다. 요청은 보통 이렇게 구성 되어 있다:

• HTTP 동사는 어떤 종류의 작동을 수행할지 정한다.
• 헤더는 클라이언트가 요청에 대한 모든 정보를 알 수 있게 해준다. (실패 했는지 성공 했는지 무엇이 문제인지 등등 뒤에 자세히 나옴)
• 리소스로 가는 길
• 데이터를 포함한 선택적인 메세지 바디

HTTP 동사

레스트 시스템 안에서 리소스와 상호작용하기 위해 쓰여지는 기본적인 HTTP 동사는 4가지가 있다. (크롤링을 배워본 사람들은 본적이 있을듯.)

• GET — 특정한 리소스(id 값으로) 또는 리소스 모음을 찾아준다
• POST — 새로운 리소스를 만든다
• PUT — 특정한 리소스를 업데이트 한다 (id 값으로)
• DELETE — id 값으로 특정한 리소스를 제거한다

여기 Codecademy의 글을 보면 HTTP 동사들에 대해 더욱 자세히 배워 볼 수 있다:

• CRUD는 무엇인가?

헤더와 어셉트 변수

요청으로 온 헤더에는 클라이언트가 서버로부터 받을 수 있는 컨텐츠 타입을 보내준다. 이걸 어셉트 필드라고 부르는데, 이것은 클라이언트에 의해 이해하지 못하거나 진행 할 수 없는 데이터를 서버에 보내지 않게 만들어준다. 컨텐츠 타입들을 위한 옵션들은 MIME 타입들이라고 한다.(또는 다목적 인터넷 메일 확장판 MDN Web Dos에서 더욱 자세히 알아 볼 수 있다.)

MIME 타입은 한때 어셉트 필드에서 type과 subtype에 의존한 컨텐츠 타입들로 명시 되곤 했었다. 이들은 슬레시(/)로 나눈다.

예를 들어 HTML을 담고 있는 텍스트 파일은 text/html로 명시되어야 할것이다. 만약 텍스트 파일이 html 대신에 css를 담고 있다면, text/css로 명시 될 것이다. 일반 텍스트 파일은 text/plain으로 표시된다. 하지만 이 기본값 text/plain은 모든 범주를 포함 하지는 않는다. 만약 클라이언트가 text/css를 예상하고 있는데 text/plain을 받는다면, 클라이언트는 컨텐츠를 인식 할 수 없을 것이다.

다른 타입들과 많이 쓰이는 서브타입들:

• image — image/png, image/jpeg, image/gif
• audio — audio/wav, audio/mpeg
• video — video/mp4, video/ogg
• application — application/json, application/pdf, application/xml, application/octet-stream

예를 들어 클라이언트가 서버, articles안에 있는 id 23에 접속하기 위해서는 GET 요청을 다음과 같이 보내야 한다.

GET /articles/23
Accept: text/html, application/xhtml

이런 경우에 어셉트 헤더 필드는 클라이언트가 text/html 또는 application/xhtml에 관한 컨텐츠를 받을 수 있다고 보여주고 있다.

경로 (우리가 흔히 보는 인터넷 주소가 PATH(경로)임)

요청은 반드시 동작이 실행 될 수 있는 리소스로 가는 경로를 포함하여야 한다. 레스트 API 안에서, 경로는 무슨일이 벌어지는 있는지 클라이언트가 아는 것을 돕기위해 지정되어야한다.
대체적으로 경로의 첫번째 부분은 리소스의 복수 형태로 되어야한다. 이것은 중첩된 경로를 읽기 간결하게 하고 쉽게 이해할 수 있도록 해준다.

만약 당신이 이런 특정한 경로를 본적이 없다 하더라도 fashionboutique.com/customers/223/orders/12 라는 경로는 이것이 무엇을 가리키는지 명확하다. 왜냐하면 이것은 계층의 구분이 확실하고 서술적이기 때문이다. 우리는 customer id 223에 id12로 접속 한것을 알 수 있다.

경로에는 필요한 특정수준의 리소스를 찾는데 필요한 정보가 포함되어야 한다. 리스트나 리소소의 모음을 조회 할 때, 항상 id를 추가할 필요는 없다. 예를 들어 POST 방식으로 fashionboutique.com/customers에 요청을 할 때는 서버가 새로운 대상을 위해 id를 생성 해냄으로써 여분의 식별자가 필요하지 않다.

만약에 우리가 하나의 리소스에 접속 한다면, 경로에 id를 넣어햐 할지도 모른다. 예 : GET fashionboutique.com/customers/:id — 아아템을 특정한 id 이용하여 customers 리소스 안에서 찾아옴. DELETE fashionboutique.com/customers/:id — 아이템을 특정한 id를 이용하여 customers 리소스 안에서 삭제.

응답 전송

컨텐츠 타입들

만약 서버에서 데이터 페이로드를 클라이언트에 보낸다면, 서버는 반드시 리소스 헤더에 잇는 content-type를 포함하여야 한다. content-type 헤더 필드는 클라이언트에게 응답 바디 안에서 보내지고 있는 데이터 타입을 알려준다. 컨텐츠 타입들은 MIME 타입이다, 이 컨텐츠 타입들은 요청 헤더의 accept필드에 있다. 응답 속에 서버가 되돌려 보내는 content-type는 요청의 accept 필드에서 클라이언트가 특정하는 하나의 옵션이어야 한다.

예를 들어, 클라이언트가 articles 리소스 안에 있는 id 23 접근을 할 때 이런 GET방식 요청을 한다.

GET /articles/23 HTTP/1.1
Accept: text/html, application/xhtml

서버는 아마 컨텐츠를 응답 헤더와 함께 되돌려보낼것이다:

HTTP/1.1 200 (OK)
Content-Type: text/html

이것은 요청된 컨텐츠가 응답 바디에서 클라이언트가 수용할 수 있는 text/html과 함께 돌아오는 것을 의미한다.

응답 코드

서버에서 응답은 클라이언트에게 작업의 성공여부를 알려주기 위해 상태코드를 포함하여 보여준다.
개발자로서, 엄청 많은 상태 코드들을 다 알필요는 없지만 자주 사용되는 것들은 어떻게 사용 되는지 알아 둘 필요가 있다.
|상태 코드|의미|
| :-------- | :---- |
|200 (성공)|서버가 요청을 제대로 처리했다는 뜻이다. 이는 주로 서버가 요청한 페이지를 제공했다는 의미로 쓰인다.|
|201 (작성됨)|성공적으로 요청되었으며 서버가 새 리소스를 작성했다.|
|204 (콘텐츠 없음)|서버가 요청을 성공적으로 처리했지만 콘텐츠를 제공하지 않는다.|
|400 (잘못된 요청)|서버가 요청의 구문을 인식하지 못했다.|
|403 (금지됨)|서버가 요청을 거부하고 있다. 예를 들자면, 사용자가 리소스에 대한 필요 권한을 갖고 있지 않다.|
|404 (찾을 수 없음)|서버가 요청한 페이지(Resource)를 찾을 수 없다. 예를 들어 서버에 존재하지 않는 페이지에 대한 요청이 있을 경우 서버는 이 코드를 제공한다.|
|500 (내부 서버 오류)|서버에 오류가 발생하여 요청을 수행할 수 없다.|

상태 코드 부분에 한에서 출처(위키백과) :https://ko.wikipedia.org/wiki/HTTP_%EC%83%81%ED%83%9C_%EC%BD%94%EB%93%9C
음 테이블 부분이 마크다운이 안되는데 이유를 아시는분...

각각의 HTTP 동사에 성공시 예상 되는 서버의 응답들:

• GET — return 200 (OK)
• POST — return 201 (CREATED)
• PUT — return 200 (OK)
• DELETE — return 204 (NO CONTENT) 만약 작동이 실패하면, 서버가 맞닥뜨린 문제에 상응하여 가장 자세한 상태 코드를 되돌려 줄것이다.

요청과 반응의 예시

우리가 어플리케이션으로 작은 옷가게인 fashionboutique.com의 고객이나 주문들을 보고 작성하고 고치고 삭제할 수 있다고 가정해보자. 클라이언트가 이러한 기능들을 사용 할 수 있게 해주는 HTTP API를 만들었다고 해보자:

만약 우리가 모든 고객을 보고싶다면 요청은 이렇게 보낼 수 있다:

GET http://fashionboutique.com/customers
Accept: application/json

되돌아 오는 응답 헤더는 이렇다:

Status Code: 200 (OK)
Content-type: application/json

요청된 customers 데이터는 application/json포멧 형식으로 온다.

POST 방식으로 새로운 고객 데이터 만들기:

POST http://fashionboutique.com/customers
Body:
{
    "customer": {
        "name" = "Scylla Buss",
        "email" = "scylla.buss@codecademy.org"
    }
}

서버는 id 라는 대상을 만들어낸 다음에 아래의 헤더와 함께 클라이언트에게 되돌려 보내준다.

201 (CREATED)
Content-type: application/json

하나의 고객 정보를 보기 위해 특정 고객 아이디를 GET 방식으로 가져오려면:

GET http://fashionboutique.com/customers/23
Accept: application/json

예상 가능 응답 헤더는 :

Status Code: 200 (OK)
Content-type: application/json

application.json 포멧 형식으로 id 23의 customer 데이터 정보를 가져올 것이다.

새로운 데이터를 PUT 방식으로 업데이트를 해줄 수도 있다.

PUT http://fashionboutique.com/customers/123
Body:
{
    "customer": {
        "name" = "Scylla Buss",
        "email" = "scyllabuss1@codecademy.com"
    }
}

응답 헤더에서는 클라이언트에게 id가 123으로 수정이 되었다는 것을 알려주기위해 Status Code: 200 (OK)를 보여줄것이다.

또한 DELETE 방식으로 특정한 id를 지울 수도 있다:

DELETE http://fashionboutique.com/customers/123

응답은 Status Code: 204 (NO CONTENT)를 포함하고 클라이언트에게 id 123이 삭제되었다고 알려주고 바디에 아무런 내용이 없는 헤더를 보내 줄 것이다.

레스트로 연습하기

우리가 사진 모음 사이트를 만든다고 상상해보자. 우리는 사용자, 장소, 그 장소들의 사진들을 계속 추적하는 API를 만들기를 원한다. 이 사이트는 index.html과 style.css를 가지고 있다. 각각의 사용자는 유저네임과 패스워드를 가지고 있다. 각각의 사진(유저가 찍은)은 장소와 저작권자가 있다. 각각의 장소들도 명칭과 주소들이 있다. 아래의 기능을 제공하는 레스트 시스템을 디자인 할 수 있니:

• 사용자와 사진, 장소를 저장
• 장소에 접속하고 어떤 장소의 어떤 사진에 접속

아래 내용에 대해 생각해보고 계획을 먼저 세워보기

• 어떤 종류의 요청에 대해 우리가 만들기를 원하는지
• 서버가 어떤 응답을 되돌려 보내 줄 것인지
• 각가의 응답이 어떤 content-type 일 것인지

가능한 솔루션 - 모델

{
    "user": {
        "id": <Integer>,
        "username": <String>,
        "password":  <String>
    }
}

{
    "photo": {
        "id": <Integer>,
        "venue_id": <Integer>,
        "author_id":  <Integer>
    }
}

{
    "venue": {
        "id": <Interger>,
        "name": <String>,
        "address":  <String>
    }
}

가능한 솔루션 - 요청과 응답

GET 방식 요청

Request- GET /index.html Accept: text/html Response- 200 (OK) Content-type: text/html

Request- GET /style.css Accept: text/css Response- 200 (OK) Content-type: text/css

Request- GET /venues Accept: application/json Response- 200 (OK) Content-type: application/json

Request- GET /venues/:id Accept: application/json Response- 200 (OK) Content-type: application/json

Request- GET /venues/:id/photos/:id Accept: application/json Response- 200 (OK) Content-type: image/png

POST 방식 요청

Request- POST /users Response- 201 (CREATED) Content-type: application/json

Request- POST /venues Response- 201 (CREATED) Content-type: application/json

Request- POST /venues/:id/photos Response- 201 (CREATED) Content-type: application/json

PUT 방식 요청

Request- POST /users Response- 201 (CREATED) Content-type: application/json

Request- POST /venues Response- 201 (CREATED) Content-type: application/json

Request- POST /venues/:id/photos Response- 201 (CREATED) Content-type: application/json

DELETE 방식 요청

Request- DELETE /venues/:id Response- 204 (NO CONTENT)

Request- DELETE /venues/:id/photos/:id Response- 204 (NO CONTENT)

번역 전 본문 내용 Codecademy : https://www.codecademy.com/articles/what-is-rest

영어 공부겸 타자 연습겸 REST API 공부할겸 겸사겸사 했더니 시간이 상당히 오래걸렸다. 도움이 되길 바라며 적어도 내 자신에게는 도움이 된거 같아 뿌듯하다. 그럼 20000