12장 리소스 설명과 연결된 데이터 표현 전략(Representation Strategy) 클라이언트가 GET 요청을 리소스의 URL로 보내고 해당 리소스의 표현을 받는 것을 말한다. 리소스가 자기 자신에 대해 말 하는 것. 이 책에서 다룬 데이터 형식지금까지 이 책에선 이걸 허용했다. 설명 전략(description strategy) 표현의 리소스보다 다른 리소스들에 대해 말하는 것 RDF(Resource Description Framework) 리소스 설명 프레임워크 설명 전략에만 집중한 형식 그룹 어떤 리소스에 대해 누가, 무엇을, 어떻게 설명했는지 구조적으로 표현하는 방식 이걸 기계가 이해할 수 있는 방식으로 정리하는 것 ...
11장 API를 위한 HTTP WWW가 기술스택이라면 3단계로 나눌 수 있다. 맨 아래: URL, 리소스 리소스 위: HTTP 프로토콜, 리소스 표현을 읽는 권한한과 기본적인 리소스 상태에 쓰는 권한 맨 위: 하이퍼미디어, 하나의 웹 사이트나 API의 프로토콜 의미 체계 ⇒ 이 책에서 지금까지 다룬 것 새로운 HTTP1.1 설계 명세서 RFC 2616 HTTP 프로토콜 의미 체계를 명확히 하는 것 응답 코드 엔티티 바디는 응답 코드에 대한 설명(문제가 무엇인지)이 담겨야 한다. 200(OK)와 에러 메시지를 함께 보내지 마라. RFC 2616에 있는 것 외에 새로운 것을 정의히지 마라 헤더 RFC 2616에 있는 것 외에 새로운 것을 정의하지 마라 표현들 사이에서 선택하기 서버가 하나의 리소스에 대해 다양한 표현을 제공할 때 클라이언트가 이것들을 어떻게 구분해야 할까? ...
10장 하이퍼미디어 동물원 정말 다양한 하이퍼미디어 유형들이 있다. 이에 대해서 더 자세히, 기술적으로 알고 싶다면 해당 하이퍼미디어의 형식 명세서를 읽으면 된다. 도메인 특화 형식 Maze+XML: 미로게임 오픈서치(OpenSearch): 검색 쿼리 문제 상세 문서: 오류 조건을 설명 SVG: 이미지 형식, 벡터 그래픽 VoiceXML: 대화 말하기(음성 인식) 컬렉션 패턴 형식 Collection+JSON: 컬렉션과 아이템 AtomPub OData 필터링: 쿼리 언어를 사용하여 내재된 프로토콜 의미 체계의 집합을 정의 함수들과 메타데이터 문서 서비스 설명 문서로서 메타데이터 문서 순수 하이퍼미디어 유형 HTTP의 프로토콜 의미 체계를 표현하는 데 집중 HTML, HAL, 사이렌, Link 헤더, Location과 Content-Location 헤더, URL 목록, JSON 홈 문서,Link-Template 헤더, WADL, XLink, XForms, GeoJSON: 일반적인 하이퍼미디이 컨트롤, 미디어 유형이 없는 결함있음 의미 체계 동물원 연결 관계의 IANA 등록부 마이크로포맷 위키 hCalendar, hCard, XFN, XOXO,adr, geo, hAtom, hListing, hMedia, hNews, hProduct, hRecipe, hResume, hReview 등 마이크로포맷 위키의 연결 관계, schema.rog, 더블린 코어, 액티비티 스트림즈, ALPS 등록부
9장 설계 절차(1) 2단계 설계 절차 가장 단순한 형태 표현에 사용할 미디어 유형을 선택한다. 프로토콜 의미 체계(HTTP 프로토콜 하에서 API의 행동 양식)와 애플리케이션의 의미 체계(표현이 참조할 수 있는 실제 세계의 것들)에 제약 사항들을 결정 그 외 모든 것을 다루는 프로파일을 작성한다. JSON을 선택 ⇒ 프로토콜 애플리케이션 의미 체계에 아무런 제한이 없음 ⇒ 2에 모든 시간을 소비 7단계 설계 절차 API에서 클라이언트가 얻길 원하는 것이나 또는 API를 통해 넣길 원하는 모든 정버를 열거함 의미 체계 서술자 API를 나타내는 상태 다이어그램을 그림 연결 관계 기존에 있는 프로파일의 문자열을 이 API의 마법 문자열과 조정함 이 API의 프로토콜 의미 체계와 애플리케이션 의미 체계와 호환되는 미디어 유형을 선택하거나 새롭게 정의 애플리케이션 의미 체계를 기술하는 프로파일을 작성 코드 작성 광고판 URL 게시 미로 게임을 예시로 둔다. ...
8장 프로파일 현재까지 공부한 API 설계의 규칙 프로토콜 의미 체계의 문제 해결법 내 문제에 맞는 도메인 특화표준이 있다? ⇒ 사용 애플리케이션 특화 확장은 문서화 내 문제에 맞는 컬렉션 패턴이 있다? ⇒ 사용 애플리케이션 특화 용어를 정의하고 문서화 둘 다 해당되지 않으면? ⇒ 일반적인 하이퍼미디어 유형 사용 애플리케이션을 상태 전이로 나누고 문서화 애플리케이션 의미 체계의 문제 해결법 내 문제에 맞는 마이크로데이터 아이템이나 마이크로포맷이 있다? ⇒ 사용 문서화 없으면 애플리케이션 특화 용어를 정의 문서화 결국 문서화는 필요하다. ...
7장 순수 하이퍼미디어 설계 왜 HTML인가? HTML은 세상에서 가장 인기 있는 하이퍼미디어 유형이다. HTML의 기능 텍스트 문서의 중첩 구조를 표현할 수 있다. 택스트 콘텐트와 기타 태그를 표현할 수 있다. 하이퍼미디어 컨트롤 HTML은 다음과 같은 하이퍼미디어 컨트롤을 내장하고 있다. <link>, <a>, <img>, … 플러그인 애플리케이션 의미 체계 HTML은 사람이 이해할 수 있는 문서를 다룬다. HTML은 원래의 용도 외의 목적으로 사용하기가 매우 쉽다. HTML4는 세 가지 일반 속성을 더 가진다. rel : 연결되는 리소스와 지금 리소스 사이의 관계를 정의 id : 문서 내 한 요소를 식별하는 고윳값 class : 태그의 애플리케이션 의미 체계를 전달하는 용도(속하는 클래스를 정의) 마이크로포맷 hCard같은 마이크로포맷은 HTML에 추가적인 애플리케이션 의미 체계를 더하게 해준다. hMaze 마이크로포맷 새로운 hCard같은 마이크로포맷을 정의하는 것은 쉽다. 몇개의 클래스의 의미만 정의하면된다. 마이크로데이터 마이크로데이터는 HTML 5용으로 마이크로포맷을 다듬은 것이다. 다섯 개의 새로운 속성이 있다 itemprop : 마이크로포맷이 class 속성을 사용하던 방식으로 사용 itemscope : boolean. 태그에 마이크로데이터가 있는가를 표시 itemtype : 해당 마이크로데이터의 의미를 확인할 수 있는 곳 itemid itemref 마이크로포맷을 사용할땐 class=hCard 가 붙은 태그 내부가 모두 hcard 포맷임을 알 수 있다. 마이크로데이터는 그렇지 않다. itemscope 내부는 itemtype 이 가리키는 문서로 작성되어 있다고 표현된다. 예시 1 2 3 4 5 <div itemscope itemtype="https://www.naver.com/..."> <div itemprope="cell"> ... </div> </div> 마이크로포맷은 rel로 연결 관계를 정의할 수있지만 마이크로데이터는 그렇지 않다. itemtype 문서에는 나타날 것. 리소스 상태 변경하기 스위치를 누르면 리소스의 상태와 관계가 변경된다고 해보자 이 스위치를 조작하는 요청은 하이퍼미디어로 어떻게 구현될까? 폼에 애플리케이션 의미 체계 추가하기 rel 속성은 두 리소스 사이의 관계를 나타낸다. ‘리소스 상태를 변경하라’는 의미를 가진 rel 값을 만들 수 있을까? 리소스들이 나열되고 그 리소스를 요청하는 것은 GET 요청이다. 하지만 리소스 상태 변경은 GET 요청을 쓸 수 없다. POST를 써야한다. 이때 HTML이 정의한 하이퍼미디어 폼을 사용하면 된다. 대신, rel 속성은 지원하지 않는다. 이 switch 클래스도 hMaze 마이크로포맷에 추가할 수 있겠다. 1 2 3 <form action="/switches/4" method="post"> <input class="flip" type="submit" value="Flip it!"/> </form> 하이퍼미디어의 대체재는 미디어다 요즘 API 문서들에는 많은 메서드가 개별 API 호출로 노출되고, 상세하게 문서화되어 있다. 이는 다시 말해, 사람이 읽을 문서를 하이퍼미디어 대체재로 사용하고 있다는 것이다. 사람 대신, 이 정보를 받도록 의도된 대상(소프트웨어)에 맞춰 작성해야 한다. 스위치를 나타내는 두 버전을 살펴보자 1 2 3 4 스위치를 조작하려면 다음 주소로 POST 요청을 보낸다. https://api.example.com/swithches/{id}?action=flip {id}는 스위치 ID다. 스위치가 있는 셀에 있을 때에만 스위치를 조작할 수 있다. 1 2 3 4 5 6 7 <div class="swithch"> <span class="position">down</span> <form action="/swithches/4" method="post"> <inpuit class="flip" type="submit" /> </form> </span> </div> 애초에 하이퍼미디어 컨트롤을 사용할 수 있을 때만 제시되므로, 셀에 있을때에만 조작할 수 있다는 경고문구는 제공할 필요도 없다. HTML의 제약 기술적으로 HTML은 일반 하이퍼미디어 포맷이 아니라 도메인 특화 표준이다. 여기서 발생하는 한계들이 있다 PUT, DELETE는 HTML 하이퍼미디어 컨트롤로는 표현할 수 없다. HTML 4의 폼은 두 가지 종류의 엔티티 바디만 만들 수 있다. application/x-www-form-urlencoded multipart/form-data HTML 4는 JSON과 달리 숫자와 문자열을 구분하지 않는다. HTML 4는 날짜를 표시할 방법을 정의하지 않는다. HTML5가 문제를 해결해 줄까? 보완점 날짜 문제 ⇒ time 태그로 해결 숫자 문제 ⇒ 일반적으로 동작하지 않음 몇 가지 컨트롤을 더 정의하나, 여전히 유용하지 않음 input 태그 검증을 위한 방법 정의 일부는 보완되나, 하이퍼미디어 포맷으로서의 HTML을 급격히 변화시키지는 않는다. 하이퍼텍스트 애플리케이션 언어 웹 API에 특화되어 설계된, HTML의 기본 개념인 하이퍼링크만 가져온 HAL(Hypertext Application Language)가 있다. HAL은 두 가지 방식으로 제공된다. XML(application/hal+xml) JSON(application/hal+json) HTML과 HAL의 차이 HTML에는 여러가지 경우에 따라 <a>, <img>, <form> 을 사용한다. ...
6장 컬렉션 패턴 Collection+JSON은 여러 도메인에 걸쳐 반복해서 나타나는 패턴(컬렉션)을 다루기 위해 만들어졌다. 컬렉션은 무엇인가? 다른 리소스들의 링크를 걸어 나열하는 리소스다. 다른 리소스들을 한 그룹으로 묶는게 존재 목적이다. 아이템에 연결하는 컬렉션 아이템(item), 엔트리(entry), 멤버(member) : 컬렉션에 포함된 개별 리소르를 부르는 동의어 아이템이라해서 그 리소스 자체가 아니다. 친구 전화번호부의 콜렉션은 내가 아니다. Collection+JSON href: 컬렉션 자체의 영속적인 링크 items: 컬렉션 멤버를 가리키는 링크와 그것들의 부분 표현 links: 컬렉션에 관계된 다른 리소스를 연결한다. queries: 컬렉션 검색을 위한 하이퍼미디어 컨트롤 template: 컬렉션에 새 항목을 추가하기 위한 하이퍼미디어 컨트롤 아이템 표현하기 각 멤버는 JSON 객체로 표현된다. href 속성 : 해당 아이템을 독립 리소스로 나타내는 영속적인 링크 links:: 그 아이템에 연관된 다린 리소스의 하이퍼미디어 링크 data: 해당 아이템의 표현의 중요한 부분을 나타내는 기타 정보 아이템의 영속적인 링크 href 속성의 URL에 GET 요청을 보내면 서버는 한 아이템에 대한 Collection+JSON 표현을 보낸다. 아이템의 데이터 아이템의 data 슬롯에 JSON 객체 배열로 들어간다. name과 value 프로퍼티가 각각 단일 키-값 묶음을 나타낸다. 선택사항인 prompt는 사람이 이해할 수 있는 설명이다. 아이템의 링크 특정 아이템 하나를 참조하고 싶을 때 클라이언트가 사용할 특별할 URL이다. links라는 목록이 포함될 경우, 여기에 관련된 리소스를 연결하는 하이퍼미디어 링크 여러 개가 포함된다. 쓰기 템플릿 새 아이템을 컬렉션에 추가하려면 쓰기 템플릿에 적혀있는 형식으로, 컬렉션의 href로 POST 요청을 보내면 된다. 쓰기 템플릿은 개념적으로 HTML 폼과 동일하다. 동일한 입력을 하면 똑같은 요청을 보낸다는 의미다. 폼으로 보내면 application/x-www-form-urlencoded, 쓰기 템플릿으로 보내면 application/vnd,collection+json 일 뿐이다. 검색 템플릿 queries 슬롯에 저장된다. (일반) 컬렉션은 어떻게 동작하는가? GET 표현을 제공한다. 표현의 미디어 유형은 그 리소스로 무엇을 할 수 있는지 말해준다. application/vnd,collection+json : Collection+JSON 표준의 규칙 적용 application/atom+xml: AtomPub 규칙이 적용 applcation/json: 맘대로 하겠다. POST로 추가하기(POST-to-Append) 새 리소스를 생성 PUT과 PATCH 몇 개의 요소를 한 번에 수정하거나 개별 요소를 제거하는 데 사용 DELETE 무언가를 삭제하기 위해 존재 페이지 나눔 링크가 많을 경우 나눠서 제공한다. <link rel=”next” href=”/collection/4iz6”/> : 다음 next, previous, first, last, prev 등이 제공될 수 있다. 검색 폼 AtomPub(Atom Publishing Protocol) Collection+JSON의 item은 어떤것이든 나타날 수 있다. 반면 AtomPub은 뉴스 기사를 게시할 목적으로 설계되었다. 또한 뉴스 기사에 필요한 필드들이 존재한다. XML을 처리하는 방식때문에 도태됨 사람들은 자신이 필요로 하는 표준이 아니라면 해당 표준을 배우려 하지 않는다. 의미 체계의 문제: 잘 대응하고 있는가? 우리는 ‘컴퓨터가 어떤 링크를 클릭하도록 결정하게 하려면 어떻게 프로그래밍을 해야 할까?’에 대해 생각 중 컬렉션 패턴은 두 가지 다른 종류의 리소스를 인식한다 ⇒ 아이템 유형 리소스 : GET, PUT, DELETE에 응답 컬렉션 유형 리소스 : GET, POST에 응답 컬렉션과 아이템의 차이점 : 의미체계에서 나온다. 컬렉션 패턴에서 어떤 행동을 하기 위해 무엇이 필요한지는 알 수 있다. 하지만 필요한 필드의 의미를 알기 위해선 여전히 설명이 필요하다.
5장 도메인 특화 설계 요청을 보내고 클라이언트가 되돌려 받는 하이퍼미디어는 미로의 길을 알려줄만큼 다음 선택지에 대한 정보를 제공해야 한다. 클라이언트는 그들의 원하는 일을 한다 미로 지도라는 리소스의 표현에서 출구를 찾던, 지도를 작성하던, 요청 몇개 보내고 지도를 완성했다고 거짓말을 하던 상관이 없다. 클라이언트와 서버는 서로 주고받는 표현의 이해를 공유하고 있어야 하지만 풀어야 하는 문제가 무엇인지 함께 인식할 필요는 없다. 표준 확장하기 미로를 3차원으로 확장한다면 어떤 클라이언트는 작동에 이상없으나 어떤 클라이언트는 문제가 생긴다. ...
4장 하이퍼미디어 클라이언트는 어떤 요청을 해야 할지 어떻게 아는 것일까? ⇒ 하이퍼미디어 하이퍼미디어는 서버가 클라이언트에게 나중에 어떤 HTTP 요청을 보낼 수 있을지 설명하는 방식이다. 하이퍼미디어 유형으로서의 HTML <a> 태그는 HTTP GET 요청을 만들 수 있음을 브라우저에 알려주는 신호다. 더 정확히는, 특정 URL이 방문할 수 있는 리소스를 부른다는 웹 서버의 약속 사용자가 활성화할 때만 요청(클릭)이 진행된다. <img> 태그도 요청할 수 있는 HTTP GET 요청을 설명하긴 하지만, 문서 사이를 이동한다는 뜻은 담겨 있지 않다. ...
3장 리소스와 표현 REST는 설계 제약 조건 모음이다. 무엇이든 리소스가 될 수 있다 사용자가 어떤 작업을 취하고 싶다면 그것을 리소스로 만들어야 한다. 리소스에는 딱 하나의 제약만 있다. 모든 리소스는 URL을 가져야 한다. 다시말해, 무언가에 URL을 부여하면 그건 리소스가 된다. 리소스의 기본 형태는 비트 스트림이다. 클라이언트는 URL과 리소스의 표현만 볼 뿐이다. 표현은 리소스의 상태를 설명한다 표현 : 클라이언트가 리소스에 GET 요청을 보내면 그 리소스를 유용한 방식으로 나타내는 문서를 제공해야 한다. “기계가” 읽을 수 있는 설명으로 나타낸 것 표현은 양방향으로 전송된다. 클라이언트도 POST 요청에서 리소스의 표현을 보낸다. 새 리소스가 어떻게 보여야 하는지에 대한 클라이언트의 생각이 나타난다. 서버는 그 표현을 추가하거나 변경하거나 일부 무시할 수 있다. 데이터베이스 필드에 항상 created_at 과 updated_at 을 남김 표현의 상태 전송 서버는 리소스의 상태를 나타내는 표현을 보낸다. 클라이언트는 그 리소스가 가졌을면 좋을 상태를 설명하는 표현을 보낸다. 많은 표현이 있는 리소스 하나의 리소스에 여러 표현이 있을 수 있다. 다양한 언어, 파일 형식 등 클라이언트가 원하는 표현을 지정하는 법 HTTP 헤더의 값 각 표현마다 별개의 URL 부여 HTTP의 프로토콜 의미 체계 클라이언트가 리소스에 원하는 행동에 대한 규칙이 있다. 미리 정의된 프로토콜을 따라 메시지를 보낸다. 웹 API에선 이 프로토콜이 HTTP다. GET: 리소스의 표현을 얻음 DELETE: 리소스를 제거 POST: 주어진 표현에 기반을 두고 이 리소스 아래 새 리소스를 생성 PUT: 이 리소스의 현재 상태를 주어진 표현으로 대치(전체) PATCH: 이 리소스의 일부 상태를 주어진 표현으로 변경(일부) HEAD: 이 리소스의 표현과 함께 주어질 헤더를 받음(표현은 X) OPTIONS: 이 리소스가 어떤 HTTP 메서드에 응답하는지 알아냄 LINK: 다른 리소스를 이 리소스에 연결 UNLINK: 다른 리소스와 이 리소스의 연결 관계를 제거 모든 요청은 프로토콜 의미 체계가 동일하지만, 애플리케이션 의미 체계는 다르다. GET 정보를 요청할 뿐이라 안전한 메서드여야 한다. 리소스 상태를 바꿀 것을 예상해서는 안된다. DELETE 삭제하는 메서드 멱등성(idempotence) DELETE 요청은 두 번 이상 보내도 한번 보낸것과 같은 결과가 나와야 한다. 지운걸 또 지우려는 요청을 보내도 처음 지웠을 떄와 동일하기 때문이다. 수학 0을 곱하는 것과 같은 이치 GET도 마찬가지다. 리소스가 변하지 않으므로 PUT도 마찬가지. 같은걸 계속 덮어써도 결과는 동일하므로 POST로 추가하기 새로운 리소스를 생성 PUT 덮어쓰기 PATCH 일부만 수정할 경우 멱등성이 없다. 예를 들어, 특정 값을 1 증가시키는 요청을 보내면 멱등성이 없다. PUT은 리소스 전체상태의 교체기 때문에 이러한 요청이 없다. 특히 PUT은 전체상태를 모르는 상태에서 이렇게 만들기 위해 쓰기도 한다. 반면 PATCH는 현재 상태를 알고 이를 일부 변화시키기 위한 요청 아직 HTTP 명세에 정의되지 않았다. LINK와 UNLINK 리소스 간 하이퍼미디어 링크를 관리 멱등하지만, PATCH와 마찬가지로 명세에 정의되지 않아 안전하지 않음 HEAD GET을 헤더에만 적용하는 느낌이라 안전함 GET 대신 쓰더라도 시간이 줄어들진 않지만, 대역폭 사용량은 줄어든다. OPTIONS 응답 헤더에는 HTTP Allow가 담겨, 해당 리소스가 지원하는 HTTP 메서드를 나열한다. 잘 설계된 API는 이 요청이 없어도 응답에 제공되는 하이퍼미디어 문서로 알게끔 해준다. 오버로드한 POST 사실 온갖 종류의 변화에 다 쓰이는게 POST다. ...