8장 프로파일

현재까지 공부한 API 설계의 규칙

프로토콜 의미 체계의 문제 해결법

  • 내 문제에 맞는 도메인 특화표준이 있다? ⇒ 사용
    • 애플리케이션 특화 확장은 문서화
  • 내 문제에 맞는 컬렉션 패턴이 있다? ⇒ 사용
    • 애플리케이션 특화 용어를 정의하고 문서화
  • 둘 다 해당되지 않으면? ⇒ 일반적인 하이퍼미디어 유형 사용
    • 애플리케이션을 상태 전이로 나누고 문서화

애플리케이션 의미 체계의 문제 해결법

  • 내 문제에 맞는 마이크로데이터 아이템이나 마이크로포맷이 있다? ⇒ 사용
    • 문서화
  • 없으면 애플리케이션 특화 용어를 정의
    • 문서화

결국 문서화는 필요하다.

클라이언트는 문서를 어떻게 찾는가?

  • 요청과 응답은 추측이 없이, 자기 서술형 메시지여야 한다.
  • 의미 체계는 두 종류가 있다.
    • 프로토콜 의미 체계
    • 애플리케이션 의미 체계
  • hCard를 사용하는 HTML 문서 ⇒ 파싱으로 프로토콜은 알 수 있으나 애플리케이션은 알 수 없다.
  • 트위터 API에서 제공하는 JSON 문서 ⇒ 둘 다 알수 없다.
  • 여기서 알 수 없는(빠진) 규격을 **프로파일(profile)**이라고 부른다.

프로파일이 뭘까?

RFC 6906에 나온 정의

프로파일은 리소스 표현 자체의 의미 체계를 변경하기 위함이 아니라 클라이언트에게 미디어 유형에 의해 정의된 의미 체계에 더해 그 리소스 표현에 연계된 추가적인 의미 체계를 알 수 있게 하기 위해 정의된다.

프로파일에 연결하기

hCard를 사용하는 HTML 문서와 트위터 API에서 제공되는 JSON 문서에서 빠진것은 프로파일과 그것을 사용하는 문서사이의 연결이다.

클라이언트 : 그래서 어떤 프로파일이 적용되는데? ⇒ 하이퍼미디어로 연결해줄 수 있다.

profile 연결 관계

rel="profile"을 가진 태그.

profile 미디어 유형 매개 변수

헤더에 있는 Content-Type 에 추가할 수 있다.

Content-Type: application/json'profile="https://dev.twitter.com/docs

특수 목적 하이퍼미디어 컨트롤

<div itemscope itemtype="http://schema.org/Person">

프로파일은 프로토콜 의미 체계를 설명한다

  • 프로파일은 JSON처럼 하이퍼미디어 컨트롤이 없는 미디어 유형과 같은 경우에만 프로토콜 의미 체계를 설명할 필요가 있다.
  • HTML 처럼 온전히 기능을 갖춘 하이퍼 미디어 유형을 표현 형식으로 사용하면, 적어도 API 문서에서 프로토콜 의미 체계에 대해 말할 필요는 없어진다.

프로파일은 애플리케이션 의미 체계를 설명한다

  • API 문서는 보통 “fn”, “bday”, “east”, “flip” 같은 문자열들을 설명한다.

  • 이 문자열들은 JSON 객체의 키이거나, XML 태그 이름등에 사용하는 변수들이다.

  • 컴퓨터에게 애플리케이션 의미체계를 이해시킬 때, “fn”이 CSS 클래스로 사용될 때 나오는 것이라고 말하는 것이 훨씬 쉽다.

  • 이 문자열들은 프로파일을 단순화 할 수 있게 해준다.

    연결관계

    • 하이퍼미디어 컨트롤에 붙는 문자열로, 클라이언트가 해당 컨트롤을 활성화하면 어떤 상태 전이가 일어날지를 설명한다.
    • 연결 관계를 지원하는 하이퍼미디어 컨트롤은 목적 URL을 위한 공간 하나(href), 연결 관계를 위해 두 번째 공간(rel)을 정의한다.

    안전하지 않은 연결 관계

    • 연결 관계가 GET 요청을 의미하는 것은 아니다.

    의미 체계 서술자

    • 사람의 전체 이름을 표시하는 CSS 클래스
      • hCard 마이크로포맷 : “fn” <span class="fn">junsu bae</span>
      • http://schema.org/Person : “name” <span iotemprop="name">junsu bae</span>
      • 트위터 API 문서 : 특정 { "name" : "junsu bae"}
    • 모두 사람의 이름을 나타내는 동일한 목표를 다른 방식으로 접근한다.
    • 이것들이 의미 체계 서술자(semantic descriptor)이다.
    • 트위터 API 같은 문서에선 관습적인 이름 짓기일 뿐이다.

XMDP: 기계가 이해할 수 있는 첫 번째 프로파일 형식

  • 다른 마이크로포맷을 설명하는 마이크로포맷
  • 컴퓨터는 어떤 CSS 클래스가 hCard 속하는 지 알 수 있다.

ALPS

  • HTML은 웹에서는 독보적으로 사용되는 표현 형식이지만, 웹 API에선 아니다(JSON).
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16

<?xml version="1.0" ?>
<alps>
	<linmk rel="self" href="http://alps.io/microformats/hacrd" />
	<docs>
		Blah Blah...
	</docs>
	
	<descriptor id="vcard" type="semantic">
		<doc>
			Another Blah...
		</doc>
		<descriptor href="#fn"/>
		<descriptor href="#family-name"/>
		...
	</descriptor>
</alps>
  • 사람은 Docs로 자세히 볼 수 있음
  • 기계는 “vcard” 로 태그된 요소 안에서 “fn” 요소를 보게 될 것이라는 걸 알게 된다.
  • type="safe" 인 descriptor는 멱등한 GET 요청임을 알 수도 있다.

ALPS의 장점

  • HTML 뿐 아니라 HAL, XML, JSON, 사이렌 등의 표현에도 사용될 수 있다.

ALPS가 모든 것을 하진 않는다.

  • 의미 체계 서술자가 필요하다거나
  • 특정 위치에 한 번만 나올수 있다는 표현은 할 수 없다.

JSON-LD

  • 콘텍스트(context)라 부르는 기계가 이해할 수 있는 문서를 일반적인 JSON 문서에 결합시킨다.

임베딩된 문서

  • 사이렌 버전으로 작성된 스위치 조작에 관한 폼을 보자
1
2
3
4
5
6
7

"actions" : [
	{ "name": "flip",
		"href": "/switches/4",
		"title": "Flip the mysterious switch.",
		"method": "POST",
	}
]
  • flip과 “Flip the mysterious switch” 는 중복이다.
  • 전자는 클라이언트 프로그래머를 위한 표현이고, 후자는 사람을 위한 표현이다.
  • 이 둘을 연결하는 것은 없고, 영어 문장은 프로파일조차 아니다.
  • 현실적으로, 사용자가 API로 뭘 할지 모르니 포함시켜야 한다.

요약

  • 의미체계의 문제를 어떻게 처리할 것인가? ⇒ 잘 선택한 미디어 유형 + 프로파일
  • 연결 관계 : 클라이언트가 하이퍼미디어 컨트롤을 동작시키면 발생할 상태 전이를 설명하는 문자열
  • 의미 체계 서술자 : 표현의 어떤 부분이 무슨 뜻인지를 알려주는 짧은 문자열
  • 연결 관계와 의미 체계 서술자는 그 자체로는 의미가 없다.
    • 하지만 반드시 근처에 있는 문서가 사람이 이해할 수 있는 설명을 담고 있다 ⇒ 프로파일
  • 기계가 이해할 수 있는 프로파일 : 클라이언트가 자동으로 연결 관계나 의미 체게 서술자의 사람이 이해할 수 있는 정의를 찾아볼 수 있게 해준다.
  • JSON-LD는 기존 클라이언트들을 망가뜨리지 않고 JSON API에 간단한 하이퍼미디어 컨트롤을 추가할 수 있다.
  • 프로파일은 하이퍼미디어 표현에 포함된 사람이 이해할 수 있는 텍스트를 대체할 수 없다. 둘은 용도가 다르다.
    • 프로파일 : 개발자들이 스마트한 클라이언트를 작성하도록 해준다.
    • 표현에 포함된 텍스트 : 클라이언트를 통해 애플리케이션을 사용할 수 있게 해준다.