This is the public REST API every Starve user can use. All endpoints respond with a semantic HTTP status code and optionally carry a payload body.
This API is being versioned via an Accept header:
Accept: application/vnd.starve+json; version=1
This header has to be part of every request made to the API.
Just use HTTP basic auth with the email and password you use to sign into Starve:
curl -u email@host.com:password https://api.starve.glasz.org/hello
If you can't be authorized (for any endpoint), you'll receive 401 Unauthorized.
To get all the feeds you subscribed to:
GET /subscriptions.json
Response
Returns an array of all subscriptions.
[
{
"created_at": "2014-04-16T23:30:26.000+02:00",
"favicon": "https://starve-static.s3.amazonaws.com/assets/favicons/default/missing-1d2c306d00fcac5a96125a07835cd790.png",
"feed_url": "http://edgerails.info/atom.xml",
"title": "Edge Rails.info",
"feed_id": 177,
"folder_id": 18,
"id": 467
},
...
]
You can subscribe to a feed by submitting it's URL to the following endpoint.
POST /subscriptions.json?feed_url=https://firstlook.org/theintercept/feed/
Response
If no RSS feed could be found at the feed_url, you'll receive 403 Forbidden.
If the feed is already among your subscriptions, you'll receive a 301 redirect with a Location header whose value is the API URL to the subscription.
If the subscription was new and successful, you'll receive a 201 Created and a Location header whose value is the API URL to the new subscription.
DELETE /subscriptions/:id.json
Response
This endpoint responds with 204 No Content upon successful unsubscription.
If a subscription with :id does not exist, you'll receive a 404 Not Found.
Gets you all the entries -- optionally scoped by feed.
GET /entries.json
GET /entries/unread.json
GET /entries/favorites.json
GET /feeds/:feed_id/entries.json
GET /feeds/:feed_id/entries/unread.json
GET /feeds/:feed_id/entries/favorites.json
All of the above should be obvious. The last 3 examples show how to retrieve
entries for a specific feed identified by a :feed_id.
Response
From either endpoint you'll receive 200 OK and an array of entries.
[
{
"created_at": "2014-04-16T23:32:21.000+02:00",
"published_at": "2014-04-16T22:00:42.000+02:00",
"id": 7628,
"feed_id": 215,
"title": "Simple Color Instantiation with NSString",
"url": "http://iosdevelopertips.com/objective-c/simple-color-instantiation-nsstring.html",
"author": "John Muchow",
"excerpt": "<p>Category on NSString allowing simple color instantiation from its content – Nicolas Goutaland read more on github.com</p>\n<p>iOS Developer Tips & Tricks : <a href=\"http://iOSDeveloperTips.com\">iOSDeveloperTips.com</a></p>\n",
"content": "<p>Category on NSString allowing simple color instantiation from its content – Nicolas Goutaland read more on github.com</p>\n<p>iOS Developer Tips & Tricks : <a href=\"http://iOSDeveloperTips.com\">iOSDeveloperTips.com</a></p>\n",
"summary": null
},
...
]
To mark an entry as read or unread use the following endpoints.
The :id placeholder is to be substituted with the ID of an entry.
PATCH /entries/:id/mark_read.json
PATCH /entries/:id/mark_unread.json
Response: Both will just respond with 204 No Content.
To toggle read status on up to 1000 entries at once use the following endpoint.
To get all unread entries:
GET /entries/unread.json
Response: 200 OK with an array of entry IDs.
[123,345,567]
To mark them unread:
POST /entries/unread.json
{"entry_ids":[123,345,567]}
Response: 204 No Content
Or, to mark them read
DELETE /entries/unread.json
{"entry_ids":[123,345,567]}
Response: 204 No Content
To add an entry to your favorites or remove it call the following entries
with :id substituted with the ID of the entry.
PATCH /entries/:id/favor.json
PATCH /entries/:id/disfavor.json
Response: Both will report success with 204 No Content.
To toggle favorite status on up to 1000 entries at once use the following endpoint.
To get all favorites:
GET /entries/favorites.json
Response: You'll receive an array of entry IDs.
[123,345,567]
To favor multiple entries:
POST /entries/favorites.json
{"entry_ids":[123,345,567]}
Response: 204 No Content
Or, to disfavor them:
DELETE /entries/favorites.json
{"entry_ids":[123,345,567]}
Response: 204 No Content
Subscriptions are organized in folders.
GET /folders.json
Response: You'll get an array of all your folders.
[
{
"unread_articles_count": 10,
"created_at": "2014-04-16T23:30:28.000+02:00",
"title": "politics",
"id": 17
},
...
]
GET /folders/:id.json
Response: 200 OK with an object with folder properties.
{
"unread_articles_count": 255,
"created_at": "2014-04-16T23:30:27.000+02:00",
"title": "objc",
"id": 16
}
POST /folders.json?folder[title]=new%20folder
Response: Upon successful creation you'll recieve a Location redirect
to the newly created folder's API URL.
DELETE /folders/:id.json
Response: This endpoint responds with 204 No Content upon successful deletion.
If a folder with :id does not exist, you'll receive a 404 Not Found.