Kinglet API
Each function is preceded with @/api/v1@.
h2. Users
Except for activating a user account, URIs for GETs and PUTs end with a query string:
/?user_name=[user_name]&user_id=[user_id]&session_id=[session_id
retrieve profile page info for user name JR.
@GET /users/JR@
create a new user account.
@POST /users@
activate user account.
@GET /users/activate/[user_digest]@
logout user JR.
@GET /users/JR/logout@
login user.
@POST /users/login@
retrieve new password for existing account. user would not be logged in. this would be executed for someone who forgot or lost password.
@POST /users/password@
change password for existing account. user must be logged-in.
@PUT /users/password@
update e-mail and/or profile description for the user.
@PUT /users@
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. Lists
In order for User A to message User B, User A needs to be added to User B's approved list of user for messaging. When User A makes the request to User B, then User B is automatically added to User A's approved list. User A must wait for User B to approve or reject the request.
URIs for GETs end with a query string:
/?user_name=[user_name]&user_id=[user_id]&session_id=[session_id
request to be added to a recipient's approved list of users. the logged-in user sends a request to user mrx.
@GET /lists/request/mrx@
reject the request from user JR to be added to the logged-in user's approved list of users.
@GET /lists/reject/JR@
approve the request from user JR.
@GET /lists/approve/JR@
logged-in user can show the list of requests received, so that the user can change the reject/approve status.
@GET /lists/requests@
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/JR/23/ru8er03jjg3k40vjl09@
homepage. stream. messages created by or sent to the logged in user.
@GET /messages@
page three of the stream.
@GET /messages/page/3@
for the logged-in user, get all new messages received since the supplied date, which is in epoch seconds.
@GET /messages/since/[date]@
retrieve message 5.
@GET /messages/5@
create a new message.
@POST /messages@
retrieve all reply messages for message 5.
@GET /messages/5/replies@
create a reply message to message 5.
@POST /messages/5/replies@
list the messages that start new discussions.
@GET /messages/threads@
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
#todo - show all error messages
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" : 204,
"description" : "No Content",
"activate_account" : "true"
}
code..
h3. Log In
code.{
"status" : 200,
"description" : "OK",
"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" : 204,
"description" : "No Content",
"profile_updated" : "true"
}
code..
h3. Successfully Displayed User Profile Page
#todo - for display to other users or logged-in user?
code.{
"desc_markup" : "this is my boring profile page.",
"status" : 200,
"description" : "OK",
"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,
"description" : "OK",
"new_password" : "7rqqawh8"
}
code..
h3. Successfully Logged Out
code.{
"status" : 204,
"description" : "No Content",
"logged_out" : "true"
}
code..
h3. Successfully Submitted Approved List Request
code.{
"status" : 204,
"description" : "No Content",
"made_request" : "true"
}
code..
h3. Re-submitting the Same Approved List Request
code.{
"status" : 400,
"request_status" : "pending",
"system_message" : "Request is pending approval by the recipient.",
"user_message" : "Request made earlier.",
"description" : "Bad Request"
}
code..
h3. Re-submitting the Same Approved List Request After Being Rejected
code.{
"status" : 400,
"request_status" : "rejected",
"system_message" : "Recipient has already rejected the requester.",
"user_message" : "Request made earlier.",
"description" : "Bad Request"
}
code..
h3. Re-submitting the Same Approved List Request After Being Approved
code.{
"status" : 400,
"request_status" : "approved",
"system_message" : "Recipient has already approved the requester.",
"user_message" : "Request made earlier.",
"description" : "Bad Request"
}
code..
h3. Approving or Rejecting a Request
code.{
"status":200,
"description":"OK"
}
code..
h3. List of Approval Requests Received
code.{
"status":200,
"requests":
[
{
"status":"approved",
"created_date":"Feb 12, 2014",
"user_name":"testuser1"
},
{
"status":"rejected",
"created_date":"Feb 25, 2014",
"user_name":"testuserA"
},
{
"status":"rejected",
"created_date":"Feb 25, 2014",
"user_name":"testuserB"
},
{
"status":"rejected",
"created_date":"Feb 25, 2014",
"user_name":"testuserC"
}
],
"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
#kinglettodo should this be available only to logged-in users?
code.{
"status" : 200,
"server_epoch_seconds" : 1389992757,
"description" : "OK"
}
code..
toc=no
#kinglet - #api - #programming