Reblog API

Table of Contents

• Overview
• Using the API
  • Refeed.ServerComm
  • JSON-RPC
• Extending the API
• Method Dictionary
  • feedPublishFormHTML
  • feedSubscriptionFormHTML
  • feedTagsFormHTML
  • itemBodyHTML
  • itemCommentFormHTML
  • itemEditFormHTML
  • itemHeadHTML
  • markFeedPublished
  • markFeedRead
  • markFeedUnpublished
  • markFeedUnread
  • markItemPublished
  • markItemRead
  • markItemsPublished
  • markItemsRead
  • markItemsUnread
  • markItemUnpublished
  • markItemUnread
  • postItem
  • setFeedTags
  • setItemCommentTags
  • setItemLink
  • setItemTags
  • setItemTitleContentLink
  • setKeyboardUse
• License

Overview

Reblog provides a client JSON-RPC API, written to support AJAX-style interactions in the default interface. The API may be extended by plug-ins.

JSON (JavaScript Object Notation) is a lightweight data-interchange format. It is easy for humans to read and write. It is easy for machines to parse and generate. It is based on a subset of the JavaScript Programming Language, Standard ECMA-262 3rd Edition - December 1999. This feature can also be found in Python. JSON is a text format that is completely language independent but uses conventions that are familiar to programmers of the C-family of languages, including C, C++, C#, Java, JavaScript, Perl, TCL, and many others. These properties make JSON an ideal data-interchange language.

More information about JSON and JSON-RPC is available at json.org and json-rpc.org.

Using the API

Refeed.ServerComm

Reblog provides the javascript class Refeed.ServerComm to implement basic JSON-RPC interactions, defined in comm.js. The value Refeed.ServerComm.callHREF must be defined prior to using Refeed.ServerComm.remoteCall() to invoke server-side methods. By default, Refeed.ServerComm.callHREF is set to call.php.

Refeed.ServerComm.remoteCall() accepts four arguments:

1. String: method name
   Name of remote method to call.

2. Array: parameters
   Parameters to remote method. These may be values of any type, including objects, NULL, and arrays.

   For methods that accept RF_Items and RF_Feeds, JSON-RPC class-hinting is used. For example, a feed with id 3 would be passed as:

   {"jsonclass": ["RF_Feed", [{"id": 3}]]}.

   Javascript Refeed.Feed and Refeed.Item objects (see feed.js, item.js) classes provide a toClassHint() method to generate these representations.

3. Function: on-result
   Javascript function object, called with response result value if defined, and no error is present.

4. Function: on-error
   Javascript function object, called with response error value if defined, and no result is present.

Methods calls are asynchronous, so no value is returned by Refeed.ServerComm.remoteCall().

The id value specified in JSON-RPC (see below) is intended to correlate requests and responses, but it is unused by Refeed.ServerComm since Javascript closures and the callback function parameters fulfill the same requirement more effectively.

JSON-RPC

JSON-RPC is a minimal remote procedure protocol defined in the JSON format. A detailed specification is provided at json-rpc.org.

Methods are called via HTTP POST requests to the JSON-RPC endpoint, located at call.php by default. This is an example method call, analogous to foo("bar", "baz"):

POST /call.php HTTP/1.1

{"method":"foo","params":["bar","baz"],"id":0}

An example response:

HTTP/1.1 200 OK
Content-Type: application/x-json-rpc

{"result":"bar-baz","error":null,"id":0}

Another example response, where an error has occurred:

HTTP/1.1 200 OK
Content-Type: application/x-json-rpc

{"result":null,"error":"Something went horribly awry.","id":0}

Extending the API

Please see the plug-ins documentation for details on writing plug-ins and defining remote methods.

Method Dictionary

feedPublishFormHTML

Retrieve feed publish form HTML

Args:

1. RF_Feed

Return: string of HTML representing single feed publish form content

feedSubscriptionFormHTML

Retrieve feed subscription form HTML

Args:

1. RF_Feed

Return: string of HTML representing single feed subscription form content

feedTagsFormHTML

Retrieve feed tags form HTML

Args:

1. RF_Feed

Return: string of HTML representing single feed tags form content

itemBodyHTML

Retrieve item body HTML

Args:

1. RF_Item

Return: string of HTML representing single item body content

itemCommentFormHTML

Retrieve item comment form HTML

Args:

1. RF_Item

Return: string of HTML representing single item comment form content

itemEditFormHTML

Retrieve item edit form HTML

Args:

1. RF_Item

Return: string of HTML representing single item edit form content

itemHeadHTML

Retrieve item head HTML

Args:

1. RF_Item

Return: string of HTML representing single item head content

markFeedPublished

Mark a feed as published

Args:

1. RF_Feed

Return: boolean true on success

markFeedRead

Mark all items in a feed as read

Args:

1. array of RF_Feeds

Return: boolean true on success

markFeedUnpublished

Mark a feed as unpublished

Args:

1. RF_Feed

Return: boolean true on success

markFeedUnread

Mark all items in a feed as unread

Args:

1. array of RF_Feeds

Return: boolean true on success

markItemPublished

Mark an item as published

Args:

1. RF_Item

Return: boolean true on success

markItemRead

Mark an item as read

Args:

1. RF_Item

Return: boolean true on success

markItemsPublished

Mark several items as published

Args:

1. array of RF_Items

Return: boolean true on success

markItemsRead

Mark several items as read

Args:

1. array of RF_Items

Return: boolean true on success

markItemsUnread

Mark several items as unread

Args:

1. array of RF_Items

Return: boolean true on success

markItemUnpublished

Mark an item unas published

Args:

1. RF_Item

Return: boolean true on success

markItemUnread

Mark an item as unread

Args:

1. RF_Item

Return: boolean true on success

postItem

Post a new item

Args:

1. associative array of item arguments:
   • title: Title of new item, required
   • link: Link for new item, required.
   • content: Content of new item, required.
   • tags: Space-delimited list of item tags, optional.
   • feed_id: numeric feed ID; leave this blank in almost all cases.
   • modified: modification timestamp; leave blank for "now".
   • guid: globally unique identifier; leave this blank in almost all cases.
2. optional array of metadata:
   Each element should be an associative array of the form:
   {"label": ..., "value": ..., "format": ...}

Return: RF_Item

setFeedTags

Set an feed's tags

Args:

1. RF_Feed
2. array of strings: tags
3. boolean: apply tags to all existing items in feed? optional, default false

Return: boolean true on success

setItemCommentTags

Set an item's comment and tags

Args:

1. RF_Item
2. string: comment
3. array of strings: tags

Return: boolean true on success

setItemLink

Set an item's link

Args:

1. RF_Item
2. string: link

Return: boolean true on success

setItemTags

Set an item's tags

Args:

1. RF_Item
2. array of strings: tags

Return: boolean true on success

setItemTitleContentLink

Set an item's title, link and content

Args:

1. RF_Item
2. string: title
3. string: content
4. string: link

Return: boolean true on success

setKeyboardUse

Toggle keyboard usage flag

Args:

1. boolean: turn keyboard usage on or off

Return: boolean true on success

License

Reblog is distributed under the GPL (see the LICENSE file in this directory), though some of its included libraries (in./library/) are not.