You're viewing old version number 140. - Current version

6 min

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

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

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"           :  204,
    "description"      :  "No Content",
    "activate_account" : "true"
}

Log In

{
    "status"      :  200,
    "description" :  "OK",
    "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"           :  204,
    "description"      : "No Content",
    "profile_updated"  : "true"
}

Successfully Displayed User Profile Page
#todo - for display to other users or logged-in user?

{
    "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."
}

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 Submitted Approved List Request

{
    "status"       :  200,
    "description"  :  "OK"
}

Re-submitting the Same Approved List Request

{
    "status"          :  400,
    "request_status"  :  "pending",
    "system_message"  :  "Request is pending approval by the recipient.",
    "user_message"    :  "Request made earlier.",
    "description"     :  "Bad Request"
}

Re-submitting the Same Approved List Request After Being Rejected

{
    "status"          :  400,
    "request_status"  :  "rejected",
    "system_message"  :  "Recipient has already rejected the requester.",
    "user_message"    :  "Request made earlier.",
    "description"     :  "Bad Request"
}

Re-submitting the Same Approved List Request After Being Approved

{
            "status"  :  400,
    "request_status"  :  "approved",
    "system_message"  :  "Recipient has already approved the requester.",
      "user_message"  :  "Request made earlier.",
       "description"  :  "Bad Request"
}

Approving or Rejecting a Request

{
    "status":200,
    "description":"OK"
}

List of Approval Requests Received

{
    "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"
}

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
1231 words - 10761 chars - 6 min read
created on
updated on - #
source - versions

Related articles
Kinglet API - Mar 07, 2014
Forecast.io becomes darksky.net in sep 2016 - Sep 21, 2016
Programming Things To-Do - Apr 01, 2014
App idea to learn new code - Mar 10, 2014
Cross-Origin Resource Sharing header - Jan 09, 2015
more >>



A     A     A     A     A

© 2013-2017 JotHut - Online notebook

current date: Nov 15, 2024 - 1:38 a.m. EST