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 for editor’s picks on home page in English version GET api/predictions.json?lang=en&editors_pick=1

Example for filtered view of all surveillance predictions in literature GET api/predictions.json?lang=en&category=surveillance&source_type=literature

###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

###Endpoint for connecting existing predictions and realisations: api/connect.json

parameter	description	required?
origin	id of the first node that should be connected	required
target	id of the second node that should be connected	required
action	Creates or destroys a connection between two nodes, defaults to create	optional

Example for connecting realisation id=67 connected to prediction id=42
POST api/connect.json?origin=42&target=67