$Revision: 1.3 $
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.
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:
String: method name
Name of remote method to call.
Array: parameters
Parameters to remote method. These may be values of any type,
including objects, NULL
, and arrays.
For methods that accept RF_Item
s and
RF_Feed
s, 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.
Function: on-result
Javascript function object, called with response
result
value if defined, and no
error
is present.
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 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}
Please see the plug-ins documentation for details on writing plug-ins and defining remote methods.
Retrieve feed publish form HTML
Args:
RF_Feed
Return: string of HTML representing single feed publish form content
Retrieve feed subscription form HTML
Args:
RF_Feed
Return: string of HTML representing single feed subscription form content
Retrieve feed tags form HTML
Args:
RF_Feed
Return: string of HTML representing single feed tags form content
Retrieve item body HTML
Args:
RF_Item
Return: string of HTML representing single item body content
Retrieve item comment form HTML
Args:
RF_Item
Return: string of HTML representing single item comment form content
Retrieve item edit form HTML
Args:
RF_Item
Return: string of HTML representing single item edit form content
Retrieve item head HTML
Args:
RF_Item
Return: string of HTML representing single item head content
Mark a feed as published
Args:
RF_Feed
Return: boolean true
on success
Mark all items in a feed as read
Args:
RF_Feed
sReturn: boolean true
on success
Mark a feed as unpublished
Args:
RF_Feed
Return: boolean true
on success
Mark all items in a feed as unread
Args:
RF_Feed
sReturn: boolean true
on success
Mark an item as published
Args:
RF_Item
Return: boolean true
on success
Mark an item as read
Args:
RF_Item
Return: boolean true
on success
Mark several items as published
Args:
RF_Item
sReturn: boolean true
on success
Mark several items as read
Args:
RF_Item
sReturn: boolean true
on success
Mark several items as unread
Args:
RF_Item
sReturn: boolean true
on success
Mark an item unas published
Args:
RF_Item
Return: boolean true
on success
Mark an item as unread
Args:
RF_Item
Return: boolean true
on success
Post a new item
Args:
title
: Title of new item, requiredlink
: 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.{"label": ..., "value": ..., "format": ...}
Return: RF_Item
Set an feed's tags
Args:
RF_Feed
false
Return: boolean true
on success
Set an item's comment and tags
Args:
RF_Item
Return: boolean true
on success
Set an item's link
Args:
RF_Item
Return: boolean true
on success
Set an item's tags
Args:
RF_Item
Return: boolean true
on success
Set an item's title, link and content
Args:
RF_Item
Return: boolean true
on success
Toggle keyboard usage flag
Args:
boolean
: turn keyboard usage on or offReturn: boolean true
on success
Reblog is distributed under the GPL (see the LICENSE file in this directory), though some of its included libraries (in./library/
) are not.