Springnote

Welcome to Springnote's REST API page.

Preparation

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

• HTTP(S) Protocol
• REST Style
• OAuth Authentication

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:

1. 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.
2. HTTP and HTTPS are supported protocols which one is required to be selected and used.
3. All API calls must be sent to the domain api.springnote.com.
4. Each resource has its own URL.
5. The extension is determined by the content type.
6. 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.

1. POST /pages.xml
2. Host: api.springnote.com
3. Header: application/xml
4.  
5. <page><title>NewPage</title>...</page>

Resource

Resources provided in Springnote's API are as follows:

• Page resources

  • Attachment resources
  • Revision resources
  • Lock resources
  • Collaboration resources
  • Comment 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.

• Response Status code
• Error message

References

• Library

• Communities