api; xml-rpc (or even json)

Request new functionality here
futtta
Bear Rating Trainee
Bear Rating Trainee
Posts: 30
Joined: 16 Dec 2009, 00:20
Location: belgium
Contact:

api; xml-rpc (or even json)

Postby futtta » 16 Dec 2009, 01:13

hi all;
i've been testing tt-rss to see if it can replace google reader and i must say kudo's for a great piece of software! i was thinking of hacking together a small POC for a client (as in "client/server", not as in "customer") using e.g. the iUI iphone-UI-like presentation framework for web applications (cfr. http://code.google.com/p/iui/, with an example here) and for that purpose I was looking for an api, preferably outputting json.

I found the xml-rpc api in the source code and it seems some functionality is still missing in the api? As far as I can tell, an application that wants to integrate with tt-rss would ideally have the following available in the tt-rss api;

1. get list of categories (optionally only those with unread articles) -> maps to getCategories

2. get list of feeds (optionally only those with unread articles)
2.1. get all feeds -> maps to getSubscribedFeeds
2.2. get feeds for category(x) -> does not exist?

3. get list of (unread) articles
3.1. get (top x|all) (unread) articles from all categories/ feeds -> does not exist
3.2. get (top x|all) (unread) articles for category(x) -> does not exist?
3.3. get (top x|all) (unread) articles for feed(y) -> maps to getFeedHeadlines

4. get individual article -> maps to getArticle
5. toggle article as read -> maps to setArticleRead
6. toggle article as marked -> maps to setArticleMarked

Is anyone (fox?) looking into extending the xml-rpc api? or better yet, is anyone contemplating writing an api that outputs json instead of xml? 8)

kind regards,
frank (belgium)

User avatar
fox
^ me reading your posts ^
Posts: 6318
Joined: 27 Aug 2005, 22:53
Location: Saint-Petersburg, Russia
Contact:

Re: api; xml-rpc (or even json)

Postby fox » 16 Dec 2009, 11:58

Well, the API should certainly be extended in one way or another, although unfortunately I currently don't have much time to do so. Also, given the way you have to jump through hoops to make xml-rpc replies in php, maybe deprecating it and switching to JSON is not a bad idea. It would be easy to convert already implemented API calls and build on that.

I might have some time to take a look at it during new year holidays, but I won't promise anything. Patches are always welcome, though. :D

futtta
Bear Rating Trainee
Bear Rating Trainee
Posts: 30
Joined: 16 Dec 2009, 00:20
Location: belgium
Contact:

Re: api; xml-rpc (or even json)

Postby futtta » 16 Dec 2009, 12:47

i'm not familiar with the tt-rss code, so I hope you indeed find some time during the holidays :)

but i indeed think an api that produces output in json would be both simpler to implement and more powerful to work with (both in terms of cpu-power needed to parse as in time needed to develop against). once you have a json api, building a seperate client (for android, iphone, flex or another web-client) will become a whole lot easier 8)

User avatar
fox
^ me reading your posts ^
Posts: 6318
Joined: 27 Aug 2005, 22:53
Location: Saint-Petersburg, Russia
Contact:

Re: api; xml-rpc (or even json)

Postby fox » 16 Dec 2009, 12:52

You might want to check out trunk code. :D

Specifically, http://tt-rss.org/trac/browser/trunk/ap ... p?rev=3310

User avatar
fox
^ me reading your posts ^
Posts: 6318
Joined: 27 Aug 2005, 22:53
Location: Saint-Petersburg, Russia
Contact:

Re: api; xml-rpc (or even json)

Postby fox » 16 Dec 2009, 13:09

To add, for the time being you send API request parameters using standard HTTP, not JSON or anything fancy like that since it's much easier to test in the browser.

futtta
Bear Rating Trainee
Bear Rating Trainee
Posts: 30
Joined: 16 Dec 2009, 00:20
Location: belgium
Contact:

Re: api; xml-rpc (or even json)

Postby futtta » 16 Dec 2009, 15:26

wow, that's quick for someone who's not doing active development! ;-)

did you deploy this somewhere? I haven't gotten around installing tt-rss yet (i'm one of the 'online.tt-rrs.org'-users for now).

based on a superficial reading of the code, you're outputting unordered sets of key/value pairs (json objects)? but maybe just outputting an ordered list of values (a json array) might suffice?

Code: Select all

$rv = array("version" => VERSION);
print json_encode($rv);


results in something like {"version":"1.3.4"}

whereas

Code: Select all

$rv = array(VERSION);
print json_encode($rv);


would result in ["1.3.4']

but (and I'm brainstorming here, I'm not an expert by any measure) maybe outputting in a format like this might be an ideal compromise;
[<functionname>,<resultstring>,[<data>]]

which for getVersion would result in;
["getVersion","ok",["1.3.4"]]

or getFeeds for someone who's not logged in:
["getFeeds","nok",["You have to authenticate to call this API-function."]]

and getFeeds if logged in and 3 feeds are to be returned:
["getFeeds","ok",[["http://some.url/here","some title","123","1","1","1260968965"],["http://other.url/here","other title","126","1","1","1260968945"],["http://third.url/here","third title","129","1","1","1260968465"]]]

by adding the name of the function and a result-string (or code) the receiving app has all the context needed to parse the ordered list (so name is not needed).

although the result is admittedly less human-readable, using an ordered list instead of unordered key-values would considerably limit the size of response (esp. for getFeeds, getCategories and getHeadlines), meaning less load on the server and quicker response in the client (which is a condition to provide it with a near-realtime feel)?

User avatar
fox
^ me reading your posts ^
Posts: 6318
Joined: 27 Aug 2005, 22:53
Location: Saint-Petersburg, Russia
Contact:

Re: api; xml-rpc (or even json)

Postby fox » 16 Dec 2009, 16:26

This is now available on Online. You'll have to enable API access in the preferences otherwise it won't let you do anything.

I'd like to keep the key/value pairs since they are much easier to work with on both sides in my experience. E.g. feed->title, not feed[9] or something. Also, it makes things harder to break accidentally if I reorder stuff around or add something new. I'm not sure if there is any serious enough performance advantage in typical tt-rss workloads to suffer dumb arrays. :D

I can add method names to the replies, but is this really needed? The application should have some sort of context with regard to the request it sent, unless everything goes in one huge callback function. The API is currently stateful, so some sort of session tracking on the client is needed anyway (keeping the cookie, at least).

User avatar
fox
^ me reading your posts ^
Posts: 6318
Joined: 27 Aug 2005, 22:53
Location: Saint-Petersburg, Russia
Contact:

Re: api; xml-rpc (or even json)

Postby fox » 16 Dec 2009, 16:28

Ed: Also, if you don't have Git, you can check out the latest source here: http://tt-rss.org/trac/browser/trunk/api/index.php (it gets synced hourly from my internal Git repository).

futtta
Bear Rating Trainee
Bear Rating Trainee
Posts: 30
Joined: 16 Dec 2009, 00:20
Location: belgium
Contact:

Re: api; xml-rpc (or even json)

Postby futtta » 16 Dec 2009, 16:52

fox wrote:I'd like to keep the key/value pairs since they are much easier to work with on both sides in my experience. E.g. feed->title, not feed[9] or something. Also, it makes things harder to break accidentally if I reorder stuff around or add something new. I'm not sure if there is any serious enough performance advantage in typical tt-rss workloads to suffer dumb arrays. :D


it indeed does make the code and parsing the output more error-prone, that's clear :)

fox wrote:I can add method names to the replies, but is this really needed? The application should have some sort of context with regard to the request it sent, unless everything goes in one huge callback function. The API is currently stateful, so some sort of session tracking on the client is needed anyway (keeping the cookie, at least).


not really needed if keys are provided, as the keys provide the needed context as well.

did some testing from within the browser, 2 questions (there'll be more I guess, but it's a start);
* when does the session timeout? after of fixed amount to time from logon, or after a fixed amount of time after last call?
* getHeadlines with "show_excerpt=true" returns html (in the excerpt) that does not seem properly escaped?

User avatar
fox
^ me reading your posts ^
Posts: 6318
Joined: 27 Aug 2005, 22:53
Location: Saint-Petersburg, Russia
Contact:

Re: api; xml-rpc (or even json)

Postby fox » 16 Dec 2009, 20:57

Take a look at this: http://online.tt-rss.org/api/apitest.html :D

when does the session timeout? after of fixed amount to time from logon, or after a fixed amount of time after last call?


I didn't specify any expiration options, so I suppose it defaults to remove cookie when you close the browser. That really depends on the client which can actually ignore cookies altogether and use the session id it receives when it performs the login. PHP also garbage collects sessions from time to time, I guess.

getHeadlines with "show_excerpt=true" returns html (in the excerpt) that does not seem properly escaped?


Yeah, it looks kinda funny but it is actually properly (well, good enough for JSON to figure it out, that is) escaped - apitest client linked above shows it. :D

futtta
Bear Rating Trainee
Bear Rating Trainee
Posts: 30
Joined: 16 Dec 2009, 00:20
Location: belgium
Contact:

Re: api; xml-rpc (or even json)

Postby futtta » 16 Dec 2009, 22:42

well, an api and a test app in one day ... great work andrew! :D

futtta
Bear Rating Trainee
Bear Rating Trainee
Posts: 30
Joined: 16 Dec 2009, 00:20
Location: belgium
Contact:

Re: api; xml-rpc (or even json)

Postby futtta » 21 Dec 2009, 01:47

been looking at the api-code some more and experimenting with a small client. for getFeeds and getHeadlines, it would be great to be able to request x items (cfr. limit from getHeadlines) starting from number y, so a client could develop pagination in case of lots of feeds or (even more important) articles?

User avatar
fox
^ me reading your posts ^
Posts: 6318
Joined: 27 Aug 2005, 22:53
Location: Saint-Petersburg, Russia
Contact:

Re: api; xml-rpc (or even json)

Postby fox » 21 Dec 2009, 13:01

Yeah, that can be easily done.

futtta
Bear Rating Trainee
Bear Rating Trainee
Posts: 30
Joined: 16 Dec 2009, 00:20
Location: belgium
Contact:

Re: api; xml-rpc (or even json)

Postby futtta » 21 Dec 2009, 16:27

great to see it's in getFeeds already, suppose/ hope getHeadlines will follow soon? 8)

futtta
Bear Rating Trainee
Bear Rating Trainee
Posts: 30
Joined: 16 Dec 2009, 00:20
Location: belgium
Contact:

Re: api; xml-rpc (or even json)

Postby futtta » 04 Jan 2010, 15:42

hi there fox :)

first things first;
  • a great 2010 to you (and all in the tt-rss community)
  • great to see the new iUI-based mobile version, looks very sexy indeed!
next item; i'm slowly but surely advancing with a mobile version of my own (based on xUI). it's ugly as hell, not feature-complete yet and will be optimized for my personal use, but i think i'll have something usable by mid-january which i will be more then happy to share with anyone interested.

anyway, to be able to make progress, it would be great to have the following features in the json api;
  • in getHeadlines: support the 'unread_only' flag in the request (as in getFeeds/ getCategories)
  • in getHeadlines: have 'link' in response (i'm not using getArticle, but getHeadlines with show_content instead)
  • in updateArticle: provide a way to mark an array of articles (represented by semi-colon seperated seperated values in the parameter, e.g. article_id=3;7;18 in the URL) as (un)read/published/marked (e.g. to avoid marking an entire feed/ category as read if not all items are displayed)
  • provide support for jsonp (which basically allows to do cross-domain xhr, i'm using some proxy.php on a server of my own, but that really is sub-optimal, no?) cfr. http://remysharp.com/2007/10/08/what-is-jsonp/


Return to “Feature requests”

Who is online

Users browsing this forum: No registered users and 2 guests