Kinglet API
Each function is preceded with @/api/v1@.
h2. Users
# = URIs for GETs and PUTs end with a query string:
/?user_name=[user_name]&user_id=[user_id]&session_id=[session_id
retrieve user info for user name JR
@GET /users/JR@
create a new user account
@POST /users@
@GET /users/activate/[user_digest]@ - activate user account
@GET /users/JR/logout@ - logout user JR. #
@POST /users/login@ - login user.
@POST /users/password@ - retrieve new password for existing account. user would not be logged in. this would be executed for someone who forgot or lost password.
@PUT /users/password@ - change password for existing account. user must be logged-in. #
@PUT /users@ - update e-mail and/or profile description for the user #
h3. User actions
* create account
* activate account
* login
* change password
* change e-mail and profile description
* retrieve user profile info
* request new password
* logout
h2. Messages
Each URI ends with a query string @/?user_name=[user_name]&user_id=[user_id]&session_id=[session_id@.
example displaying message number 5:
@GET /api/v1/messages/5/ru8er03jjg3k40vjl09/23/JR@
@GET /messages@ - homepage. stream. messages created by or sent to the logged in user.
@GET /messages/page/3@ - page three of the stream.
@GET /messages/since/[date]@ - for the logged-in user, get all new messages received since the supplied date, which is in epoch seconds.
*@GET /messages/5@ - retrieve message 5.
@POST /messages@ - create a new message.
@GET /messages/5/replies@ - retrieve all reply messages for message 5.
@POST /messages/5/replies@ - create a reply message to message 5.
@GET /messages/threads@ - list the messages that start new discussions.
h3. Message actions
* create a new message
* get single message
* create a reply to a particular message
* retrieve all replies for a message
* get user's stream of all messages (sent and received)
* get user's new messages received since supplied date
** _need to create a 2nd user account for testing_
* list the new messages that start a discussion thread
h2. Test script order
* create account
* activate account
* login
* create a new message
* get single message
* create a reply to a particular message
* retrieve all replies for a message
* get user's stream of all messages (sent and received)
* get user's new messages received since supplied date
* list the new messages that start a discussion thread
* make
* change password
* change e-mail and profile description
* retrieve user profile info
* request new password
* logout
* get server time
h2. Returned JSON
h3. Create New User Account
code.{
"status" : 201,
"user_id" : "9",
"user_name" : "1389906958",
"password" : "khd7vj4m",
"email" : "1389906958@test.com",
"user_digest" : "p7X4CwwLSuqD2bjYIATcw",
"description" : "Created"
}
code..
h3. Activate Account
code.{
"status" : 200,
"description" : "OK"
}
code..
h3. Log In
code.{
"status" : 200,
"user_id" : "17",
"user_name" : "kinglettest1389911089",
"session_id" : "LUb83Dw38nnqMOI47NVZw"
}
code..
h3. Successfully Change Password
code.{
"session_id" : "3Ms41qwZfjuHW2kUmNeOg",
"status" : 200,
"user_id" : "20",
"user_name" : "kinglettest1389912835"
}
code..
h3. Unsuccessfully Changed Password
code.{
"status" : 400,
"description" : "Bad Request",
"user_message" : "Old password is incorrect.",
"system_message" : "Try again. oldpwd=ykboQdwz7h0qXrPoUJKGaw - pwd=9gz3Ijf8GhCdFCqsma+dvw - olddig=AVQk3qoFBzn2yrbEIVVA - digest=5BYzikIRrokcaEQmGIeSA"
}
code..
h3. Successfully Updated User Profile Page
code.{
"status" : 200
}
code..
h3. Successfully Displayed User Profile Page
code.{
"desc_markup" : "this is my boring profile page.",
"status" : 200,
"created_date" : "Jan 16, 2014",
"user_name" : "kinglettest1389915584",
"email" : "kinglettest1389915584@testnew.com",
"user_status" : "o",
"user_id" : "21",
"digest" : "q5JUMA9YC2GgkMwb8s19Mg",
"desc_format" : "this is my boring profile page."
}
code..
h3. Unsuccessfully Retrieved New Password
code.{
"status" : "404",
"description" : "Not Found",
"user_message" : "Invalid input.",
"system_message" : "Username and/or e-mail does not exist."
}
code..
h3. Successfully Retrieved New Password
code.{
"email" : "kinglettest1389921202@test.com",
"status" : 200,
"new_password" : "7rqqawh8"
}
code..
h3. Successfully Logged Out
code.{
"status" : 200,
"description" : "OK"
}
code..
h3. Successfully Created a New Message
code.{
"message_id" : "35",
"status" : 201,
"description" : "Created"
}
code..
h3. Successfully Read a Message
code.{
"content_digest" : "yGK8VYhKj5dJV7AhJMNP9Q",
"author_name" : "kinglettest1389981418",
"author_id" : "32",
"message_id" : "36",
"status" : 200,
"created_date" : "Jan 17, 2014 at 06:03:54 PM",
"message_status" : "o",
"description" : "OK",
"recipient_names" : "|kinglettest1389981418|",
"parent_id" : "0",
"reply_count" : "0",
"message_text" : "@kinglettest1389981418 sending a messsage to myself."
}
code..
h3. Successfully Added Reply Message
code.{
"message_id" : "37",
"status" : 201,
"description" : "Created"
}
code..
h3. Successfully Retrieving All Replies
code.{
"messages":
[
{
"author_name" :"kinglettest1389981418",
"message_id" : "37",
"message_status" : "o",
"created_date" : "1 hr ago",
"parent_id" : "36",
"recipient_names" : "kinglettest1389981418",
"author_type" : "you",
"logged_in_user" : "32",
"message_text" : "This is a reply message.","reply_count":"0"
}
],
"status" : 200,
"description" : "OK",
"next_link_bool" : 0
}
code..
h3. Successfully Retrieved All of a User's Messages, Sent and Received
code.{
"messages"
[
{
"author_name" : "kinglettest1389981418",
"message_id" : "37",
"message_status" : "o",
"created_date" : "1 hr ago",
"parent_id" : "36",
"recipient_names" : "kinglettest1389981418",
"author_type" : "you",
"logged_in_user" : "32",
"message_text" : "This is a reply message.",
"reply_count" : "0"
},
{
"author_name" : "kinglettest1389981418",
"message_id" : "36",
"message_status" : "o",
"created_date" : "2 hrs ago",
"parent_id" : "0",
"recipient_names" : "kinglettest1389981418",
"logged_in_user" : "32",
"author_type" : "you",
"message_text" : "@kinglettest1389981418 sending a messsage to myself.",
"reply_count" : "1"
}
],
"status" : 200,
"description" : "OK",
"next_link_bool" : 0
}
code..
h3. No New Messages Received Since a Specified Date
code.{
"new_message_count" : 0,
"status" : 200,
"description" : "OK"
}
code..
h3. Successfully retrieved all new messages that start new discussions threads involving the user
code.{
"status" : 200,
"description" : "OK",
"threads" :
[
{
"author_name" : "kinglettest1389981418",
"last_message_date" : "2 hrs ago",
"message_id" : "36",
"created_date" : "2 hrs ago",
"last_message_id" : "37",
"recipient_names" : "kinglettest1389981418",
"logged_in_user" : "32",
"message_text" : "sending a messsage to myself.",
"last_message_author_name" : "kinglettest1389981418",
"reply_count" : "1"
}
]
}
code..
h3. Retrieved Server Time
#juncotodo should this be available only to logged-in users?
code.{
"status" : 200,
"server_epoch_seconds" : 1389992757,
"description" : "OK"
}
code..
toc=no
#kinglet - #api - #programming