Openmaru 개발자 노트

Lock 리소스

Sat, 29 Nov 2008 16:33:25 +0900

페이지 잠금

# 이 리소스들은 모두 읽기전용입니다.j

creator: 현재 페이지를 수정중인 사용자 OpenID
date_expired: 잠금이 해제되는 (예상) 시간(UTC) 예) 2008-01-30T10:11:16Z
relation_is_part_of: 잠금 리소스가 속한 페이지의 ID

XML

<lock xmlns="http://api.springnote.com">
<creator>http://aaron.myid.net/</creator>
<relation_is_part_of type="integer">4</relation_is_part_of>
<date_expired type="datetime">2008-10-28T13:08:30Z</date_expired>
</lock>

요청

특정 페이지의 Lock 상태 조회

GET /pages/#{page_id}/lock.xml

Lock 얻기

POST /pages/#{page_id}/lock.xml

Collaboration 리소스

Sat, 29 Nov 2008 16:26:53 +0900

협업

<collaborations><collaboration> 엘리먼트

이 리소스들은 모두 읽기전용입니다. (GET method only)

rights_holder: 협업자의 OpenID
access_rights: 협업자가 가진 권한 예) reader, writer, guest, creator
pydate_created: 협업을 시작한 시간(UTC) 예) 2008-01-30T10:11:16Z

XML

<collaboration>
 <relation_is_part_of type="integer">4</relation_is_part_of>
 <date_created type="datetime">2008-10-28T12:58:44Z</date_created>
 <access_rights type="symbol">writer</access_rights>
 <rights_holder>http://deepblue.myid.net/</rights_holder>
</collaboration>

JSON

{"collaboration": {
    "date_created": "2008/10/28 12:58:13 +0000",
    "access_rights": "reader",
    "rights_holder": "everybody",
    "relation_is_part_of": 4
}}

요청

특정 페이지의 Collaboration 목록 읽기

GET /pages/#{page_id}/collaboration.xml

pages resource

Fri, 07 Nov 2008 14:42:39 +0900

Page resource (pages)

Read only resource

identifier: Page ID ex) 1
date_created: Date of initial creation(UTC) ex) 2008-01-30T10:11:16Z
date_modified: Date of last modification(UTC) ex) 2008-01-30T10:11:16Z
rights: Creative Commons License of the page ex) by-nc
creator: OpenID of page owner
contributor_modified: OpenID of last modifier

Writable resource

title: Name of the page ex) TestPage
source: Original page.
- Note: Page is in XML Schema format, which means only strings should be entered. Therefore tags must be entity escaped.
 ex) It should be hello instead of hello .
relation_is_part_of: ID of the parent page ex)2

XML

<page>
<identifier type="integer">4</identifier>
<title>TestPage</title>
<source>None</source>
<relation_is_part_of type="integer">1</relation_is_part_of>
<date_created type="datetime">2007-10-26T05:30:08Z</date_created>
<date_modified type="datetime">2008-01-08T10:55:36Z</date_modified>
<creator>http://deepblue.myid.net/</creator>
<contributor_modified>http://deepblue.myid.net/</contributor_modified>
<tags>test</tags>
</page>

JSON

{"page": {
    "rights": null,
    "source": "\u003Cp\u003ENone\u003C/p\u003E\n",
    "creator": "http://deepblue.myid.net/",
    "date_created": "2007/10/26 05:30:08 +0000",
    "contributor_modified": "http://deepblue.myid.net/",
    "date_modified": "2008/01/08 10:55:36 +0000",
    "relation_is_part_of": 1,
    "identifier": 4,
    "tags": "test",
    "title": "TestPage"
}}

Request

Read a speciifc page

GET /pages/#{id}.xml

Edit a specific page

PUT /pages/#{id}.xml

Page resource must be included to request

Delete a specific page

DELETE /pages/#{id}.xml

Generate a page

POST /pages

Page resource must be included to request

Page list

GET /pages.xml

The following parameters can be selected for use
- sort
  - Defines the field to be sorted using one of the following: identifier | title | relation_is_par_of | date_modified | date_created,
  - ex> https://api.springnote.com/pages.xml?sort=date_modified => Requests sort by modified date
- order
  - Defines the responding page to be sorted order based on desc | asc.
  - ex> https://api.springnote.com/pages.xml?sort=date_modified&order=desc => Requests most recent pages
- offset
  - Defines the responding page list's offset
  - ex> https://api.springnote.com/pages.xml?sort=date_modified&offset=10 => Requests the most recent starting from the 10th item
- count
  - Defines the range of the responding page list.
  - ex> https://api.springnote.com/pages.xml?sort=date_modified&count=10 => Requests only 10 pages from the most recent page list
- parent_id
  - Returns a specific page's sub page(s).
  - ex> https://api.springnote.com/pages.xml?parent_id=1234
- q
  - Executes search
  - ex> https://api.springnote.com/pages.xml?q=test
- tags
  - Returns pages that include specified tags
  - ex>https://api.springnote.com/pages.xml?tags=spring
- identifiers
  - Returns pages with matching IDs that are provided with with CSV
  - ex> https://api.springnote.com/pages.xml?identifiers=1,2

Page 리소스

Fri, 07 Nov 2008 14:42:21 +0900

Page 리소스

읽기전용 리소스

identifier: 페이지 고유 ID 예) 1
date_created: 페이지 최초 생성 일시(UTC)예) 2008-01-30T10:11:16Z
date_modified: 페이지 최종 수정 일시(UTC)예) 2008-01-30T10:11:16Z
rights: 페이지에 설정된 Creative Commons License예) by-nc
creator: 페이지 소유자 Open ID
contributor_modified: 최종 수정자 Open ID

쓰기가능 리소스

title: 페이지 이름 예) TestPage
source: 페이지 원본.
- 주의: 페이지 내용은 XML 스키마 타입으로 string만 들어와야 합니다. 따라서 태그는 들어올 수 없으며, 반드시 엔티티 이스케이프 처리를 해서 보내야 합니다.
 - 예) hello 로 넣으면 안되고, hello 와 같이 넣으세요.
relation_is_part_of: 이 페이지의 부모 페이지의 ID예) 2
tags: 페이지에 붙은 태그: 예) tag1,tag2

XML

<page>
<identifier type="integer">4</identifier>
<title>TestPage</title>
<source>None</source>
<relation_is_part_of type="integer">1</relation_is_part_of>
<date_created type="datetime">2007-10-26T05:30:08Z</date_created>
<date_modified type="datetime">2008-01-08T10:55:36Z</date_modified>
<creator>http://deepblue.myid.net/</creator>
<contributor_modified>http://deepblue.myid.net/</contributor_modified>
<tags>test</tags>
</page>

JSON

{"page": {
    "rights": null,
    "source": "\u003Cp\u003ENone\u003C/p\u003E\n",
    "creator": "http://deepblue.myid.net/",
    "date_created": "2007/10/26 05:30:08 +0000",
    "contributor_modified": "http://deepblue.myid.net/",
    "date_modified": "2008/01/08 10:55:36 +0000",
    "relation_is_part_of": 1,
    "identifier": 4,
    "tags": "test",
    "title": "TestPage"
}}

요청

특정 페이지 읽기

GET /pages/#{id}.xml

특정 페이지 수정

PUT /pages/#{id}.xml

페이지 리소스를 함께 담아 요청한다

특정 페이지 삭제

DELETE /pages/#{id}.xml

페이지 생성

POST /pages

페이지 리소스를 함께 담아 요청한다

페이지 목록

GET /pages.xml

선택적으로 사용할 수 있는 파라메터
- sort
  - 정렬 기준으로 사용할 필드, identifier | title | relation_is_par_of | date_modified | date_created 중 하나를 선택,
  - ex> https://api.springnote.com/pages.xml?sort=date_modified => 수정된 날짜 기준으로 정렬 요청
- order
  - 응답 페이지 정렬 순서, desc | asc 중 하나.
  - ex> https://api.springnote.com/pages.xml?sort=date_modified&order=desc => 최신 페이지 요청
- offset
  - 응답 페이지 리스트의 offset정의
  - ex> https://api.springnote.com/pages.xml?sort=date_modified&offset=10 => 최신 페이지 중 10번째 페이지부터 요청
- count
  - 응답페이지 리스트의 크기 정의
  - ex> https://api.springnote.com/pages.xml?sort=date_modified&count=10 => 최신 페이지 10개만 요청
- parent_id
  - 특정 페이지의 하위 페이지만을 반환한다
  - ex> https://api.springnote.com/pages.xml?parent_id=1234
- q
  - 검색을 수행합니다
  - ex> https://api.springnote.com/pages.xml?q=test
- tags
  - 특정 태그를 포함하는 페이지를 반환한다
  - ex>https://api.springnote.com/pages.xml?tags=spring
- identifiers
  - CSV로 제공하면, ID가 매칭되는 페이지만 반환한다
  - ex> https://api.springnote.com/pages.xml?identifiers=1,2

서비스 API 문서

Fri, 07 Nov 2008 11:20:27 +0900

서비스 API 문서

귓속말

Thu, 06 Nov 2008 16:31:40 +0900

귓속말
1. Resrouce
  1. account
  2. message
2. URLs
  1. account 요청 URL
  2. messages 요청 URL

귓속말^#

Resource^#

account^#

openid : 사용자의 오픈아이디 / (읽기가능)

<accounts type="array">
<account>
<openid>http://ias.myid.net/</openid>
</account>
</accounts>

message^#

id : 메시지 ID / (읽기가능)
hasRead : 읽었는지 여부 / (읽기가능,쓰기가능)
starCheck : star 체크 여부 / (읽기가능,쓰기가능)
from : 메시지 송신자 / (읽기가능,쓰기가능)
content : 메시지 내용 / (읽기가능,쓰기가능)
sent-date : 전송 일자 / (읽기가능)

예> XML 포맷일 경우

<messages>
<message id="120387129847392847" hasRead="yes/no" starCheck="yes/no">
<from>http://ias.myid.net/</from>
<content><![CDATA[ .... ]]></content>
 <sent-date>yyyy-MM-dd HH:mm:ss</sent-date>
</message>
<message id="12033213218930213" hasRead="yes/no" starCheck="yes/no">
 <from>http://ias.myid.net/</from>
 <content><![CDATA[ .... ]]></content>
 <sent-date>yyyy-MM-dd HH:mm:ss</sent-date>
</message>
</messages>

URLs^#

account 요청 URL^#

http://whisper.playmaru.net/account (GET): 계정 유무 조회
- parameters
 - openid : 사용자의 오픈 아이디 (REQUIRED)
 - 예> http://ias.myid.net/
 - 만약 여러개의 openid에게 동시에 메시지를 보내려면 comma separate 로 입력한다.
 - 예> account?openid=http://ias.myid.net/,http://rath.myid.net/
1. response
 - <accounts type="array">
 <account>
 <openid>http://ias.myid.net/</openid>
 </account>
 </accounts>

회원가입 API

"계정 유무 조회 API"를 이용하여 해당 서비스의 회원이 아닐 경우 아래 API를 이용해 가입후 지정된 URL로 돌아올 수 있습니다.

URI(GET) : http://whisper.playmaru.net
Parameter
- openid_identifier : 사용자의 openid
- next_to : 회원 가입 후 돌아올 URL
예 : http://whisper.playmaru.net?openid_identifier=http://humbroll.myid.net/&next_to=http://mashupsdev.openmaru.com

messages 요청 URL^#

http://whisper.playmaru.net/messages/ (GET): 메시지 전체(보낸,받은,혼잣말) 조회
- parameters
  - has_read : 읽었는지 여부(OPTIONAL) 예> yes, no
  - star_check : star에 체크 여부(OPTIONAL) 예> yes, no
  - since_date : 특정 날짜 이후 메시지 조회를 위한 날짜(OPTIONAL) 예> 2008-4-24 (yyyy-MM-dd)
  - type : 받은메시지(inbox), 보낸메시지(outbox), 혼잣말(selfbox) 예> inbox, outbox, selfbox
    - type 파라미터 대신 URI 부분에 메시지함을 바로 적을 수도 있다.
    - 예> http://whisper.playmaru.net/messages/inbox , http://whisper.playmaru.net/messages/outbox , http://whisper.playmaru.net/messages/selfbox
  - format : 응답 메시지의 형태 (OPTIONAL) 예> xml, json
http://whisper.playmaru.net/messages (POST): 메시지 전송
- parameters
  - openid_to : 수신자 (REQUIRED) 예> http://ias.myid.net/
  - content : 내용 (REQUIRED)
http://whisper.playmaru.net/messages/inbox|outbox|selfbox/m_id (GET): 특정 메시지 조회(m_id : 메시지의 id)
http://whisper.playmaru.net/messages/inbox|outbox|selfbox/m_id (PUT): 특정 메시지 수정(m_id : 메시지의 id)
- parameters
  - has_read : 읽었는지 여부(OPTIONAL) 예> yes, no
  - star_check : star 체크 (OPTIONAL) 예> yes, no
http://whisper.playmaru.net/messages/inbox|outbox|selfbox/m_id (DELETE): 특정 메시지 삭제(m_id : 메시지의 id)
http://whisper.playmaru.net/messages/inbox (GET): 받은 메시지 조회
- parameters
  - has_read : 읽었는지 여부(OPTIONAL) 예> yes, no
  - star_check : star에 체크 여부(OPTIONAL) 예> yes, no
  - since_date : 특정 날짜 이후 메시지 조회를 위한 날짜(OPTIONAL) 예> 2008-04-24
http://whisper.playmaru.net/messages/outbox (GET): 보낸 메시지 조회
- parameters
  - star_check : star에 체크 여부(OPTIONAL) 예> yes, no
  - since_date : 특정 날짜 이후 메시지 조회를 위한 날짜(OPTIONAL) 예> 2008-04-24
http://whisper.playmaru.net/messages/selfbox (GET): 혼잣말 조회
- parameters
  - star_check : star에 체크 여부(OPTIONAL) 예> yes, no
  - since_date : 특정 날짜 이후 메시지 조회를 위한 날짜(OPTIONAL) 예> 2008-04-24
http://whisper.playmaru.net/messages-with?openid=http://foo.bar.com/
- parameters
  - openid : 메시지를 주고 받았던 내역을 조회할 상대방의 오픈아이디.
  - format : 응답 메시지의 형태 (OPTIONAL) 예> xml, json

OAuth프로토콜 관점에서 본 OAuth 인증과정

Fri, 31 Oct 2008 13:38:35 +0900

OAuth프로토콜 관점에서 본 OAuth 인증과정

본 문서는 OAuth프로토콜 관점에서 본 OAuth 인증과정을 설명하며, OAuth 스팩의 Appendix A - Protocol Example의 내용을 기반으로 작성되었습니다.

각 과정은 아래에 나온 순서도에 기반하여 이루어지기 때문에 그림과 함께 보면 이해하는데 도움이 될 것입니다.

* 이 사진에 나오는 A,B,C.. 단계는 아래의 단계와 관련이 없습니다.

A. 프로토콜 예제

본 예제에서 서비스 프로바이더인 photos.example.net 는 사진 공유 사이트이며, 컨수머인 printer.example.com은 사진 출력 사이트입니다. Jane은 사용자이며 photos.example.com에 저장되어 있는 비공개 사진인 vacation.jpg를 출력하기 위하여 printer.example.com 서비스를 사용할 것입니다.

Jane이 그녀의 아이디와 비밀번호를 입력하여 photos.example.net 에 로그인하면, 그녀는 http://photos.example.net/photo?file=vacation.jpg URL을 통해 그녀의 사진에 접근할 것입니다. 다른 사용자들은 그 사진에 접근할 수 없으며, Jane은 그녀의 아이디와 비밀번호를 printer.example.com에 공유하고 싶지 않습니다.

이 예제에서 파라미터를 전송할 때 사용하는 요청은 URL 쿼리 메소드를 사용합니다. 이는 단순한 예제를 위해 사용되며 한개의 메소드가 다른 용도로 사용되어서는 안됩니다.

A.1. 문서화와 등록

서비스 프로바이더의 문서에서는 컨수머 키와 컨수머 시크릿을 등록하는 방법을 설명하며, 다음과 같은 URL들을 선언해 주어야 합니다.

Request Token URL:

https://photos.example.net/request_token, HTTP POST 사용

User Authorization URL:

http://photos.example.net/authorize, HTTP GET 사용

Access Token URL:

https://photos.example.net/access_token, HTTP POST 사용

Photo (Protected Resource) URL:

http://photos.example.net/photo , file파라미터와 size파라미터(선택적)와 함께 전송

서비스 프로바이더는 모든 요청에 대하여 HMAC-SHA1 시그네쳐를 지원하며, 보안(HTTPS)요청일 경우에만 PLAINTEXT을 사용할 수 있음을 말해줍니다.

컨수머인 printer.example.com은 이미 컨수머 키와 컨수머 시크릿을 photos.example.net으로 부터 부여 받았으며, 출력할 사진은 photos.example.net에 저장되어 있음을 명시합니다. 컨수머 등록을 하면 다음과 같은 값들을 부여받습니다:

Consumer Key:

dpf43f3p2l4k3l03

Consumer Secret:

kd94hf93k423kf44

A.2. 리퀘스트 토큰 얻기

Jane이 printer.example.com에게 photos.example.net에 저장되어 있는 그녀의 휴가사진을 출력할 것임을 알려주면, 출력 웹사이트는 사진에 접근을 시도할 것이며, 그 사진은 비공개이기 때문에 HTTP 401 Unauthorized 메시지를 받습니다. 서비스 프로바이더는 응답과 함께 다음과 같은 헤더를 포함합니다:

WWW-Authenticate: OAuth realm="http://photos.example.net/"

컨수머는 서비스 프로바이더에게 다음과 같은 HTTP POST를 보내야 합니다.

https://photos.example.net/request_token?oauth_consumer_key=dpf43f3p2l4k3l03&oauth_signature_method=PLAINTEXT&oauth_signature=kd94hf93k423kf44%26&oauth_timestamp=1191242090&oauth_nonce=hsu94j3884jdopsl&oauth_version=1.0

서비스 프로바이더는 signature를 검사하고, HTTP 응답의 body에 인증되지 않은 리퀘스트 토큰과 함께 응답합니다.

oauth_token=hh5s93j4hdidpola&oauth_token_secret=hdhd0244k9j7ao03

A.3. 사용자 인증 요청하기

컨수머는 Jane의 비공개 사진으로 접근을 승인을 얻기 위하여 브라우저를 서비스 프로바이더의 Authoirization URL로 리다이렉트 시킵니다.

http://photos.example.net/authorize?oauth_token=hh5s93j4hdidpola&oauth_callback=http%3A%2F%2Fprinter.example.com%2Frequest_token_ready

서비스 프로바이더는 Jane이 그녀의 아이디와 비밀번호를 사용해 로그인 할 것을 요청하고, 성공적으로 로그인을 했으면, printer.example.com이 그녀의 비공개 사진에 접근할 권한을 줄 것인지 묻습니다. Jane이 요청을 승인하면, 서비스 프로바이더는 컨수머의 callback URL로 리다이렉트 시킵니다:

http://printer.example.com/request_token_ready?oauth_token=hh5s93j4hdidpola

A.4. 액세스 토큰 얻기

이제 컨수머는 Jane이 승인한 리퀘스트 토큰을 알고 있으며, 서비스 프로바이더에게 그것을 액세스 토큰으로 교환해 줄 것을 요청합니다:

https://photos.example.net/access_token?oauth_consumer_key=dpf43f3p2l4k3l03&oauth_token=hh5s93j4hdidpola&oauth_signature_method=PLAINTEXT&oauth_signature=kd94hf93k423kf44%26hdhd0244k9j7ao03&oauth_timestamp=1191242092&oauth_nonce=dji430splmx33448&oauth_version=1.0

서비스 프로바이더는 시그네쳐를 검사하고 HTTP 응답의 바디에 액세스 토큰을 넘겨줍니다:

oauth_token=nnch734d00sl2jdk&oauth_token_secret=pfkkdhi9sl3r4s00

A.5. 보호된 자원에 접근하기

컨수머는 이제 비공개 사진을 요청할 준비가 되었습니다. 사진 URL이 HTTPS가 아니라면, 반드시 HMAC-SHA1을 사용해야 합니다.

A.5.1. Signature Base String 생성하기

signature를 생성하기 위해, Signature Base String을 생성해야 합니다. 요청은 다음과 같은 파라미터들(oauth_signature를 제외한)을 순서대로 노멀라이즈된 문자열로 연결한 것을 포함해야 합니다.

oauth_consumer_key:

dpf43f3p2l4k3l03

oauth_token:

nnch734d00sl2jdk

oauth_signature_method:

HMAC-SHA1

oauth_timestamp:

1191242096

oauth_nonce:

kllo9940pd9333jh

oauth_version:

1.0

file:

vacation.jpg

size:

original

다음과 같은 것들이 Signatrue Base String을 생성하기 위해 사용됩니다.

GET
http://photos.example.net/photos
file=vacation.jpg&oauth_consumer_key=dpf43f3p2l4k3l03&oauth_nonce=kllo9940pd9333jh&oauth_signature_method=HMAC-SHA1&oauth_timestamp=1191242096&oauth_token=nnch734d00sl2jdk&oauth_version=1.0&size=original

Signature Base String 은 다음과 같습니다:

GET&http%3A%2F%2Fphotos.example.net%2Fphotos&file%3Dvacation.jpg%26oauth_consumer_key%3Ddpf43f3p2l4k3l03%26oauth_nonce%3Dkllo9940pd9333jh%26oauth_signature_method%3DHMAC-SHA1%26oauth_timestamp%3D1191242096%26oauth_token%3Dnnch734d00sl2jdk%26oauth_version%3D1.0%26size%3Doriginal

A.5.2. Signature 값 암호화 하기

HMAC-SHA1은 Signature Base String을 text로, kd94hf93k423kf44&pfkkdhi9sl3r4s00(컨수머 키&액세스토큰시크릿)를 key로 사용하여 base64-encoding된 문자열로 변환된 값을 만들어 냅니다:

tR3+Ty81lMeYAr/Fid0kMTYa/WM=

A.5.3. 보호된 자원 요청하기

사진을 요청하기 위한 컨수머의 요청내용을 정리해 보면 :

http://photos.example.net/photos?file=vacation.jpg&size=original
                Authorization: OAuth realm="http://photos.example.net/",
                oauth_consumer_key="dpf43f3p2l4k3l03",
                oauth_token="nnch734d00sl2jdk",
                oauth_signature_method="HMAC-SHA1",
                oauth_signature="tR3%2BTy81lMeYAr%2FFid0kMTYa%2FWM%3D",
                oauth_timestamp="1191242096",
                oauth_nonce="kllo9940pd9333jh",
                oauth_version="1.0"

쿼리 파라미터를 사용한다면:

http://photos.example.net/photos?file=vacation.jpg&size=original&oauth_consumer_key=dpf43f3p2l4k3l03&oauth_token=nnch734d00sl2jdk&oauth_signature_method=HMAC-SHA1&oauth_signature=tR3%2BTy81lMeYAr%2FFid0kMTYa%2FWM%3D&oauth_timestamp=1191242096&oauth_nonce=kllo9940pd9333jh&oauth_version=1.0

photos.example.net은 signature를 검사하고 나서 요청한 사진을 응답으로 돌려줄 것입니다.

여기까지 OAuth프로토콜 관점에서 본 OAuth인증 과정을 살펴보았습니다. 이제 OAuth의 이해를 바탕으로 실제 컨수머 개발을 위해 튜토리얼을 참고하시기 바랍니다.

사용자 관점에서 본 OAuth 인증과정

Fri, 31 Oct 2008 13:26:48 +0900

사용자 관점에서 본 OAuth 인증과정

본 문서는 사용자 관점에서 본 OAuth 인증과정을 설명하며, OAuth 공식 홈페이지의 Getting Started Part-2 의 내용을 기반으로 작성되었습니다.

OAuth는 실제 예제로 잘 설명될 수 있습니다. OAuth 스펙에 있는 Appendix A와 유사한 예제이지만, 스펙에서는 HTTP 호출 문법에 초점을 맞춘 반면, 여기에서는 사용자, 컨수머, 그리고 서비스 프로바이더 의 관점에서 OAuth세션을 중심으로 설명합니다.

2주동안 스코트랜드의 여행을 마치고 돌아온 Jane은, 여행을 하며 찍은 사진들을 친구들과 공유하고 싶습니다. Jane은 여행 사진을 공유하기 위해 사진 공유사이트인 Faji를 사용 합니다. 그녀는 faji.com에 로그인하고 비공개로 설정한 두 장의 사진을 업로드 합니다.

OAuth에서 쓰이는 용어에 따르면 Jane은 사용자이고 Faji는 서비스 프로바이더입니다. Jane이 업로드한 2장의 사진은 보호된 데이터(Protected Resource)가 되겠죠.

그녀의 몇몇 친구들과 사진을 공유한 다음, Jane은 그녀의 할머니와도 사진을 공유하려 합니다. 희귀한 스코트랜드의 병 사진을 다른 사람들과 공유하고 싶지는 않지만, 할머니는 인터넷에 접속할 수 없기때문에 Jane은 그 사진을 인쇄해서 할머니에게 보내려 합니다. 이를 위해 Jane은 Beppa라는 온라인 인쇄 서비스를 사용하려 합니다.

OAuth에서 쓰이는 용어에 따르면 Beppa는 컨수머입니다. Jane이 사진을 비공개로 해 놓은 이상, Beppa가 그 사진을 인쇄하기 위해 사진을 얻기 위해서는 OAuth인증을 해야 합니다.

beppa.com에 방문한 Jane은 인쇄 명령을 내립니다. Beppa는 Faji를 포함한 많은 외부의 사진공유 사이트들에 잇는 사진들을 가져올 수 있는 기능을 지원합니다. Jane은 사진이 있는 곳의 서비스를 선택하고 continue버튼을 누릅니다.

Beppa가 Faji 사진을 가져올 수 있도록 지원하고자 한다면, Beppa 개발자는 Faji의 OAuth인증을 사용하는 API를 사용하기 위하여 Faji로부터 컨수머 키(Consumer Key)와 컨수머 시크릿(Consumer Secret)을 사전에 받아와야 합니다.

Jane이 continue버튼을 누른 후, 뒷단에서는 Beppa와 Faji 사이에 중요한 일들이 일어납니다. Beppa는 Faji에게 리퀘스트 토큰(Request Token)을 요청합니다. 리퀘스트 토큰(Request Token)은 사용자와는 전혀 상관이 없으며, Beppa가 Faji에 있는 Jane의 비공개 사진에 접근하는 것을 승인하기 위하여 사용될 뿐입니다.

Jane은 continue버튼을 누르고 화면이 바뀌길 기다립니다.

Beppa가 리퀘스트 토큰(Request Token)을 받으면, Faji의 OAuth 사용자 인증 URL로 방금 받은 리퀘스트 토큰(Request Token)과 함께 리다이렉트 시키고, Jane이 승인을 하면 http://beppa.com/order로 되돌아오게 할 것을 요청합니다.

Jane은 Faji로 리다이렉트되고 사이트에 로그인할 것을 요청받습니다. OAuth는 서비스 프로바이더가 먼저 사용자를 인증하고, 컨수머에게 접근권한을 줄 것인지 승인을 받습니다.

Jane은 브라우저에 있는 URL을 통해 그녀는 지금 Faji사이트에 있다는 것을 알게 되며, 아이디와 비밀번호를 입력합니다.

OAuth는 Jane이 그녀의 아이디와 비밀번호를 Beppa나 다른 사이트들이 공유하지 않게끔 해줍니다. Jane이 그녀의 faji에 대한 비밀정보(아이디,비밀번호)를 beppa.com에 입력하는 과정이 없기 때문이죠.

Faji에서 로그인에 성공하면, Jane은 Beppa에게 Faji에 접근할 수 있는 권한을 부여하기 위한 승인을 하게 됩니다. Faji는 Jane에게 누가 접근요청을 하는지(여기서는 Beppa가 되겠죠) 알려주며 승인을 할 것인지 묻습니다. Jane은 승낙하거나 거절할 수 있습니다.

Jane은 Beppa가 필요한 만큼만 제한적으로 접근할 수 있게 해줍니다. 그녀는 Beppa가 그녀의 사진을 수정하거나 다른 일들을 하는 것을 원하지 않습니다. 또한, Beppa가 Faji에 있는 그녀의 사진을 가져오는데는 1시간이면 충분하다는 것을 알고 있습니다.

Jane이 요청을 승낙하면 Faji는 리퀘스트 토큰(Request Token)을 Jane으로부터 "사용자 승인이 된" 토큰으로 표시합니다. Jane의 브라우저는 리퀘스트 토큰(Request Token)과 함께 보내온 http://beppa.com/order 주소로 리다이렉트 시킵니다. 이는 Beppa가 Jane의 사진을 가져오는 작업을 계속 할 수 있다는 것을 알려주는 것입니다.

Jane은 Beppa가 Faji 계정으로부터 사진을 가져오는 것을 기다립니다.

Jane이 기다리는 동안, Beppa는 인증된 리퀘스트 토큰(Request Toekn)과 액세스 토큰(Access Token)을 교환홥니다. 리퀘스트 토큰(Request Token)은 사용자의 승인을 얻어내기 위해 사용될 뿐이며, 액세스 토큰(Access Token)은 보호된 자원(Protected Resource : 여기에서는 Jane의 사진이 되겠죠)에 접근하기 위해 사용됩니다. 첫 번째 요청에서, Beppa는 리퀘스트 토큰(Request Token)을 액세스 토큰(Access Token)으로 바꾸고, 두 번째로 사진을 요청(여러번 요청이 될 수 있겠죠. 한번은 사진의 리스트를, 다른한번은 각 사진을 가지고 오는 등...)합니다.

Beppa가 작업을 마치면 Jane의 브라우저는 작업을 다 마쳤음을 보여주는 화면으로 바뀝니다.

Beppa는 성공적으로 Jane의 사진을 가져왔습니다. 그녀의 사진을 선택할 수 있도록 썸네일로 보여줍니다.

Jane은 Beppa가 그녀의 아이디와 비밀번호를 모르는데도 불구하고 그녀의 사진을 가져왓다는 것에 놀랍니다. 그녀는 화면에서 시키는데로 인쇄요청을 합니다.

여기까지 사용자 관점에서 본 OAuth 인증과정을 살펴보았습니다. 이제 이러한 인증과정에 맞춘 컨수머 개발을 하기 위해서 OAuth프로토콜 관점에서본 OAuth인증 과정을 살표보시기 바랍니다.(보러가기)

Library

Wed, 29 Oct 2008 18:50:50 +0900

You can use Springnote API more easily using libraries. Some of these libararies were made by outside developers. We give special thanks to those developers. Libraries for OAuth can be found here.

Java

Springnote Java API

Ruby

PHP

Others

스프링노트 REST API

Wed, 29 Oct 2008 18:49:43 +0900

스프링노트 REST API 페이지에 오신 것을 환영합니다.

API를 사용하시다 또는 문서를 읽다가 궁금증이 생기면 언제든 문의/제안을 찾아주시기 바랍니다. 최대한 신속하게 답변 드리겠습니다.

준비 운동
요청
리소스
응답
참고 사이트

준비 운동^#

스프링노트 API를 사용하기 위해서는 아래 내용에 대한 약간의 이해가 필요합니다.

모두 업계에서 사실상 표준으로 인정받는 기술들로, 스프링노트에서도 이를 따르고 있습니다.

요청^#

API 요청은 아래 내용을 담고 있어야 합니다.

인증 정보
리소스 URL
컨텐츠 타입
HTTP 메서드와 파라메터

인증 ^#

OAuth와 HTTP 기본 인증 방식을 함께 제공합니다만, OAuth를 사용하실 것을 추천합니다. 보다 자세한 내용은 OAuth 페이지를 참고하세요.

간단히 요약하자면, 특정 사용자의 노트에 접근하기 위해서는 그 사용자의 Acess Token이 필요합니다. 오픈마루 API 센터에서 애플리케이션키를 발급받고, 아래 URL을 통해 필요한 토큰을 얻을 수 있습니다. 이 때 보안을 위해 사용자의 동의를 얻는 과정이 필요합니다.

Request Token URL: https://api.openmaru.com/oauth/request_token
Authorize URL: https://api.openmaru.com/oauth/authorize
Access Token URL: https://api.openmaru.com/oauth/access_token/springnote

리소스 URL^#

스프링노트에서 제공하는 모든 리소스(Page, Attachment 등)는 고유 URL이 부여됩니다. 예를 들어 지금 보고 있는 이 페이지에 대한 정보를 XML 형식으로 얻기 위해서는 아래와 같이 요청합니다.

사용가능한 HTTP 메서드는 리소스에 따라 다릅니다. 예를 들어 Page 리소스(/pages/#{id})는 GET/POST/PUT/DELETE를 모두 지원합니다. 하지만 페이지 목록(/pages)은 GET과 POST를 지원하며, PUT/DELETE를 지원하지 않습니다.
지원하는 프로토콜은 HTTP와 HTTPS이니, 선택해서 사용할 수 있습니다.
API 호출의 경우 모두 api.springnote.com 도메인을 사용합니다.
리소스마다 고유 URL이 보여됩니다
확장자로 컨텐츠 타입을 지정합니다.
접근할 노트의 도메인은 domain 파라메터를 이용해 명시할 수 있습니다. 만일 domain을 생략하면 사용자의 첫번째 개인노트를 의미합니다.

컨텐츠 타입^#

스프링노트의 모든 리소스는 XML과 JSON 타입으로 제공됩니다.

그리고 원하는 컨텐츠 타입을 아래와 같은 방법으로 지정할 수 있습니다. (반드시 필요하며, 그렇지 않으면 API 호출로 인정되지 않습니다)

적당한 확장자를 붙입니다. 즉, 리소스 URL 뒤에 .xml 또는 .json을 붙입니다. (추천)
요청의 Content-Type Header를 application/xml 또는 application/json으로 명시합니다.

요청과 응답의 형식은 항상 일치합니다. 즉, XML로 요청하면 응답은 XML 형식으로 주어집니다.

리소스 파라메터^#

POST나 PUT 메서드로 리소스를 스프링노트로 전송하는 경우 아래와 같이 3가지 방법으로 전달할 수 있습니다.예를 들어 새로운 페이지를 만들려면, 새로 만들 페이지 리소스에 대한 정보를 API에 담아 요청합니다.

리소스를 HTTP 요청 파라미터에 속성별로 풀어씁니다. 파라미터 값은 물론 URL 인코딩해야 합니다. 이 때 파라미터명은 리소스명[속성명]으로 적어줍니다(추천).
- 예) POST http://api.springnote.com/pages.xml?page[title]=NewPage&page[source]=test&page[relation_is_part_of]=1
HTTP 요청 파라메터에 XML이나 JSON 형식으로 포함합니다. 이 때 파라메터명은 xml 또는 json입니다.
- 예) POST http://api.springnote.com/pages.xml?xml=<page><title>NewPage</title>...</page>
HTTP 본문(body)에 넣습니다. 이 때 요청 HTTP 호출의 헤더에 Content-Type을 정확히 명시해야 합니다. 예를 들어, XML이라면 Content-Type이 'application/xml'이어야 하고, JSON이라면 'application/json'이어야 합니다.
1. POST /pages.xml
2. Host: api.springnote.com
3. Header: application/xml
5. <page><title>NewPage</title>...</page>

리소스^#

스프링노트 API에서 제공하는 리소스는 다음과 같습니다.

Page 리소스

응답^#

요청이 성공한 경우 200 OK와 함께 상황에 맞는 리소스가 XML 또는 JSON으로 제공됩니다.

만일 에러가 발생하면, 상황에 따른 응답 상태 코드와 에러 메시지가 제공됩니다.

참고 사이트^#

Springnote

Wed, 29 Oct 2008 18:49:36 +0900

Welcome to Springnote's REST API page.

If you have any questions while using or reading our API, please utilize our Suggestions/Bug Reports forum to contact us.

Preparation

In order to use the Springnote API, you need to understand the following items:

These are all de facto standards which are widely used.

Request

API request requires the following:

Authentication information
Resource URL
Content type
HTTP method and paramaters

Authentication

Although OAuth and basic HTTP authentication is provided together, we recommend that you utilize OAuth. For more detailed information, please refer to the OAuth page.

To summarize, in order to access the notebook of a specified user, the user's Access Token is needed. After you have been issued the application from <Openmaru's API Center>, you can obtain tokens from the URLs listed below. This process is protected thus requiring an approval from the user.

Request Token URL: https://api.openmaru.com/oauth/request_token
Authorize URL: https://api.openmaru.com/oauth/authorize
Access Token URL: https://api.openmaru.com/oauth/access_token/springnote

Resource URL

All resources (Page, Attachment, etc.) provided by Springnote have its own URL. For example, in order to obtain information the page you are viewing now in XML, the following is requested:

HTTP methods that can be used differs depending on the resource. For example, GET, POST, PUT, and DELETE are all supported for the page resource (/pages/#{id}). GET and POST are supported for page lists (/pages) while PUT and DELETE are not.
HTTP and HTTPS are supported protocols which one is required to be selected and used.
All API calls must be sent to the domain api.springnote.com.
Each resource has its own URL.
The extension is determined by the content type.
The notebook domain can be defined by using a domain parameter. In a case where the domain is omitted, the first personal notebook of the user is seleceted by default.

Content Type

All Springnote resources are provided in XML and JSON types. You can also use the methods listed below to specify a desired content type. (This is strictly required. API calling is not approved if the methods listed below are not used)

Add an appropriate extension. In other words, add an extension to the end of the URL. Example) .xml or .json. (RECOMMENDED)
The Content-Type Header request is filled by application/xml or application/json.

The request and response type always correspond with each other. In other words, if you request through XML, the response will be given in XML.

Resource Parameters

Listed below are possible ways to send resources using POST and PUT methods to Springnote. For example, to create a new page, you need to include the resource parameter in the API and then make a request.

Resource is separated by attribute in the HTTP request parameter. The parameter value needs to be encoded, therefore the parameter name should be written as the resource (attribute) name. (RECOMMENDED)
- Example) POST http://api.springnote.com/pages.xml?page[title]=NewPage&page[source]=test&page[relation_is_part_of]=1
XML or JSON is directed included into the HTTP request parameter. The parameter name is either xml or json.
- Example) POST http://api.springnote.com/pages.xml?xml=<page><title>NewPage</title>...</page>
Add the resource to the HTTP body. At the header of the HTTP request, Content-Type must be accurately determined. For example, for XML the Content-Type must be application/xml, while JSON must be application/json.

POST /pages.xml
Host: api.springnote.com
Header: application/xml
<page><title>NewPage</title>...</page>

Resource

Resources provided in Springnote's API are as follows:

Page resources

Response

If the request is successful, resources in XML or JSON are provided along with 200 OK. If an error occurs, you will be provided with response status codes and an error message on your situation.

Openmaru 개발자 노트

Lock 리소스

페이지 잠금

XML

요청

특정 페이지의 Lock 상태 조회

Lock 얻기

Collaboration 리소스

협업

XML

JSON

요청

특정 페이지의 Collaboration 목록 읽기

pages resource

Page resource (pages)

Read only resource

Writable resource

XML

JSON

Request

Read a speciifc page

Edit a specific page

Delete a specific page

Generate a page

Page list

Page 리소스

Page 리소스

읽기전용 리소스

쓰기가능 리소스

XML

JSON

요청

특정 페이지 읽기

특정 페이지 수정

특정 페이지 삭제

페이지 생성

페이지 목록

서비스 API 문서

서비스 API 문서

귓속말

귓속말#

Resource#

account#

message#

URLs#

account 요청 URL#

회원가입 API

messages 요청 URL#

OAuth프로토콜 관점에서 본 OAuth 인증과정

OAuth프로토콜 관점에서 본 OAuth 인증과정

A. 프로토콜 예제

A.1. 문서화와 등록

A.2. 리퀘스트 토큰 얻기

A.3. 사용자 인증 요청하기

A.4. 액세스 토큰 얻기

A.5. 보호된 자원에 접근하기

A.5.1. Signature Base String 생성하기

A.5.2. Signature 값 암호화 하기

A.5.3. 보호된 자원 요청하기

사용자 관점에서 본 OAuth 인증과정

사용자 관점에서 본 OAuth 인증과정

Library

Java

Ruby

PHP

Perl

Python

Javascript

Visual Basic

Others

스프링노트 REST API

준비 운동#

요청#

인증 #

리소스 URL#

컨텐츠 타입#

리소스 파라메터#

리소스#

응답#

참고 사이트#

귓속말^#

Resource^#

account^#

message^#

URLs^#

account 요청 URL^#

messages 요청 URL^#

준비 운동^#

요청^#

인증 ^#

리소스 URL^#

컨텐츠 타입^#

리소스 파라메터^#

리소스^#

응답^#

참고 사이트^#