• User Help
• Create an Account
• Login
• Logout
• Profile Page
• Approved List
• Messages
• Create New Message
• Reply to a Message
• Show Message
• Threads
• Programmer Help
• Users

Kinglet User and Programming Documentation

#kinglet - #api - #rest - #json

Example usage: http://soupmode.com

It's a simple, web-based, private messaging app. It uses a basic, responsive design. It contains only a small number of functions. It's part microblog, part e-mail, and part message board.

This web app was created to communicate with friends and family in a different way and to practice API development. The API code is written in Perl, and it only returns JSON.

The "client" code that accesses the API also exists on the same server, and it is currently written in Perl, but a Node.js "client" will be created. These server-side client pieces could exist on servers different than the API server.

By having the API created, I can practice creating client code that is written in JavaScript that runs in the browser as a single page application. I can practice iOS and Android app development.

The API code receives REST requests, talks to the database, processes data, and returns JSON. Test scripts work against the API.

User Help

Create an Account

• User visits the sign-up page.
• User enters a username and an e-mail address.
• If configured, the system will send an e-mail with an auto-generated password and a link to activate the account. If the system is set to debug mode, then the password and the activation link will be sent to the browser. In debug mode, a user does not need to provide a valid e-mail address, since no e-mail is sent. But the user needs to provide an e-mail with valid syntax.
• User clicks the link to activate the account.

Login

• At the homepage or on the login page, the user enters the e-mail address, used to create the account and the password, generated by the system.
• Optionally, a user can check the save login box to avoid having to login the next time the user accesses the site. If using multiple devices, the save login box will have to be checked for each device if the user wants to avoid logging in on all devices.
• If the user forgets the password, the user can request the system to create a new password by entering the username and e-mail address in lost password section of the login page. If configured, the system will send an e-mail with the new password. If the system is in debug mode, then the new password is displayed to the browser.

Logout

• To remove the save login cookie from the device's browser, the user needs to click the logout link.

Profile Page

• To change password, e-mail address, or profile description information, the user clicks on his or her username, located in the navigation bar at the top of the site.
• Next, the user clicks on "Change your password, e-mail address, or description info" and follows the form fields accordingly.
• The e-mail address not seen by anyone else.
• If the user enters description or profile information, this information is only seen by others who are on the user's approved list.

Approved List

• Unless the user only wants to communicate with himself, the user needs to know someone else who has created an account.
• On the profile page, the user enters the username of a known user and clicks the Request Approval button under the text line that says:
  • "In order to message another user, you need to request permission to be added to the user's approved list."
• Users can message others only if the user is on the others' approved list.
• When the user sends the request, that other person is automatically added to the user's approved list as "approved."
• A user can send only one request to another user.
• If a user tries to send another request, the user will receive one of three messages:
  • request is still pending
  • request was approved
  • request was rejected
• When the other person has approved or rejected the request, the user will receive a system-generated message, indicating what type of action was taken.
  • "System Message: Your request to be added to xxxx's approved list has been approved." (or rejected)
• On the same profile page, the user can click "Approval requests received" to see if any new requests are pending or to change the status of previous requests. The user can modify his approved list by changing a user's status from approved to rejected and vice versa.

Messages

• The homepage shows a stream of all messages sent and received.
• Sent messages appear with a light blue background, and the text is displayed smaller and grayer.
• Received messages appear with a light green background, and the text is displayed larger and darker.
• Each message bubble displayed on the homepage contains links for:
  • displaying the individual message
  • displaying all the messages for the thread
  • replying to the thread
• Each message bubble on the homepage also shows the usernames who received the message.

Create New Message

• A new message is limited to a max of 300 characters.
• To create a new message, the user clicks the "new" link, located in the navigation bar.
• In the message box, the user adds the usernames who should receive the message.
• Each username is preceded with the at-sign.
• If multiple recipients, then each username is separated by at least one space.
• Example:
  • @userA @userB @userC Hello. This is a test message.
• If the user has not been added to a recipient's approved list, then the message will not be sent. Example message:
  • "Error: Bad Request - You cannot message 'userA' because your request to be added to the user's approved list is still pending a decision by the user." (or has been rejected)
• If the user creates or receives a new message that starts a new thread, then that message bubble on the homepage contains an orange bar at the bottom of the bubble.

Reply to a Message

• A reply message is limited to a max of 300 characters.
• On the homepage, the user can reply to a thread by clicking the "reply" link.
• Even though each reply contains a reply link, this is not a threaded discussion. Replies to replies to replies is not supported.
• Each reply is for the thread or the message that started the thread. It's like posting a comment to a message board that uses a flat commenting system, where the new comment appears at the bottom of the thread.
• When the user clicks the reply link on the homepage for a message, the first message that started the thread is displayed above the message box, along with a link to the entire thread.
• Clicking the "thread" link for a message on the homepage will also display the entire thread.

Show Message

• On the homepage and on the page that shows the entire discussion thread, each message contains its own permalink, which is the date that the message was created.
• Clicking the permalink for a message will display that individual message on its own page.
• When showing a message on its own page, a link will be displayed at the top of the page called "discussion thread," which will take the user back to the page that shows the entire discussion thread.
• Also when showing the message on its own page, a reply link exists.

Threads

• In the navigation bar, a link called "threads" exists.
• The threads link will show all discussion threads that the user has posted to. These could be discussion threads that the user started, or threads where the user was included on the original message sent by someone else.
• The threads page shows a small portion of the original message that started the thread and the number of replies for that thread. The replies count is a link to that discussion thread.

---

Programmer Help

( #todo list how the POST request is crafted. )

Kinglet API description. It's currently being used at Soupmode.com.

It uses REST and JSON.

Each function below is preceded with /api/v1 in the URI. So for Soupmode, it would be http://soupmode.com/api/v1.

Example of activating a new user account:
http://soupmode.com/api/v1/users/activate/ru8wkn0ol2ql3bm9

At the moment, I don't have SSL enabled at Soupmode.com, and OAuth is not used. Strengthening authentication is on the to-do list.

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 request.
  /users/JR

• Create a new user account.
  POST request.
  /users

• Activate user account.
  GET request.
  /users/activate/[user_digest]

• Logout user JR.
  GET request.
  /users/JR/logout

• Login user.
  Post request.
  /users/login

• Retrieve new password for existing account. User would not be logged in. This would be executed for someone who forgot or lost a password.
  POST request.
  /users/password

• Change password for existing account. User must be logged-in.
  PUT request.
  /users/password

• Update e-mail and/or profile description for the user.
  PUT request.
  /users