-
Notifications
You must be signed in to change notification settings - Fork 5
API Documentation
Timothy Duffy edited this page Aug 15, 2014
·
60 revisions
##API Documentation v0.1##
###upload_media.json###
HTTP POST:
<form action="/upload_media.json" method="post" accept-charset="utf-8" enctype="multipart/form-data">
<input id="client_id" name="client_id" type="text" value="<client_id>" />
<input id="media_type" name="media_type" type="text" value="<media_type>">
<input id="media_file" name="media_file" type="file" value="<file_name>" /> <!-- optional -->
<input id="media_text" name="media_text" type="text" value=""> <!-- optional -->
<input id="media_caption" name="media_caption" type="text" value=""> <!-- optional -->
<input type="submit" value="submit" />
</form>
Field Descriptions:
clientid:
This is of type text, and is the unique id of the client. This is a uuid that is generated by the
client and is associated with a user within the database. Event if a user is 'validated' their
unique client_id is still used to identify them.
media_type:
This field holds the type of the media. Valid types include:
text - a text post. there is no limit on it's length.
audio - an audio recording (should be in mp3 format)
video - a video recording (should be in mpg format)
image - an image (should be in jpg format)
If a media_type of 'text' is used, then the media_text field must contain a non-zero length string. If
any other media_type is used, then the media_file field must contain file data. Not following these
rules will produce a { "success": false } response.
media_file:
This is of type file, and will be the media object that is being uploaded. This is an optional field,
but the media_type filed must be 'text' if this is not included, else { "success": false } will be
returned.
media_text
This is of type text, and will hold the text of the media post. This is an optional field, but the
media_type field must be 'audio', 'video', or 'image' if this is not include, else a
{ "success": false } will be returned.
media_caption
This is of type text, and will hold an additional description of the media type. This is an optional
and does not need to be included.
Response:
Successful upload:
{
media_id: "0be05edf-3489-4037-bd00-d6af3baee8b9"
success: true
new_user: false
file_name: "b75aa8b5-5e0b-46ad-9344-f74da0d54fee.jpg"
media_text: ""
error_text: ""
}
Unsuccessful upload:
{
"success": false,
"error_text": "<some error text>"
}
Once a successful response is issued, you can navigate to the media object:
http://<domain>/media/<file_name>
###publish_post.json###
HTTP Post:
<form action="/publish_post.json" method="post" accept-charset="utf-8" enctype="multipart/form-data">
<input id="client_id" name="client_id" type="text" value="{0}">
<input id="assignment_id" name="assignment_id" type="text" value="{0}">
<input id="language_code" name="language_code" type="text" value="en">
<input id="location" name="location" type="text" value="{'lat': 44, 'lng': -77}">
<input id="media_objects" name="media_objects" type="text" value="{'<uuid>','<uuid>', etc.}">
<input type="submit" value="submit" />
</form>
Field Descriptions:
client_id:
This is of type text, and is the unique id of the client. This is a uuid that is generated by the
client and is associated with a user within the database. Event if a user is 'validated' their
unique client_id is still used to identify them.
assignment_id:
This is of type text, and holds the optional assignment id the post is responding to. Since user
posts can be responses to assignments, this field will hold the assignment id that the post is
responding to.
language_code:
This is of type text, and holds the two letter language code the post is in. Language codes must
match those codes that exist within the languages table within the database. Valid values currently
are:
en - English
es - Español
Note: If responding to an assignment, the response post should have the same language code as the
question being asked.
location:
This is of type text, and is a json object that holds the latitude and longitude of the user making
the post. The json dictionary has the flowing keys:
{
"lat": 43.1656,
"lng": -77.6114
}
Both keys must be present, and be valid latitude/longitude values.
media_objects:
This is of type text, and is a json object that holds an array of mediaobject id's. The json array
looks like this:
[
"4ebbb6c0-bd4c-43fc-8242-5aec49989f61",
"b71d403b-caf1-470c-ad29-51229526fe1e"
]
The supplied id's must be associated with valid mediaobject uploads, and should only come from the
upload_media.json response json dictionary.
###get_assignments.json###
This will return all of the available assignments. This is subject to change based on geo fencing.
{
"assignments": [
{
"question_text": "How do you feel about broccoli?",
"answer9": "",
"answer8": "",
"fence": "{}",
"expire_datetime": "2014-08-30 14:09:19.656411",
"answer4": "",
"answer7": "",
"answer6": "",
"answer1": "",
"answer0": "",
"answer3": "",
"answer2": "",
"answer5": "",
"question_type": "free_text",
"organization": "Yellr",
"publish_datetime": "2014-07-31 14:09:19.656403"
}
],
"success": true
}
###get_notifications.json###
The get_notifications.json end-point only takes a single parameter in the HTTP GET, and that is client_id:
get_notifications.json?client_id=19ce6abd-d4c1-4d89-a87c-73a21bd56ab3
Response example:
{
"notifications": [
{
"notification_id": 2,
"notification_type": "new_message",
"notification_datetime": "2014-07-30 17:22:49.724056",
"payload": {
"organization": "Yellr"
}
}
],
"success": true
}
The resulting json dict will have an array of notifications called 'notifications'. Note that this list will never be more than 25 items long. It includes the 'notification_id' of the notification. It is the clients responsibility to keep track of which notifications have, and have not been 'seen'.
The 'notification_type' field can have the following values, paired with their respective payload values:
post_successful
payload = {
'post_id': 0, # the ID within the database of the post (probably not useful to client)
'title': '', # the title of the post that was sent (could be used for display purposes)
}
post_viewed
payload = {
'organization': '', # organization that viewed the post
}
new_message
payload = {
'organization': '', # organization the person who viewed the post belongs to
}
message_sent
payload = {
'message_subject': '' # the subject of the message that was sent
}
###get_messages.json###
The get_messages.json route is a GET method, and requires a single parameter: client_id. An example a request looks like:
/get_messages.json?client_id=e7a784c4-bda4-4ccd-9c86-01e9facb47f5
An example response looks like:
{
"messages": [
{
"message_datetime": "2014-07-10 15:52:41.388892",
"parent_message_id": null,
"text": "Congratulations, you are now apart of Yellr! You can start posting content right away!",
"from_organization": null,
"from_user_id": null,
"to_user_id": 1,
"subject": "Welcome to Yellr!"
}
],
"success": true
}
Field Descriptions:
message_datetime:
This is the date and time the message was created.
parent_message_id:
This holds the parent message id. If the message is apart of a chain of correspondence, this will be
the message the sender is responding to. If the field is null, then it is an original, and the first
of a correspondence chain.
text:
This is the body text of the message.
from_organization:
The display organization that the message is from. If this field is null it is a system message.
from_user_id:
This is the ID of the user that sent the message. If it is null then it is a system message.
to_user_id:
This is the ID of the client user.
subject:
This is the subject field for the message. This is usually a brief description or theme of the
message body.
###client_logs.json###
NOTE: This is for debug purposes only, and will be removed in production code. Calling client_logs.json will produce a json object will logs of events within the system. Here is an example response:
[
{
"event_log_id": 1,
"user_id": 1,
"event_type": "http_request",
"event_datetime": "2014-07-10 13:39:15.492121",
"details": {
"date_time": "2014-07-10 13:39:15",
"media_id": "b94d18c7-b628-4c95-b6eb-6c83c4e360db",
"success": true,
"media_caption": "",
"new_user": true,
"file_name": "",
"media_text": "",
"url": "upload_media.json",
"client_id": "19ce6abd-d4c1-4d89-a87c-73a21bd56ab3",
"media_type": "text"
}
},
{
"event_log_id": 2,
"user_id": 1,
"event_type": "new_user_created",
"event_datetime": "2014-07-10 13:39:15.511134",
"details": {
"method": "upload_media.json",
"client_id": "19ce6abd-d4c1-4d89-a87c-73a21bd56ab3"
}
},
{
"event_log_id": 3,
"user_id": 1,
"event_type": "http_request",
"event_datetime": "2014-07-10 13:39:24.132955",
"details": {
"media_objects": [
"b94d18c7-b628-4c95-b6eb-6c83c4e360db"
],
"pos_id": 1,
"success": true,
"new_user": false,
"assignment_id": "19ce6abd-d4c1-4d89-a87c-73a21bd56ab3",
"datetime": "2014-07-10 13:39:24",
"url": "publish_post.json",
"location": {
"lat": 44,
"lng": -77
},
"client_id": "19ce6abd-d4c1-4d89-a87c-73a21bd56ab3",
"language_code": "en"
}
}
]
###get_posts.json###
Returns a list of all known posts within the system. Note: this will eventually be behind a login.
{
"success": true,
"posts": [
{
"last_name": "",
"language_name": "English",
"post_id": 1,
"language_code": "en",
"lat": 44,
"user_id": "12345678",
"lng": -77,
"post_datetime": "2014-07-22 15:13:46.565763",
"media_objects": [
{
"file_name": "",
"description": "Text.",
"media_text": "desription thing",
"name": "text",
"caption": ""
}
],
"first_name": "",
"verified": false,
"reported": false,
"organization": ""
}
]
}
##Admin APIs##
###admin/get_access_token.json###
This gets an access token that needs to be passed around with all admin api calls.
admin/get_access_token.json?user_name=<user_name>&password=<password>
Response:
{
"success": true,
"token": "34ff0a2f-b8e1-45be-ac00-97dadb04baad"
}
Possible error messages include:
Bad credentials:
{
"success": false,
"error_text": "Invalid credentials"
}
Missing fields:
{
"success": false,
"error_text": "Missing 'username' or 'password' within request"
}
###admin/get_posts.json###
As an admin, you can get posts that are ordered in descending order (newest first).
admin/get_posts.json?start=<start_index>&count=<count>
There are two optional fields:
start
Start allows you to set a starting index for the responses. This is useful for paging.
Note: If start is not specified, then it defaults to 0.
count
Count allows you to set the number of responses to return. This is useful for paging.
Note: If count is not specified, then it defaults to 50.
Note: within the response there is the 'total_post_count' field. This is the total number of posts within the database. This is useful for paging.
Example response:
{
"total_post_count": 2,
"posts": [
{
"last_name": "",
"datetime": "2014-08-15 15:13:22.006679",
"reported": false,
"client_id": "1234567890",
"verified_user": false,
"lat": 42,
"lng": -77,
"media_objects": [
{
"file_name": "",
"media_text": "This is some text for my post",
"media_type": "text",
"media_description": "Text.",
"caption": ""
}
],
"first_name": "",
"title": "Test Post",
"organization": ""
},
{
"last_name": "",
"datetime": "2014-08-15 14:51:14.555236",
"reported": false,
"client_id": "1234567890",
"verified_user": false,
"lat": 42,
"lng": -77,
"media_objects": [],
"first_name": "",
"title": "Test Post",
"organization": ""
}
],
"success": true
}
There are two different errors that can come back:
{
"error_text": "Invalid auth token.",
"success": false
}
{
"error_text": "Missing 'token' field in request.",
"success": false
}