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="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_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": ""
        }
    ]
}