스프링노트 REST API

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

 

 

 

준비 운동^#

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

 

• HTTP(S) 프로토콜
• REST 스타일
• OAuth 인증

 

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

 

요청^#

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 형식으로 얻기 위해서는 아래와 같이 요청합니다.

 

 

1. 사용가능한 HTTP 메서드는 리소스에 따라 다릅니다. 예를 들어 Page 리소스(/pages/#{id})는 GET/POST/PUT/DELETE를 모두 지원합니다. 하지만 페이지 목록(/pages)은 GET과 POST를 지원하며, PUT/DELETE를 지원하지 않습니다.
2. 지원하는 프로토콜은 HTTP와 HTTPS이니, 선택해서 사용할 수 있습니다.
3. API 호출의 경우 모두 api.springnote.com 도메인을 사용합니다.
4. 리소스마다 고유 URL이 보여됩니다
5. 확장자로 컨텐츠 타입을 지정합니다.
6. 접근할 노트의 도메인은 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
  4.  
  5. <page><title>NewPage</title>...</page>

 

리소스^#

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

 

• Page 리소스

  • Attachment 리소스
  • Revision 리소스
  • Lock 리소스
  • Collaboration 리소스
  • Comment 리소스

 

응답^#

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

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

 

참고 사이트^#

• FAQ
• 변경 이력

• 언어별 라이브러리 및 샘플
• 스프링노트 문의/제안 게시판

• 매시업 예제

  • 험브롤님의 가제트
  • deepblue님의 Slugger (오픈소스 프로젝트)