-
Notifications
You must be signed in to change notification settings - Fork 5
API Documentation
Timothy Duffy edited this page Feb 4, 2015
·
60 revisions
##API Documentation v0.1##
###server_info.json###
Returns information about the version of the server, and the required version of the client software.
A response looks like this:
{
"server_version": "0.0.1",
"success": true,
"required_client_version": "0.0.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="clienFt_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="title" name="title" type="text" value="{0}">
<input id="language_code" name="language_code" type="text" value="en">
<input id="lat" name="location" type="text" value="44">
<input id="lng" name="location" type="text" value="-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.
title
The title of the post.
lat:
This is the latitude of the user. 43.1656 is an example.
lng
This is the longitude of the user. -77.6114 is an example.
media_objects:
This is of type text, and is a json object that holds an array of media_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.
A valid response looks like:
{
"new_user": false,
"post_id": 1,
"success": true
}
###get_assignments.json###
This is a HTTP GET api. This will return all of the available assignments. This is subject to change based on geo fencing.
get_assignments.json?client_id=<client_id>&language_code=<language_code>&lat=<lat>&lng=<lng>
The input fields are:
client_id
This is the unique GUID from the client
language_code
This is the two letter language code ('en', 'es', 'fr', etc.)
lat
This is the users current latitude in degrees
lng
This is the users current longitude in degrees
A valid response looks like:
{
"assignments": [
{
"bottom_right_lat": -77.3,
"question_text": "How do you feel about broccoli?",
"answer9": "",
"answer8": "",
"assignment_id": 1,
"answer4": "",
"answer7": "",
"top_left_lng": -77.9,
"answer1": "",
"answer0": "",
"answer3": "",
"answer2": "",
"expire_datetime": "2014-09-21 16:03:11.435792",
"description": "Tell me how you really feel about broccoli. Be as detailed as you want!",
"answer6": "",
"top_left_lat": 43.4,
"question_type_id": 1,
"organization": "Yellr",
"answer5": "",
"publish_datetime": "2014-08-22 16:03:11.435785",
"bottom_right_lng": -77.3,
"post_count": 14
}
],
"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!"
"message_id": 2,
}
],
"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.
###get_profile.json###
Returns information about the user.
HTTP GET
/get_profile.json?client_id=e7a784c4-bda4-4ccd-9c86-01e9facb47f5
Valid response looks like:
{
"first_name": "",
"last_name": "",
"verified": false,
"success": true,
"post_count": 1,
"posts": {
"1": {
"reported": false,
"verified_user": true,
"post_id": 1,
"client_id": "dbab0fc0-0771-47c2-b252-ccb3e7dcb4d9",
"language_code": "en",
"lat": 43.1,
"lng": -77.5,
"post_datetime": "2014-09-08 22:26:15.833802",
"media_objects": [
{
"media_id": "2791ebcc-42ca-40e8-b012-bb1d46571ce8",
"file_name": "b97b91cc-0a3e-4ae9-98e1-d440f7cc07b4.jpg",
"media_text": "",
"caption": "",
"media_type_description": "An Image.",
"media_type_name": "image"
}
],
"user_id": 7,
"title": "My post!",
"assignment_id": 6,
"language_name": "English"
}
},
"organization": "",
"email": ""
}
###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": ""
}
]
}
###create_response_message.json###
This API is used to respond to a message sent by an admin/mod/sub.
create_response_message?client_id=<client_id>&subject=<subject>&text=<text>&parent_message_id=<parent_message_id>
This call is an HTTP POST API. The command takes the following fields:
client_id
The client id that must correspond to the user that the message was sent to.
subject
The free-form text that is the subject of the message (can be unique from the parent message)
text
The free-from text that is the body of the message.
parent_message_id
This is the message if of the parent message. This is included in the response form
get_messages.json.
Valid responses:
{
"error_text": "One or more of the following fields is missing or invalid: client_id, parent_message_id, :subject, text.",
"success": false
}
{
"error_text": "Message already has posted response.",
"success": false
}
{
"message_id": 6,
"success": true
}
###get_stories.json###
This end point allows users to get the current stories that your location is showing.
get_stories.json?client_id=<client_id>&lat=<lat>&lng=<lng>&language_code=<language_code>
There are four required fields:
client_id
the unique id for the user making the request
lat
The current latitude of the user in degrees.
lng
The current longitude of the user in degrees.
language_code
The language code of the stories you would like.
Note: if this is left blank, language will be ignored, and all languages will be returned.
A valid response looks like this:
{
"total_story_count": 1,
"stories": [
{
"bottom_right_lat": 43,
"top_text": "",
"author_last_name": "SYSTEM USER",
"top_left_lng": -77.9,
"banner_media_file_name": "dea9d50a-d6ec-4f39-9d8e-3a4a5d21e618.jpg",
"author_first_name": "SYSTEM USER",
"title": "My Story!",
"bottom_right_lng": -77.3,
"story_unique_id": "194e2157-dd3c-4cba-bcc6-49a360c8fde0",
"tags": "first, story, fresh",
"author_organization": "Yellr",
"banner_media_id": "25b0910f-480e-4add-bd41-194b502c71a8",
"author_email": "",
"top_left_lat": 43.4,
"edited_datetime": "None",
"publish_datetime": "2014-08-22 16:03:37.450331",
"contents": "... the <b>story</b>!"
}
],
"success": true
}