-
Notifications
You must be signed in to change notification settings - Fork 5
Client API Documentation
#DEPRECATED DO NOT USE!!!!!!! THIS PAGE WILL SOON BE DELETED!!!!#
##API Documentation v0.1##
###server_info.json###
NOTE: DEPRECATED - DO NOT USE
Returns information about the version of the server, and the required version of the client software. This is a HTTP GET end point.
Field Descriptions:
- none -
A response looks like this:
{
"server_version": "0.0.1",
"success": true,
"required_client_version": "0.0.1"
}
###upload_media.json###
The upload_media.json end point allows for the client to upload a media object of text, image, audio, or video. Multiple media objects can be associated with a post. This is an HTTP POST end point.
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.
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###
The publish_post.json end point allows the client to publish a post to the server with any number of media objects associated with it. This is an HTTP POST end point.
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 assignment id the post is responding to. This field will hold
the assignment id that the post is responding to. If this is a free-post (not associated with an
assignment) then set this to "0".
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 [NOTE: DEPRECATED - DO NOT USE]
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###
The get_assignments.json end point will return all assignments that have geo fences that include the current lat/lng of the user. This is a HTTP GET end point.
get_assignments.json?client_id=<client_id>&language_code=<language_code>&lat=<lat>&lng=<lng>
The input fields are:
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.
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_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
}
###get_notifications.json###
The get_notifications.json end-point gets all notifications for the user. This is an HTTP GET end point.
get_notifications.json?client_id=19ce6abd-d4c1-4d89-a87c-73a21bd56ab3
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.
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 gets any messages the user may have waiting for them. This includes response messages. This is an HTTP GET end point;
/get_messages.json?client_id=e7a784c4-bda4-4ccd-9c86-01e9facb47f5
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.
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
}
Response 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,
"post_view_count": 0,
"organization": "",
"post_used_count": 0,
"email": ""
}
For unverified users, first_name, last_name, organization, and email will be "". post_count, post_view_count, and post_used_count will always be a real number greater or equal to 0.
post_view_count
This represents the number of posts that a moderator/subscriber have viewed of the users
post_used_count
This represents the number of posts that have been used in a story by a moderator/subscriber.
###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
}
###verify_user.json###
This end point is used when a client wants to become 'verified' within the yellr system. This matches a name and email address with the client id. This is a HTTP POST end point.
The following fields are required:
client_id
This is the UUID of the account that will be set to verified, with the paired name and email address.
username
This is a unique username the user uses to login with
password
This is the sha256 of the users password.
first_name
The users first name
last_name
The users last name
email [optional]
The users email address
A response looks like:
{
"verfied_user_id": 33,
"success": true
}
An error would look like:
{
"error_text": "Username, email, and/or client ID already registered",
"success": false
}