RESTful WEB API 요약 (1)

RESTful WEB API 책을 읽으며 기억하고 싶은 내용을 기록했습니다.

출처

레오나르드 리처드슨, 마이크 애먼슨, 샘 루비. (2015). RESTful Web API(박세현, 박진형 역). 서울:인사이트. 1~2장

RESTful API의 필요성

상업적으로 성공한 API는 수 년간 유효할 것이다. 어떤 API는 수백 또는 수천 명의 사용자가 있다. 문제의 도메인이 가끔 바뀌는 수준이라 할지라도 고객들에게 미치는 영향의 총합은 엄청나게 크다.
어떤 API는 새 데이터 요소와 비즈니스 규칙이 계속 추가됨에 따라 항상 변화한다.
어떤 API는 각 고객이 필요에 따라 작업 흐름을 변경할 수 있다. API 자체는 결코 변화되지 않지만 각 고객마다 API를 사용하는 경험은 달라질 수 있다.
보통 API 클라이언트를 작성하는 사람들은 서버를 작성하는 사람과 다른 팀에서 일한다. 모든 오픈된 API는 이 카테고리에 속한다. 어떤 종류의 클라이언트가 있는지 잘 모른다면, 변화를 가하기 전에 매우 주의를 가해야만 한다. 아니면 모든 클라이언트를 망가뜨리지 않고 변화할 수 있는 디자인이 필요하다.

웹의 구조

URL 명명 규칙 자체는 결코 변화되지 않지만 각 고객마다 API를 사용하는 경험은 달라질 수 있다.
보통 API 클라이언트를 작성하는 사람들은 서버를 작성하는 사람과 다른 팀에서 일한다. 모든 오픈된 API는 이 카테고리에 속한다. 어떤 종류의 클라이언트가 있는지 잘 모른다면, 변화를 가하기 전에 매우 주의를 가해야만 한다. 아니면 모든 클라이언트를 망가뜨리지 않고 변화할 수 있는 디자인이 필요하다.

웹의 구조

URL 명명 규칙
HTTP 프로토콜
HTML 문서 형식

리소스와 표현

리소스 : URL이 붙은 것들의 기술적 용어
웹브라우저가 리소스에 HTTP 요청을 보내면 서버는 응답으로 문서를 보낸다(주로 HTML 문서지만 때로 바이너리 이미지거나 다른 것일 수도 있다). 서버가 어떤 문서를 보내건, 그 문서를 그 리소스의 표현(representation)이라고 부른다.
각 URL은 하나의 리소스를 식별한다. 클라이언트가 URL에 HTTP 요청을 보내면, 하부 리소스의 표현을 받아오는 것이다. 클라이언트가 그 리소스를 직접 보는 일은 없다.

주소 지정 가능성

주소 지정 가능성의 원칙은 모든 리소스는 각각 자신의 URL을 가져야 한다는 말이다.

상태 코드

응답 앞부분의 200은 상태 코드(ststus code)인데, 응답 코드(response code)라고 부르기도 한다. 요청이 어떻게 되었는지를 서버가 클라이언트에 빠르게 알려주는 방법이다.

짧은 세션

HTTP 세션은 하나의 요청 동안 유지된다.
무상태(stateless)라는 용어는 클라이언트가 어떤 상태인지 서버가 전혀 신경쓰지 않는다는 사실을 나타낸다.

자기 서술형 메시지

웹페이지를 요청하면 받는 HTML 문서는 요청한 그 정보만 주는 것이 아니다. 이 문서는 다음에 무엇을 해야 할지 알 수 있게 도와준다.

표준화된 메서드

GET, HEAD, POST, PUT, DELETE, PATCH

의미 체계(semantic)의 문제

문서의 구조를 이해하는 것과 문서의 의미를 이해하는 것 사이의 의미적 차이를 이어주는 것이다. (의미 체계의 문제)

간단한 API

1	$ wget -S -0 - http://www.youtypeitwepostit.com/api/

1 2	GET /api HTTP/1.1 Host: www.youtypeitwepostit.com

HTTP 응답의 구조

상태 코드(status code)

때로 응답 코드(response code)라 부른다. 세 자리 숫자로 요청이 어떻게 됐는지를 요약해 보여준다.

엔티티 바디(entity-body)

때로 본문(body)라 부른다. 클라이언트가 이해할 수 있으리라 예상되는 어떤 데이터 형식으로 작성된 문서/

응답 헤더

HTTP 응답과 엔티티 바디를 전반적으로 설명하는 키-값 묶음이다. 응답 헤더는 상태 코드와 엔티티 코드 사이에 들어간다.
가장 중요한 헤더는 Content-Type인데, HTTP 클라이언트에게 엔티티 바디를 어떻게 이해해야 할지 설명해준다.

JSON

RFC 4627에 설명된 JSON은 평문(plain-text)으로 간단한 자료 구조를 표현하는 표준이다.

API 작성하기

컬렉션에 새 항목을 생성하려면 클라이언트는 먼저 template 객체를 사용해 유효한 item 표현을 작성하고 HTTP POST를 사용해 해당 표현을 보내 서버에서 처리해야 한다.

과제요정