diff options
author | Andrew Dolgov <[email protected]> | 2015-07-25 20:39:16 +0300 |
---|---|---|
committer | Andrew Dolgov <[email protected]> | 2015-07-25 20:39:16 +0300 |
commit | 680e4682d4b68c5a6c40235fa53bccc8a0508f64 (patch) | |
tree | e1338568b80029b791156b58e7a418977b63e9f9 | |
parent | e726949f6978d7bca84ac019a71dcd96da770b21 (diff) |
fox created page: ApiReference
-rw-r--r-- | ApiReference.md | 420 |
1 files changed, 420 insertions, 0 deletions
diff --git a/ApiReference.md b/ApiReference.md new file mode 100644 index 0000000..e022612 --- /dev/null +++ b/ApiReference.md @@ -0,0 +1,420 @@ +JSON API Reference +================== + +Supported since version:1.4.0. + +The API is pluggable, plugins can use host +<code>add\_api\_method()</code> to add custom API calls (see +<code>classes/pluginhost.php</code> for details). + +Summary +------- + +The API is stateful. You need to login and maintain a session ID to +perform further operations. Session ID should be specified using JSON +parameter **sid**. I.e. + + $ curl -d '{"sid":"your-session-id","op":"getVersion"}' http://example.dom/tt-rss/api/ + +All API calls output JSON-encoded data. API can be enabled or disabled +per-user in the preferences. Client parameters should be passed encoded +using JSON in HTTP POST data (supported since version:1.5.3). Older +versions allowed passing parameters using HTTP GET and POST, but this is +no longer supported. + +Testing API calls (using curl) +------------------------------ + + $ curl -d '{"op":"login","user":"you","password":"xxx"}' http://example.dom/tt-rss/api/ + +Most of the calls (except login, logout, isLoggedIn) require valid login +session or will return this error object: +<code>{[error]("NOT_LOGGED_IN"}</code>) + +Output format +------------- + +### 1.5.0 and above + +All API methods return JSON data like this: + +<code>{[seq](0,"status":0,"content":{"version":"1.4.3.1"}}</code>) + +- seq (integer) is the sequence number supplied by client (&seq=131) +- status (integer) indicates whether request has been completed + successfully, can be either 0 (API\_STATUS\_OK) or 1 + (API\_STATUS\_ERR) +- content is the actual reply content, as documented below in method + descriptions. + +### 1.4.3 and below (obsolete) + +Methods return the “content” object below, sequence numbers and statuses +are not supported. + +Methods +------- + +### getApiLevel (since version:1.5.8, api level 1) + +Return an abstracted integer API version level, increased with each API +functionality change. This is the proper way to detect host API +functionality, instead of using getVersion. + +<code>{[level](1}</code>) + +Whether tt-rss returns error for this method (e.g. version:1.5.7 and +below) client should assume API level 0. + +### getVersion + +Returns tt-rss version. As of, version:1.5.8 it is not recommended to +use this to detect API functionality, please use getApiLevel instead. + +<code>{[version]("1.4.0"}</code>) + +### login + +Parameters: + +- user (string) +- password (string) + +Returns client session ID. + +<code>{[session\_id]("xxx"}</code>) + +It can also return several error objects: + +- If API is disabled for this user: + <code>{[error]("API_DISABLED"}</code>) +- If specified username and password are incorrect: + <code>{[error]("LOGIN_ERROR"}</code>) + +In case it isn’t immediately obvious, you have to login and get a +session ID even if you are using single user mode. You can omit user and +password parameters. + +On version:1.6.0 and above login also returns current API level as an +<code>api\_level</code> integer, you can use that instead of calling +getApiLevel after login. + +### logout + +Closes your login session. Returns either status-message +<code>{[status]("OK"}</code>) or an error (e.g. +<code>{[error]("NOT_LOGGED_IN"}</code>)) + +### isLoggedIn + +Returns a status message with boolean value showing whether your client +(e.g. specific session ID) is currently logged in. + +<code>{[status](false}</code>) + +### getUnread + +Returns an integer value of currently unread articles. + +<code>{[unread]("992"}</code>) + +### getCounters + +Returns JSON-encoded counter information. Requires version:1.5.0. + +- output\_mode (string, default: flc) - what kind of information to + return (f - feeds, l - labels, c - categories, t - tags) + +### getFeeds + +Returns JSON-encoded list of feeds. The list includes category id, +title, feed url, etc. + +Parameters: + +- cat\_id (integer) - return feeds under category cat\_id +- unread\_only (bool) - only return feeds which have unread articles +- limit (integer) - limit amount of feeds returned to this value +- offset (integer) - skip this amount of feeds first +- include\_nested (bool) - include child categories (as Feed objects + with is\_cat set) **requires version:1.6.0** + +Pagination: + +Limit and offset are useful if you need feedlist pagination. If you use +them, you shouldn’t filter by unread, handle filtering in your app +instead. + +Special category IDs are as follows: + +- 0 - Uncategorized +- ~~1~~ Special (e.g. Starred, Published, Archived, etc.) +- ~~2~~ Labels + +Added in version:1.5.0: + +- ~~3~~ All feeds, excluding virtual feeds (e.g. Labels and such) +- ~~4~~ All feeds, including virtual feeds + +Known bug: Prior to version:1.5.0 passing null or 0 cat\_id to this +method returns full list of feeds instead of Uncategorized feeds only. + +### getCategories + +Returns JSON-encoded list of categories with unread counts. + +- unread\_only (bool) - only return categories which have unread + articles +- enable\_nested (bool) - switch to nested mode, only returns topmost + categories **requires version:1.6.0** +- include\_empty (bool) - include empty categories **requires + version:1.7.6** + +Nested mode in this case means that a flat list of **only** topmost +categories is returned and unread counters include counters for child +categories. + +This should be used as a starting point, to display a root list of all +(for backwards compatibility) or topmost categories, use getFeeds to +traverse deeper. + +### getHeadlines + +Returns JSON-encoded list of headlines. + +Parameters: + +- feed\_id (integer) - only output articles for this feed +- limit (integer) - limits the amount of returned articles (see below) +- skip (integer) - skip this amount of feeds first +- filter (string) - currently unused (?) +- is\_cat (bool) - requested feed\_id is a category +- show\_excerpt (bool) - include article excerpt in the output +- show\_content (bool) - include full article text in the output +- view\_mode (string = all\_articles, unread, adaptive, marked, + updated) +- include\_attachments (bool) - include article attachments (e.g. + enclosures) **requires version:1.5.3** +- since\_id (integer) - only return articles with id greater than + since\_id **requires version:1.5.6** +- include\_nested (boolean) - include articles from child categories + **requires version:1.6.0** +- order\_by (string) - override default sort order **requires + version:1.7.6** +- sanitize (bool) - sanitize content or not **requires version:1.8** + (default: true) +- force\_update (bool) - try to update feed before showing headlines + **requires version:1.14 (api 9)** (default: false) +- has\_sandbox (bool) - indicate support for sandboxing of iframe + elements **<span class="10 api"></span>** (default: false) +- include\_header (bool) - adds status information when returning + headlines, instead of array(articles) return value changes to + array(header, array(articles)) (api 12) + +Limit: + +Before **API level 6** maximum amount of returned headlines is capped at +60, API 6 and above sets it to 200. + +This parameters might change in the future (supported since **API level +2**): + +- search (string) - search query (e.g. a list of keywords) +- search\_mode (string) - all\_feeds, this\_feed (default), this\_cat + (category containing requested feed) +- match\_on (string) - ignored + +Special feed IDs are as follows: + +- ~~1~~ starred +- ~~2~~ published +- ~~3~~ fresh +- ~~4~~ all articles +- 0 - archived +- IDs \< ~~10~~ labels + +Sort order values: + +- date\_reverse - oldest first +- feed\_dates - newest first, goes by feed date +- (nothing) - default + +### updateArticle + +Update information on specified articles. + +Parameters: + +- article\_ids (comma-separated list of integers) - article IDs to + operate on +- mode (integer) - type of operation to perform (0 - set to false, 1 - + set to true, 2 - toggle) +- field (integer) - field to operate on (0 - starred, 1 - published, 2 + - unread, 3 - article note **since api level 1**) +- data (string) - optional data parameter when setting note field + (since **api level 1**) + +E.g. to set unread status of articles X and Y to false use the +following: + +<code>?article\_ids=X,Y&mode=0&field=2</code> + +Since version:1.5.0 returns a status message: + +<code>{[status]("OK","updated":1}</code>) + +“Updated” is number of articles updated by the query. + +### getArticle + +Requests JSON-encoded article object with specific ID. + +- article\_id (integer) - article ID to return **as of 15.10.2010 + git** or version:1.5.0 supports comma-separated list of IDs + +Since version:1.4.3 also returns article attachments. + +### getConfig + +Returns tt-rss configuration parameters: + +<code>{[icons\_dir]("icons","icons_url":"icons","daemon_is_running":true,"num_feeds":71}</code>) + +- icons\_dir - path to icons on the server filesystem +- icons\_url - path to icons when requesting them over http +- daemon\_is\_running - whether update daemon is running +- num\_feeds - amount of subscribed feeds (this can be used to refresh + feedlist when this amount changes) + +### updateFeed + +Tries to update specified feed. This operation is not performed in the +background, so it might take considerable time and, potentially, be +aborted by the HTTP server. + +- feed\_id (integer) - ID of feed to update + +Returns status-message if the operation has been completed. + +<code>{[status]("OK"}</code>) + +### getPref + +Returns preference value of specified key. + +- pref\_name (string) - preference key to return value of + +<code>{[value](true}</code>) + +### catchupFeed + +Required version: version:1.4.3 + +Tries to catchup (e.g. mark as read) specified feed. + +Parameters: + +- feed\_id (integer) - ID of feed to update +- is\_cat (boolean) - true if the specified feed\_id is a category + +Returns status-message if the operation has been completed. + +<code>{[status]("OK"}</code>) + +### getCounters + +Required version: version:1.5.0 + +Returns a list of unread article counts for specified feed groups. + +Parameters: + +- output\_mode (string) - Feed groups to return counters for + +Output mode is a character string, comprising several letters (defaults +to “flc”): + +- f - actual feeds +- l - labels +- c - categories +- t - tags + +Several global counters are returned as well, those can’t be disabled +with output\_mode. + +### getLabels (since API level 1) + +Returns list of configured labels, as an array of label objects: + +<code>{[id](2,"caption":"Debian","fg_color":"#e14a00","bg_color":"#ffffff","checked":false},</code>) + +Before version:1.7.5 + +Returned id is an internal database id of the label, you can convert it +to the valid feed id like this: + +<code>feed\_id = ~~11~~ label\_id</code> + +After: + +No conversion is necessary. + +Parameters: + +\* article\_id (int) - set “checked” to true if specified article id has +returned label. + +### setArticleLabel (since API level 1) + +Assigns article\_ids to specified label. + +Parameters: + +\* article\_ids - comma-separated list of article ids\ + \* label\_id (int) - label id, as returned in getLabels\ + \* assign (boolean) - assign or remove label + +Note: Up until version:1.15 setArticleLabel() clears the label cache for +the specified articles. Make sure to regenerate it (e.g. by calling API +method getLabels() for the respecting articles) when you’re using +methods which don’t do that by themselves (e.g. getHeadlines()) +otherwise getHeadlines() will not return labels for modified articles. + +### shareToPublished (since API level 4 - version:1.6.0) + +Creates an article with specified data in the Published feed. + +Parameters: + +\* title - Article title (string)\ + \* url - Article URL (string)\ + \* content - Article content (string) + +### subscribeToFeed (API level 5 - version:1.7.6) + +Subscribes to specified feed, returns a status code. See +subscribe\_to\_feed() in functions.php for details. + +Parameters: + +\* feed\_url - Feed URL (string)\ + \* category\_id - Category id to place feed into (defaults to 0, +Uncategorized) (int)\ + \* login, password - Self explanatory (string) + +### unsubscribeFeed (API level 5 - version:1.7.6) + +Unsubscribes specified feed. + +Parameters: + +\* feed\_id - Feed id to unsubscribe from + +### getFeedTree (API level 5 - version:1.7.6) + +- include\_empty (bool) - include empty categories + +Returns full tree of categories and feeds. + +Note: counters for most feeds are not returned with this call for +performance reasons. |