You're viewing old version number 123. - Current version
Kinglet API
Each function is preceded with /api/v1.
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
User actions
- create account
- activate account
- login
- change password
- change e-mail and profile description
- retrieve user profile info
- request new password
- logout
Lists
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 for user JR to be added to - GET - /lists/reject/jr - reject request from user jr.
approve - the request - GET - /lists/approve/jr - approve the request from user jr.
show - the list of requests of requests received so that a user can change the reject/approve function - GET - /lists/requests - requests received
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
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
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
Returned JSON
Create New User Account
{
"status" : 201,
"user_id" : "9",
"user_name" : "1389906958",
"password" : "khd7vj4m",
"email" : "1389906958@test.com",
"user_digest" : "p7X4CwwLSuqD2bjYIATcw",
"description" : "Created"
}
Activate Account
{
"status" : 200,
"description" : "OK"
}
Log In
{
"status" : 200,
"user_id" : "17",
"user_name" : "kinglettest1389911089",
"session_id" : "LUb83Dw38nnqMOI47NVZw"
}
Successfully Change Password
{
"session_id" : "3Ms41qwZfjuHW2kUmNeOg",
"status" : 200,
"user_id" : "20",
"user_name" : "kinglettest1389912835"
}
Unsuccessfully Changed Password
{
"status" : 400,
"description" : "Bad Request",
"user_message" : "Old password is incorrect.",
"system_message" : "Try again. oldpwd=ykboQdwz7h0qXrPoUJKGaw - pwd=9gz3Ijf8GhCdFCqsma+dvw - olddig=AVQk3qoFBzn2yrbEIVVA - digest=5BYzikIRrokcaEQmGIeSA"
}
Successfully Updated User Profile Page
{
"status" : 200
}
Successfully Displayed User Profile Page
{
"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."
}
Unsuccessfully Retrieved New Password
{
"status" : "404",
"description" : "Not Found",
"user_message" : "Invalid input.",
"system_message" : "Username and/or e-mail does not exist."
}
Successfully Retrieved New Password
{
"email" : "kinglettest1389921202@test.com",
"status" : 200,
"new_password" : "7rqqawh8"
}
Successfully Logged Out
{
"status" : 200,
"description" : "OK"
}
Successfully Created a New Message
{
"message_id" : "35",
"status" : 201,
"description" : "Created"
}
Successfully Read a Message
{
"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" : "<a href=\"/user/kinglettest1389981418\">@kinglettest1389981418</a> sending a messsage to myself."
}
Successfully Added Reply Message
{
"message_id" : "37",
"status" : 201,
"description" : "Created"
}
Successfully Retrieving All Replies
{
"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
}
Successfully Retrieved All of a User's Messages, Sent and Received
{
"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" : "<a href=\"/user/kinglettest1389981418\">@kinglettest1389981418</a> sending a messsage to myself.",
"reply_count" : "1"
}
],
"status" : 200,
"description" : "OK",
"next_link_bool" : 0
}
No New Messages Received Since a Specified Date
{
"new_message_count" : 0,
"status" : 200,
"description" : "OK"
}
Successfully retrieved all new messages that start new discussions threads involving the user
{
"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"
}
]
}
Retrieved Server Time
#kinglettodo should this be available only to logged-in users?
{
"status" : 200,
"server_epoch_seconds" : 1389992757,
"description" : "OK"
}
#kinglet - #api - #programming
From JR's : articles
990 words - 8554 chars
- 5 min read
created on
updated on
- #
source
- versions
Related articles
Kinglet API - Mar 07, 2014
Short list of REST API info - Jan 13, 2017
Yo-Perl Readme - Aug 19, 2014
Programming Things To-Do - Apr 01, 2014
Pebble watch development - Aug 21, 2014
more >>