java.blogs provides a few basic XML-RPC APIs to allow users to search the site, and notify java.blogs that their blog has updated.
Why XML-RPC?
Why not SOAP, or a REST-ful interface? XML-RPC seems to be the standard interface for weblog aggregators and weblog search-tools, has the widest tool support, and is really simple to implement. In addition, we needed to use XML-RPC for the weblogs.com ping API, so it made sense to re-use it elsewhere.
Update Notification Pings
This API allows you to notify java.blogs when your blog updates. This allows your posts to appear on java.blogs soon after you update, instead of waiting for your next scheduled update.
The API
The API originated at weblogs.com, and is described here. Many weblogging tools already support this API: consult the documentation for your blogging-tool of choice. For example, you can configure Moveable Type to ping java.blogs by going to Weblog Configuration -> Preferences, and pasting the URL below into the box labeled ‘Notify the following sites when I update my weblog’.
Pings should be POST-ed to: http://javablogs.com/xmlrpc
Notes:
- The website URL submitted with the ping must be exactly the same as the site URL you have registered with java.blogs (note, this is your site address, not that of your RSS feed). If your pings are being rejected due to the URL not being found, please check in your weblog details that the URLs match exactly, including matching upper- and lower-case, and the presence of a trailing slash.
- When a ping is received, java.blogs will add your site to the queue of sites to be updated in the next update run. As such, it may still take several minutes for your site to be checked.
- Similarly, the front-page of java.blogs is cached, so it may take several more minutes for your post to make it onto the front page.
- If you have your blog set up to automatically ping java.blogs, there should be no need for java.blogs to perform its normal scheduled checks of your site. Please consider reducing the frequency of these checks in your weblog preferences.
Search API v1.0
This (currently experimental) API allows you to perform searches against the tens of thousands of blog entries indexed by java.blogs. You will need to be familiar with XML-RPC to implement a client.
Method
To perform a search, the POST URL is http://javablogs.com/xmlrpc, and
the method name is javablogs1.search. (The 1 is the major version number of the
API. If we ever have make backwards-incompatible changes, we can put them in a new namespace,
javablogs2)
Parameters
The method takes a single parameter of type struct (The XML-RPC equivalent of a map,
hashtable or dictionary) with the following keys and values:
| Name | Type | Notes |
|---|---|---|
query | string | (Required) The search string (boolean operators AND, OR and NOT are supported) |
createdAfter | date | (Optional) Return only results from after this date |
createdBefore | date | (Optional) Return only results from before this date |
maxResults | int | (Optional) Return at most this many results. (Defaults to 10, and java.blogs> will never return more than 20 results) |
includeDescriptions | boolean | (Optional) Include full item descriptions with results? (Defaults to false) |
Return Value
The call will return a struct. Check the flError member of the struct to see if the call
has been successful or not. If the search has failed, flError will be non-zero, and the
message value will contain an English (or at least Java-nese) error-message. Otherwise,
the struct will contain the following:
| Name | Type | Notes |
|---|---|---|
totalResults | int | The total number of results that match the query (not all of which may have been returned, depending on the value of maxResults in the query) |
results | array | An array of the search results returned |
Each individual search result in the results array is also a struct representing a blog entry
that was matched by the search:
| Name | Type | Notes |
|---|---|---|
entryTitle | string | The title of the blog entry |
entryLink | array | The URL of the blog entry |
entryDescription | string | The full description of the blog entry from its RSS feed (only present if requested in the query) |
blogTitle | string | The title of the blog the entry is from |
blogLink | string | The URL of the blog the entry is from |
Total: 2477
