Open mjstallard opened 8 years ago
Updated to no longer require pinning the most recent video to the top of the returned results
Hey @mjstallard thanks for throwing this together!
How rigid are the API endpoints in your spec? I'm questioning the /newsfeed
and /newsfeed/:id
naming choice. I like the "plural nouns" and "concrete names" pattern suggested in the Apigee Rest API Conventions article. Perhaps it could look something like: /stories
and /stories/:id
(substitute "stories" for any better synonym).
Also, since we're supporting videos, news, and articles, do we need endpoints for each resource type? e.g. /videos
// /videos/:id
; /news-story
// /news-story/:id
; /articles
// /articles/:id
If we were to use that pattern, then we might not even need the /newsfeed/:id
item endpoint, since we could link directly to the corresponding videos or news or article endpoint.
@dan-f welcome to the party! :) :tada:
I hear you on the naming, for sure. I was scratching my head, and the best I could come up with was news feed (this was basically influenced by the iOS code, which consists of the NewsFeedController
, showing value objects that implement a NewsFeedItem
protocol)...but I'm totally open to other suggestions - /stories
works for me, although it might be nice to find a noun that better encompasses videos...(insert the usual quote about naming and cache invalidation here! :stuck_out_tongue_winking_eye: )
I see your point about an endpoint per resource type - I think this should be fine (and indeed more RESTful). We'll receive the type of the resource to fetch in push notifications to the mobile apps anyway, so this won't be a problem. Sounds good :+1:
@mjstallard @dan-f @benmadrone
OK I've gotten the code up to this (revised) spec, as I understood it. There are endpoints per resource type. I didn't rename "news" to another noun, as that's the DB table name and I thought it would be confusing if it were named otherwise (plus there didn't seem to be an obvious choice for a better noun).
One thing I was unsure of, and we can fix if it's wrong in a followup PR, is what do you do if the noun already has an 's' at the end? By convention, should it be /news or /newses? I went with /news.
Update - after chatting with @mjstallard we will get rid of the "news" "articles" and "videos" endpoints in favor of "/newsfeeds" which will return the items of all types.
This way the mobile clients on all platforms will get the same data, and not need any logic to combine them. Also for example, if we want to change the number of items or their relative balance, etc we can change all that logic on the server side rather than updating the apps and relying on users to upgrade.
Individual items will be retrieved by ID via this pattern: /news/123, /articles/123 or /videos/123.
Connect News Feed API Specification
JSON API
Introduction
Word! I'd like to follow the JSON API spec in order to provide a nice standardized format. This means that, in theory, we can plug in a fancy library on each of the mobile platforms to make deserializing it a little easier (although this definitely a theory at this point). Regardless, it's a fairly nicely structured format.
There are some Python implementations of it at http://jsonapi.org/implementations/#server-libraries-python, which may make your life much easier :)
I'd like to suggest that we have unit tests around this, as it'll be a core part of the app and it'd be good to avoid regressions as the news feed definition evolves, if possible.
It should probably share the database with Sharknado, but probably shouldn't be colocated, so that we can scale it independently.
I know that @nymd had some ideas around server side tech (possibly using Tornado), but that is beyond my knowledge (and remit as a lowly iOS developer on this project) and hence is not in the scope of this spec :D
Example
Here's an example of how we use it already for Action Alerts from connect:
https://connect.berniesanders.com/api/action_alerts
Endpoint definition
/newsfeed
The content that is included in a response by default is:
article_type
ofPressRelease
ORDemocracyDaily
By default, the content should be English language. Later on, if we include Spanish content in the app, we should be able to pass a query parameter that defines the language to be returned.
Sort order
The current behavior on the iOS app is to fetch up to 30 News or Articles, and up to 5 Videos It might be nice to have some admin control over the mix of content (i.e., tweak the maximum number of each type), but that's not necessary for a first release.
The sort ordering (derived from the iOS app) is as follows:
It might also be nice to allow an admin to "pin" a news story, article or video to the top of the list, but again this is not necessary for a first release.
Required Fields
News and Articles
title
, e.g. "Improving the Rural Economy"body_markdown
, e.g. "The Governator"excerpt
, e.g. "I'll be back"timestamp_publish
, e.g. "2015-12-29T04:23:16+00:00"url
, e.g. "https://berniesanders.com/issues/improving-the-rural-economy/"image_url
, e,g, "https://berniesanders.com/wp-content/uploads/2015/05/IMG_05471.jpg"type
, e.g. "News" or "Article"id
, e.g. "7fbb52b9-e747-4f7d-9b14-4b7ecdab4ac5"Videos
title
, e.g. "Expand Social Security"video_id
, e.g. "c4e9yiuKAmY"description
, e.g. "Get to da choppa"timestamp_publish
, e.g. "2016-01-13T19:08:43+00:00"thumbnail_url
, e.g. "https://i.ytimg.com/vi/c4e9yiuKAmY/hqdefault.jpg"type
, e.g. "Video"id
, e.g. "7fbb52b9-e747-4f7d-9b14-4b7ecdab4ac5"Sample response
Something akin to this should work:
/newsfeed/:id
This will return a single record matching the id formatted as per the news feed above, or a 404.
Sample response
For example, a call to
/newsfeed/7de0c82f-2a63-4286-9b5c-84a0917f3a0f
would return: