Fever 1.14 introduces the new Fever API. This API is in public beta and= + currently supports basic syncing and consuming of content. A subsequent up= +date will allow for adding, editing and deleting feeds and groups. The API= +=E2=80=99s primary focus is maintaining a local cache of the data in a remo= +te Fever installation.
+ +I am soliciting feedback from interested developers and = +as such the beta API may expand to reflect that feedback. The current API i= +s incomplete but stable. Existing features may be expanded on but will not = +be removed or modified. New features may be added.
+ +I=E2=80=99ve created a simple HTM= +L widget that allows you to query the Fever API and view the response.<= +/p> + +
Without further ado, the Fever API endpoint URL looks like:
+ +http://yourdomain.com/fever/?api
+
+ All requests must be authenticated with a POSTed api=
+_key. The value of api_key should be the md5 checksum o=
+f the Fever accounts email address and password concatenated with a colon. =
+An example of a valid value for api_key using PHP=E2=80=99s na=
+tive md5() function:
$email =3D 'you@yourdomain.com';
+$pass =3D 'b3stp4s4wd3v4';
+$api_key =3D md5($email.':'.$pass);
+
+
+ A user may specify that https be used to connect to their =
+Fever installation for additional security but you should not assume that a=
+ll Fever installations support https.
The default response is a JSON object containing two members:
+ +api_version contains the version of the API responding (p=
+ositive integer)auth whether the request was successfully authenticated (=
+boolean integer)The API can also return XML by passing xml as the optional=
+ value of the api argument like so:
http://yourdomain.com/fever/?api=3Dxml
+
+ The top level XML element is named response.
The response to each successfully authenticated request will have auth set to 1 and include at least one additional memb=
+er:
last_refreshed_on_time contains the time of the most rece=
+ntly refreshed (not updated) feed (Unix timestamp/integer)When reading from the Fever API you add arguments to the query string o=
+f the API endpoint URL. If you attempt to POST these arguments=
+ (and their optional values) Fever will not recognize the request.
http://yourdomain.com/fever/?api&groups
+
+ A request with the groups argument will return two additio=
+nal members:
groups contains an array of group objects
+ feeds_groups contains an array of feeds_group objectsA group object has the following members:
id (positive integer)title (utf-8 string)The feeds_group object is documented under =E2=80=9CFeeds/=
+Groups Relationships.=E2=80=9D
The =E2=80=9CKindling=E2=80=9D super group is not included in this resp=
+onse and is composed of all feeds with an is_spark equal to is_spark equ=
+al to 1.
http://yourdomain.com/fever/?api&feeds
+
+ A request with the feeds argument will return two addition=
+al members:
feeds contains an array of group objectsfeeds_groups contains an array of feeds_group objectsA feed object has the following members:
id (positive integer)favicon_id (positive integer)title (utf-8 string)url (utf-8 string)site_url (utf-8 string)is_spark (boolean integer)last_updated_on_time (Unix timestamp/integer)The feeds_group object is documented under =E2=80=9CFeeds/=
+Groups Relationships.=E2=80=9D
The =E2=80=9CAll Items=E2=80=9D super feed is not included in this resp=
+onse and is composed of all items from all feeds that belong to a given gro=
+up. For the =E2=80=9CKindling=E2=80=9D super group and all user created gro=
+ups the items should be limited to feeds with an is_spark equa=
+l to 0. For the =E2=80=9CSparks=E2=80=9D super group the items=
+ should be limited to feeds with an is_spark equal to 1<=
+/code>.
A request with either the groups or feeds arg=
+uments will return an additional member:
A feeds_group object has the following members:
group_id (positive integer)feed_ids (string/comma-separated list of positive integer=
+s)http://yourdomain.com/fever/?api&favicons
+
+ A request with the favicons argument will return one addit=
+ional member:
favicons contains an array of favicon object=
+sA favicon object has the following members:
id (positive integer)data (base64 encoded image data; prefixed by image type)<=
+/li>
+ An example data value:
image/gif;base64,R0lGODlhAQABAIAAAObm5gAAACH5BAEAAAAALAAAAAABAA=
+EAAAICRAEAOw=3D=3D
+
+ The data member of a favicon object can be us=
+ed with the data: protocol to embed an image in CSS or HTML. A=
+ PHP/HTML example:
echo '<img src=3D"data:'.$favicon['data'].'">';+ +Items
+ ++ +http://yourdomain.com/fever/?api&itemsA request with the
+ +itemsargument will return two addition= +al members:
items contains an array of item objectstotal_items contains the total number of items stored in =
+the database (added in API version 2)An item object has the following members:
id (positive integer)feed_id (positive integer)title (utf-8 string)author (utf-8 string)html (utf-8 string)url (utf-8 string)is_saved (boolean integer)is_read (boolean integer)created_on_time (Unix timestamp/integer)Most servers won=E2=80=99t have enough memory allocated to PHP to dump = +all items at once. Three optional arguments control determine the items inc= +luded in the response.
+ +Use the since_id argument with the highest id of local=
+ly cached items to request 50 additional items. Repeat until the item=
+s array in the response is empty.
Use the max_id argument with the lowest id of locally =
+cached items (or 0 initially) to request 50 previous items. Re=
+peat until the items array in the response is empty. (added in=
+ API version 2)
Use the with_ids argument with a comma-separated list =
+of item ids to request (a maximum of 50) specific items. (added in API vers=
+ion 2)
http://yourdomain.com/fever/?api&links
+
+ A request with the links argument will return one addition=
+al member:
links contains an array of link objectsA link object has the following members:
id (positive integer)feed_id (positive integer) only use when is_item equals 1item_id (positive integer) only use when is_item equals 1temperature (positive float)is_item (boolean integer)is_local (boolean integer) used to determine if the sourc=
+e feed and favicon should be displayedis_saved (boolean integer) only use when is_item equals 1title (utf-8 string)url (utf-8 string)item_ids (string/comma-separated list of positive integer=
+s)When requesting hot links you can control the range and offset by speci=
+fying a length of days for each as well as a page to fetch additional hot l=
+inks. A request with just the links argument is equivalent to:=
+
http://yourdomain.com/fever/?api&links&offset=3D0&r=
+ange=3D7&page=3D1
+
+ Or the first page (page=3D1) of Hot links for the past wee=
+k (range=3D7) starting now (offset=3D0).
Fever calculates Hot link temperatures in real-time. The API assumes yo= +u have an up-to-date local cache of items, feeds and favicons with which to= + construct a meaningful Hot view. Because they are ephemeral Hot links shou= +ld not be cached in the same relational manner as items, feeds, groups and = +favicons.
+=09 +Because Fever saves items and not individual links you can only "save" =
+a Hot link when is_item equals 1.
The unread_item_ids and saved_item_ids argume=
+nts can be used to keep your local cache synced with the remote Fever insta=
+llation.
http://yourdomain.com/fever/?api&unread_item_ids+ +A request with the
+ +unread_item_idsargument will return on= +e additional member:
unread_item_ids (string/comma-separated list of positi=
+ve integers)
http://yourdomain.com/fever/?api&saved_item_ids
+
+ A request with the saved_item_ids argument will return one=
+ additional member:
saved_item_ids (string/comma-separated list of positive i=
+ntegers)One of these members will be returned as appropriate when marking an it= +em as read, unread, saved, or unsaved and when marking a feed or group as r= +ead.
+ +Because groups and feeds will be limited in number compared to items, t= +hey should be synced by comparing an array of locally cached feed or group = +ids to an array of feed or group ids returned by their respective API reque= +st.
+ +The public beta of the API does not provide a way to add, edit or delet=
+e feeds or groups but you can mark items, feeds and groups as read and save=
+ or unsave items. You can also unread recently read items. When writing to =
+the Fever API you add arguments to the POST data you submit to=
+ the API endpoint URL.
Adding unread_recently_read=3D1 to your POST =
+data will mark recently read items as unread.
You can update an individual item by adding the following three argumen=
+ts to your POST data:
mark=3Ditemas=3D? where ? is replaced with read=
+code>, saved or unsavedid=3D? where ? is replaced with the id=
+ of the item to modifyMarking a feed or group as read is similar but requires one additional = +argument to prevent marking new, unreceived items as read:
+ +mark=3D? where ? is replaced with feed=
+ or groupas=3Dreadid=3D? where ? is replaced with the id=
+ of the feed or group to modifybefore=3D? where ? is replaced with the Unix=
+ timestamp of the the local client=E2=80=99s most recent items=
+ API requestYou can mark the =E2=80=9CKindling=E2=80=9D super group (and the =E2=80=
+=9CSparks=E2=80=9D super group) as read by adding the following four argume=
+nts to your POST data:
mark=3Dgroupas=3Dreadid=3D0before=3D? where ? is replaced with the Unix=
+ timestamp of the the local client=E2=80=99s last items API re=
+questSimilarly you can mark just the =E2=80=9CSparks=E2=80=9D super group as=
+ read by adding the following four arguments to your POST data=
+:
mark=3Dgroupas=3Dreadid=3D-1before=3D? where ? is replaced with the Unix=
+ timestamp of the the local client=E2=80=99s last items API re=
+quest