-
Notifications
You must be signed in to change notification settings - Fork 5
API Documentation
##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="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="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 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": "",
"expire_datetime": "2014-09-20 17:06:28.738967",
"answer4": "",
"answer7": "",
"top_left_lng": -77.9,
"answer1": "",
"answer0": "",
"answer3": "",
"answer2": "",
"answer5": "",
"answer6": "",
"top_left_lat": 43.4,
"question_type": 1,
"organization": "Yellr",
"publish_datetime": "2014-08-21 17:06:28.738960",
"bottom_right_lng": -77.3
}
],
"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": ""
}
]
}
###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
}
##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
}
###admin/create_question.json###
All admin api's require a token to be passed in. See get_access_token.json for more information.
admin/create_question.json?token=238236fa-0e1a-499c-8051-c46e2f416387
There are two parts of an assignment: the assignment itself, and the questions that go along with it. Yellr supports multiple questions to support multiple languages. The create_question.json is a HTTP POST event, and takes three mandatory fields.
language_code
The two letter language code for the question ('en', 'es', 'fr', etc.)
question_text
This is the text of the question, in whatever language is defined by the
language_code field
question_type
This is the type of question: free text, multiple choice, ect.
Examples: 'free_text', 'multiple_choice'
answers
Optionally you can include a field called answers. This field is a JSON array of
strings. This is used for questions types such as multiple choice. You are allowed
up to ten options. You do not need to specify all ten if they are not used.
A valid response will include a success field, and a question_id field. This ID is used with the publish_assignment.json api to link questions to assignments.
{
"success": true
"question_id": 5
}
There are two different errors that can come back:
{
"error_text": "Missing 'token' field in request.",
"success": false
}
{
"error_text": "One or more of the following fields is missing or invalid:
language_code, question_text, question_type. ",
"success": false
}
###admin/publish_assignment.json###
All admin api's require a token to be passed in. See get_access_token.json for more information.
admin/publish_assignment.json?token=238236fa-0e1a-499c-8051-c46e2f416387
This call is an HTTP POST API. The command takes two fields:
life_time
This is a non-zero integer that represents the number of hours the assignment should live for.
questions
This is a JSON array of question ids that are associated with the assignment.
note: see admin/create_question.json for more information on question ids.
top_left_lat
The top left latitude of the geo fence bounding box for the assignment in degrees.
top_left_lng
The top left longitude of the geo fence bounding box for the assignment in degrees.
bottom_right_lat
The bottom right latitude of the geo fence bounding box for the assignment in degrees.
bottom_right_lng
The bottom right longitude of the geo fence bounding box for the assignment in degrees.
Note: set the bounding box to these values for 'the whole earth':
top_left_lat: 90
top_left_lng: -180
bottom_right_lat: -90
bottom_right_lng: 180
Note: set the bounding box to these values for 'Monroe County, NY':
top_left_lat: 43.4
top_left_lng: -77.9
bottom_right_lat: 43.0
bottom_right_lng: -77.3
A successful response looks like this:
{
"assignment_id": 4,
"success": true
}
Possible errors include:
{
"error_text": "One or more of the following fields is missing or invalid: life_time,questions (JSON list of question id's). ",
"success": false
}
###admin/create_message.json###
All admin api's require a token to be passed in. See get_access_token.json for more information.
admin/create_message.json?token=238236fa-0e1a-499c-8051-c46e2f416387
This call is an HTTP POST API. The command takes the following fields:
to_client_id
This is the client if of the user that you are sending the message to.
subject
This is free-form text that is the subject of the message.
text
This is the free-form text contents of the message.
[optional]
parent_message_id
If this is the first message of a chain, then you do not need to include this (and you shouldn't).
If this is a response to a message that a client sent back to an admin/mod/sub, then
this field needs to be included.
Responses:
{
"error_text": "Invalid auth token.",
"success": false
}
{
"error_text": "One or more of the following fields is missing or invalid: to_client_id, subject, text.\n",
"success": false
}
This can happen if you are trying to respond to the message twice
{
"success": false
}
This will be returned on a valid posting.
{
"message_id": 3,
"success": true
}
###admin/get_languages.json###
All admin api's require a token to be passed in. See get_access_token.json for more information.
admin/get_languages.json?token=238236fa-0e1a-499c-8051-c46e2f416387
This command returns the available languages the system supports. It is a HTTP GET request.
A response looks like:
{
"languages": [
{
"code": "en",
"name": "English"
},
{
"code": "sp",
"name": "Spanish"
}
],
"success": true
}
###admin/create_user.json###
All admin api's require a token to be passed in. See get_access_token.json for more information.
admin/create_user.json?token=238236fa-0e1a-499c-8051-c46e2f416387
This allows for creating new users. This is a HTTP POST request.
The following fields are required:
user_type
This is the type of the user. Valid values are: admin, moderator, subscriber, user
user_name
This is a username that is used to login with.
password
The password for the username. There are no restrictions to this field.
first_name
First name of the user.
last_name
Last name of the user.
email
The email address of the user.
organization
The organization the user belongs to.
A response looks like:
{
"user_id": 3,
"success": true
}
###admin/get_assignment_responses.json###
All admin api's require a token to be passed in. See get_access_token.json for more information.
admin/get_assignment_responses.json?token=238236fa-0e1a-499c-8051-c46e2f416387&assignment_id=<assignment_id>&start=<start_post_index>&count=<post_count>
This is returns all of the posts associated with an assignment. It is a HTTP GET request, and takes the following fields:
assignment_id
This is the id within the database of the assignment.
[ OPTIONAL ]
start
This is the post index to start the response from. This is useful for paging.
[ OPTIONAL ]
count
This can be used to limit the number of posts that are returned. This is useful for paging.
Note: that the media_objects array will hold all of the media objects associated with the post.
Note: the response is a dictionary of posts, not an array. This was done to speed up response time, and reduce load on the web server so multiple loops did not have to run. Here is the reference to how to iterate though the dictionary in javascript:
Note: the keys will be the post id's within the database, and may not go in order (assume they will not), and thus should not be used as an index.
This is what a valid response looks like.
{
"post_count": 1,
"posts": {
"1": {
"reported": false,
"verified_user": true,
"post_id": 1,
"client_id": "ae6aff13-21d1-4fac-99c4-2bb7ef5992eb",
"language_code": "en",
"lat": 43,
"lng": -77.5,
"post_datetime": "2014-08-22 13:32:35.000678",
"media_objects": [
{
"media_id": "d006f262-137f-4522-930d-e35fc0a37f91",
"file_name": "",
"media_text": "This is my post!",
"caption": "",
"media_type_description": "Text.",
"media_type_name": "text"
}
],
"user_id": 2,
"title": "My Post!",
"assignment_id": 1,
"language_name": "English"
}
},
"success": true
}