API Methods

Based on the featured outlined on the specifications page, these are the API methods we're going to need.

GET

###Endpoint for list of predictions: api/predictions.json

parameter	description	required?
lang	Returns all prediction where the description field for the selected language is not empty	required
editors_pick	Returns all predictions highlighted as editor’s pick	optional
category	Returns all predictions from a specific category, e.g. surveillance or health	optional
source_type	Returns all predictions from a specific source type, e.g. TV series	optional
title	Returns all predictions for a specific title, e.g. Brave New World (since titles of different source types are in one of five different fields, title should return whichever of literature_title, movie_title, series_title, game_title, other_title has a value)	optional
creator	Returns all predictions by a specific creator, e.g. George Orwell (since cretors of different source types are in one of five different fields, creator should return whichever of literature_author, movie_director, game_studio, other_creator has a value)	optional
exclude	Excludes a prediction from the list by id (e.g. if we show “view more” along a prediction, so we don’t get the current prediction again)	optional
page	the list is paginated, 50 predictions per page. defaults to 1	optional
limit	Limits the number of predictions to return	optional
img	Returns all predictions where img_url is not empty	optional
incomplete	Returns all predictions where at least one field is empty	optional

Lists are always sorted by latest first (based on timestamp_created).

Example: editor’s picks on home page in English version GET api/predictions.json?lang=en&editors_pick=1

Example: all surveillance predictions in literature GET api/predictions.json?lang=en&category=surveillance&source_type=literature

Example: all predictions in German by George Orwell except the one with id=777 GET api/predictions.json?lang=de&creator=George-Orwell&exclude=777

###Endpoint for single prediction: api/prediction.json

parameter	description	required?
id	Returns prediction with matching id	required

The returned prediction contains all fields of that prediction PLUS an array of all realisations connected to it.

POST

###Endpoint for creating new predictions and realisations: api/create.json

parameter	description	required?
type	Prediction or realisation	required
prediction_id	if a new realisation is created, this is the ID of the prediction it should be connected to	required (if type==realisation)

Example for the creation of a new prediction POST api/create.json?type=prediction

Example for the creation of a new realisation connected to prediction id=42
POST api/create.json?type=realisation&prediction_id=42