=09

API Public Beta

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>

Authentication

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)

Read

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.

Groups

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 objects



	A 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 0. The =E2=80=9CSparks=E2=80=9D super group is not included in t= his response and is composed of all feeds with an is_spark equ= al to 1.

Feeds

http://yourdomain.com/fever/?api&feeds

A request with the feeds argument will return two addition= al members:

feeds contains an array of group objects
feeds_groups contains an array of feeds_group objects



	A 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>.


	Feeds/Groups Relationships

	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)
	

	Favicons

	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=
s
	

	A favicon object has the following members:

	
	id (positive integer)
	data (base64 encoded image data; prefixed by image type)<=
/li>
	

	An example data value:
=09
	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&items

	A request with the items argument will return two addition=
al members:

	
	items contains an array of item objects
	total_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)
	

	Hot Links

	http://yourdomain.com/fever/?api&links

	A request with the links argument will return one addition=
al member:

	
	links contains an array of link objects
	

	A link object has the following members:

	
	id (positive integer)
	feed_id (positive integer) only use when is_item equals 1

	item_id (positive integer) only use when is_item equals 1

	temperature (positive float)
	is_item (boolean integer)
	is_local (boolean integer) used to determine if the sourc=
e feed and favicon should be displayed
	is_saved (boolean integer) only use when is_item equals 1

	title (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).

	Link Caveats

	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.

	Sync

	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_ids argument 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.

	Write

	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=3Ditem
	as=3D? where ? is replaced with read, saved or unsaved

	id=3D? where ? is replaced with the id=
 of the item to modify
	


	Marking 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 group
	as=3Dread
	id=3D? where ? is replaced with the id=
 of the feed or group to modify
	before=3D? where ? is replaced with the Unix=
 timestamp of the the local client=E2=80=99s most recent items=
 API request
	

	You 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=3Dgroup
	as=3Dread
	id=3D0
	before=3D? where ? is replaced with the Unix=
 timestamp of the the local client=E2=80=99s last items API re=
quest
	

	Similarly 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=3Dgroup
	as=3Dread
	id=3D-1
	before=3D? where ? is replaced with the Unix=
 timestamp of the the local client=E2=80=99s last items API re=
quest

Sep	Dec	Feb
	= 21
2021	2022	2023