Internews HID
A Humanitarian Dashboard.
API Documentation
Items
Base URL '/items/'
Create Items
'/items/' POST
{
"body": "blah",
"timestamp": "..."
}
- create an item. Should return the object, including its unique ID and the system allocated creation time.
Create item with tags and categories
{
"body": "blah",
"timestamp": "...",
"metadata": [
{ "slug": "<taxonomy-slug>", // slug OR: name
"name": "<taxonomy name>"
"tems": [
"<tem-name>", // multiple values for tags
"<tem-name>",
"<tem-name>",
]
}
{ "slug": "<taxonomy-slug>", // slug OR: name
"name": "<taxonomy name>"
"tems": ["<tem-name>"] // single for category
}
]
}
We need either the slug
or the name
(from which the slug can be derived),
and a list of relevant terms. If the name and slug don't match, obviously there
should be an exception.
List items
'/items/' GET
-
returns a list of Items
[ { "id": nn, "body": "...", "created": ... "timestamp": ... }, { ... }, ... ]
-
When we do categories it should return those the same way as post above, e.g.:
[ { "id": nn, "body": "...", "created": ... "timestamp": ... "metadata": [ {"name": ... }, ] }, { ... }, ... ]
Filter items by taxonomy
'/items?terms=<taxonomy-slug>:<term-name>' GET
- returns a list of Items tagged (or categorized) with the term <term-name> from the taxonomy <taxonomy-slug>
'terms' can be specified multiple times, to return items that are associated with all specified terms. eg:
'/items?terms=taxo1:term1&terms=taxo1:term2&terms=taxo2:term3
- returns a list of Items tagged (or categorized) with terms term1 of taxo1 and term2 of taxo2 and term3 of taxo2.
Categories and Tags (Taxonomies)
They need their own list and details urls, and we should include them in
the expanded Item
JSON somehow too.
List all Taxonomies
'/taxonomies/' GET
-
Return list of taxonomies
[ { "name": "Ebola Question Type", "slug": "ebola-question-type", "long_name": "Question Type", "cardinality": "optional", "vocabulary": "closed", "terms": [ {"name": "Is Ebola Real", "long name": ... }, ... ] }, { "name": "Reliability", ... }, ... ]
Here
long name
is shorter than thename
because I'm thinking that long name is the one that gets used as a column heading, whereasname
is the unique name for making the unique slug.
NOTE: It is the slug not the name that has has to be unique. What do we do when someone tries to create "Ebola Questions" and "ebola-questions" as taxonomies? Do they map onto the same slug? How do we handle that since the unique field is derived from the given one?
Add a new Taxonomy
'/taxonomies/' POST
{ "name": "Ebola Question Type",
"slug": "ebola-question-type", // do we supply this or is it calculated?
"long_name": "Question Type",
"cardinality": "optional",
"vocabulary": "closed",
"terms": [
{"name": "Is Ebola Real",
"long name": ...
},
...
]
},
Adds a taxonomy (optionally including terms). The slug is calculated it should be returned by the call.
Taxonomy details
'/taxonomies//' GET
{ "name": "Ebola Question Type",
"slug": "ebola-question-type", // calculated from name
"long_name": "Question Type",
"cardinality": "optional",
"vocabulary": "closed",
"terms": [
{"name": "Is Ebola Real",
"long name": ...
},
...
]
},
e.g. /taxonomies/ebola-questions/
- Taxonomy details URL should use the taxonomy's sluggified name
Update Taxonomy Details
/taxonomies/ebola-questions/
POST
{
"long_name": "Question Type",
"cardinality": "optional",
"vocabulary": "closed",
},
- Use the slug as unique id (i.e. don't deal with the internal numeric id)
List terms per taxonomy
`/taxonomies//terms/ GET
- returns list of terms
Add a term to a taxonomy
We could do
/taxonomies/ebola-questions/terms/
POST { 'name': 'vaccine' }
But for the moment we;re doing
/terms/
POST { 'name': 'vaccine', 'taxonomy': 'ebola-questions' }
Get count of items per term for a taxonomy
`/taxonomies//itemcount?start_time=&end_time=<end_time>
Returns a list of terms: [ { "name": "Vaccine", "long_name": "Vaccine Trial", "count": 2 }, { "name": "Measures", "long_name": "What measures could end Ebola?", "count": 1 }, { "name": "Symptoms", "long_name": "Symptoms/Medical", "count": 0 }, ... ]
List all Terms (all taxonomies)
'/terms/' GET
Get list of all terms (from all taxonomies). Could add query params to limit to a certain Taxonomy
'/terms/?taxonomy=ebola-questions' GET
Or item
'/terms/?item=416' GET
Or both
'/terms/?taxonomy=ebola-questions&item=416' GET
Returns a list of terms:
[ { "name": "Ebola Real?",
"long_name": "Is Ebola Real?",
"taxonomy": "ebola-questions",
},
{ "name": "Timescale",
"long_name": "When will Liberia be free of Ebola?"
"taxonomy": "ebola-questions",
},
...
]
Taxonomies as Item metadata:
These categories and tags will be used to store all the variable metadata
for the Item
s. So when we get items, we want to also get their metadata.
And also to allow Item POST requests to add metadata terms.
To create items with metadata
See above Create Items with tags and categories
List terms for an item
/item/// GET
e.g.:
'/items/2314/taxonomies/ebola-questions/' GET
- Return list of ebola questions for item 2314
OR
'/items/2314/taxonomies/terms/' GET
-
list all terms for 2314.
-
Add qyery parameters to select for a given taxonomy
'/items/2314/taxonomies/terms/?taxonomy=ebola-questions' GET
-
To delete a single term
'/items/2314/taxonomies/terms//' DELETE
-
Where term slug is the unique slug for the term. e.g. '/items/2314/taxonomies/terms/ebola-questions-
In which case you can add a term to an object like this
'/items/2314/ebola-questions/' POST { 'name': 'Duration' }
And you can remove one like this
'/items/2314/ebola-questions/duration' DELETE
Dependencies
To run all the tests, you need phantomjs installed.
With node/npm
npm install -g phantomjs
Or, on ubuntu
apt-get install phantomjs