of 12
8/9/2019 reputAPI Functional Specification
1/12
reputAPI.com
Functional Specification
Randall NOVAL
Last Updated: 17 Aug 2010
OverviewreputAPI.comis a service that lets people manage their communities and fight the trolls more
efficiently.
This spec is not, by any stretch of the imagination, complete. The wording needs revision,
the graphics and layout are just to illustrate the underlying functionality. The actual look and feelwill be developed over time with the input of graphics designers and iterative user feedback.
This spec does not discuss the algorithms used by the reputation engine, which will be
discussed elsewhere and in far greater depth. It simply discusses what the user sees when they
interact with reputAPI.com.
ScenariosIn designing products, it helps to imagine a real life story of how actual (stereotypical) people
would use them. We'll look at a typical scenario.
Scenario 1: Justin
Justin is a very busy community manager. He watches over a large, important community that
has many opinionated and vocal commenters. During the course of a typical day, he has much
reading to do and taming of trolls. Sometimes its a judgement call on whether a particular
comment is a troll or just someone making a dumb comment. Sometimes he gets in trouble
with the community for stifling conversation. These commenters can get very upset if Justin has
stifled a conversation that they were liking because he missed on his judgement. This happens
because although Justin is very smart and very good at his job, he doesn't always know what
people are thinking and why. Justin would love a way to let the community police itself and have
the high-value people (i.e. the ones who consistently add positive value to the conversations
and are actively engaged in the community) be the ones who decide how those conversationsgo.
Justin signs up for reputAPI.com, adds the API to their forum platform (theyre using vBulletin)
and watches. Over the next few weeks, 5 different people consistently have their comments
rated very highly and are very active on the site. So Justin contacts them and they agree
to become Moderators and suddenly Justin is no longer alone in his work. He has found
passionate people who want the community and the conversations to flourish (which means
8/9/2019 reputAPI Functional Specification
2/12
accepting opinions that they dont agree with also) and the trolls to disappear. Justin now has a
big grin on his face when he goes to work because he knows that he did a mitzvah which made
the community better and his life far easier.
Non GoalsThis version will notsupport the following features: Sophisticated reputation calculations
Though the calculation is a black-box and critical to the services success,
it is far beyond the scope of this version (mostly good for PhD research)
Deep data-mining options
This is strictly a proof of concept technology piece, not a full implementation of
the final product
Any kind of billing options
AssumptionsThese are the baseline working assumptions for the website:
A modern browser with JavaScript and cookies enabled
The copy on all pages is subject to frequent changes and in this document should be
considered flexible and not definitive
Database designThere is a separate document detailing in depth the database design for tracking the
relationships among voters. We are still waiting to hear from the DBAs on the design. Once we
receive a draft from them, we will add it to this document as appropriate. For now, just hold your
horses.
API ImplementationThere is a separate document detailing implementation in both common 3rd party forum
platforms as well as guidelines on how to add to custom-developed forums. That document
includes architecture, code samples and bad jokes.
reputAPI Website FlowchartWe'll have time later to go into mind-numbing detail, but for now, let's look at a quick flowchart
of the website so you get the big picture. This flowchart is not complete, but it does give you the
right idea for the "storyboard" for the website:
8/9/2019 reputAPI Functional Specification
3/12
WEBSITE
Screen by Screen SpecificationreputAPI.com consists of only a few different screens. Most will follow the brands look and feel
style guide (specified separately in the still to be created Style Guide). This document is focused
on the functionality and interaction design, not the look and layout.
All screens are created in HTML and CSS with .PNG image files. The assumption is that a
current, modern browser is used and that it supports JavaScript. If JavaScript is not available,an error message is displayed at the top of every page encouraging them to upgrade or turn on
JavaScript, however no forms are allowed to be submitted (i.e. they can only browse through
the site, not log in).
Each screen in reputAPI.com is known by a canonical name which will always appear, in this
document, with an underline, so you know we're referring to a screen by name, for example,
Home Page.
Home PageDisplayed when the user lands on the site, the Home Page serves three purposes:
1. Allow people to learn about the service and consider whether they want to sign up
2. Allow members who have already signed up to log on and view account information
3. Allow people who want to sign up to create an account.
The Home Page looks like this:
reputAPI.com
8/9/2019 reputAPI Functional Specification
4/12
Reputapi is a simple out-of-the-box
reputation system that you can deploy on
your site today.
This service is provided as-is and is a proof
of concept technology demonstration forentertainment purposes only. Do not stick
reputAPI.com in your ear or use it to clean
your elbow.)
The reputAPI API allows developers to
quickly customize for their site's unique
needs, or integrate reputations with a
universe of allied sites.
Already a member? Click here to log on!
Not a member yet? Don't worry -
membership is free! Yes, that's right, FREE!
Just click here to sign up, and within minutesyou'll be helping clear away those trolls!Privacy Notice | About Us | Contact Us
About reputAPI.com
On this, and on all screens, clicking on the reputAPI.com logo in the top left corner goes back to
Home Page.
Technical Note
Because of the high similarity between the various screens, some system ofincludes should
be used on the server so that if the name of the service changes we'll be able to change all the
screens in one place. I suggest Vignette Story Server. Sure, it's overkill. Sure, it costs $200,000.
But it's a heck of a lot easier than using server-side includes!
Clicking on the link that says "click here to log on" goes to Log In Form. Clicking on the link that
says "click here to sign up" goes to Sign Up Form. The other four links display pages with statictext to be provided by management, which are beyond the scope of this specification. They
will not have to change very often and have no functional requirements beyond following the
branding style guide.
Log In FormThe Log In Form is used by current members to log into their accounts in order to find out the
current time. It looks like this:
reputAPI.comPlease enter your email address:
[ e.g. [email protected] ]
Enter your password:
[ ]
Forgot your password? Just enter your email
Not a member yet? Don't worry -
membership is free! Yes, that's right, FREE!
Just click here to sign up, and within minutes
you'll be helping clear away those trolls!
Privacy Notice | About Us | Contact Us
8/9/2019 reputAPI Functional Specification
5/12
address and we'll email it to you.[ ] Remember me?
Log In
About reputAPI.com
The right side of the screen behaves the same way as described previously under Home Page.
The email box allows for up to 128 characters to be typed. The email box should have an
example email address that immediately disappears when the box has focus. If the box is
left blank and it loses focus, the example email address should reappear. The example email
address should be differentiated from normal text somehow (e.g. italic and grey).
The password box allows for up to 64 characters to be typed. To disguise them and prevent
hacking, as the user types in the password box, asterisks (*) will appear instead of the
characters that they type.
Password Box Technical Note
This is accomplished using
When the user clicks Log In, the following checks are performed on the server:
If the email address was provided, but it could not be a real email address because
it is not formatted correctly (e.g. there is no @ sign or it contains characters that are
not permitted in email addresses by RFC-822), a red error message will appear above
the email box, saying "The email address you provided is not in a valid format. Please
double check it." The incorrect email address that the user originally typed will now be
pre-populated in the email box. The Log In Form comes back with the password box clear.
If the email address was provided, but it does not correspond to a registered member,
a red error message will appear above the address box, saying "The email address
you provided is not a member. Please double check it. To become a member, use the
sign up link on the right side of the screen." The incorrect email address that the user
originally typed will be pre-populated in the email box.
If the user then clicks on the link to become a member, the email address
provided is used to pre-populate the email address on the sign up form.
The Log In Form comes back with the password box clear.
If the email address was provided, and it does correspond to a registered member,
but no password was typed at all, we send an email to that address containing thepassword. A red error message will appear above the address box, saying "You did not
enter a password. A reminder has been sent to your email address, please check it and
try to log in again." The subject of the email is "Your reputAPI.com membership". The
email is inplain text. The exact wording of this email is still being debated hotly by the
board of directors and the marketing department and will be provided sometime before
shipping.
Developers: For now I suggest using something nonsensical, like As plurdled
8/9/2019 reputAPI Functional Specification
6/12
gabbleblotchits on a lurgid bee, I remit the password stored to thee. That will
light a fire under their butts.
The Log In Form comes back with the password box clear.
If the email address was provided, and it does correspond to a registered member, and
a password was provided, but the password is incorrect, a red error message will appear
above the password box saying "The password you provided does not go with the emailaddress. Please double check it. Remember, passwords are case-sensitive." If the
password typed does not contain any lower case alphabetic characters, we also add this
text to the message: "Perhaps you've accidentally turned on CAPS LOCK?"
Whenever the password is incorrect, the Log In Form comes back with the
password box clear.
If the email address and password are OK, jump straight to Account Overview.
Open Issue
Need wording for password email from board of directors and the marketing department.
Open Issue
If Marketing allows, when the Remember Me box is checked and the Log In is successful, we
should deposit a cookie on the user's computer. Frequent visitors should not have to log in more
than once. I talked to Jim in Marketing about this and he's going to take point in convening a
committee of Sales, Marketing, and PR to discuss.
Account OverviewThe Account Overview is used by current members to see the status of their accounts. Since we
have no billing mechanism in place, there is only limited functionality available. It looks like this:
reputAPI.com
Totals (Metrics)
API Calls: #####
Users: #####
Votes up: #####
Votes down: #####
[email protected] || Log Out
Privacy Notice | About Us | Contact Us
About reputAPI.com
The right side of the screen behaves the same way as described previously under Home Page.
The top right corner will have the email address of the user that is logged in visually separated
from a Log Out link. Clicking the Log Out link makes an alert appear asking for confirmation. If
the user does not cancel, they are logged out and any related cookies are deleted.
The metrics are a set of simple calculations still being decided upon by the customer
8/9/2019 reputAPI Functional Specification
7/12
development, marketing and sales departments. When they give us the numbers that they want
displayed, these should be simple calculations for the user that is logged in.
Sign Up FormThe Sign Up Form is used by people looking to create accounts in order to get access to the
API. It looks like this:
reputAPI.com
Please enter your email address:
[ e.g. [email protected] ]
Enter your password:
[ ]
Enter your password again:
[ ]
Are you human:
[ CAPTCHA ]
Create Account
Don't worry - membership is free! Yes, that's
right, FREE!
Privacy Notice | About Us | Contact Us
About reputAPI.com
The right side of the screen behaves the same way as described previously under Home Page.
Create Account Technical Note
When the Create Account link is clicked, the following things happen:
The email box allows for up to 128 characters to be typed. The email box should have
an example email address that immediately disappears when the box has focus. If the
box is left blank and it loses focus, the example email address should reappear. The
example email address should be differentiated from normal text somehow (e.g. italic
and grey).
If the email address could not be a real email address because it is not formatted
correctly (e.g. there is no @ sign or it contains characters that are not permitted
in email addresses by RFC-822), a red error message will appear above the
email box, saying "The email address you provided is not in a valid format.
Please double check it."
The incorrect email address that the user originally typed will now be pre-
populated in the email box.
The Sign Up Form comes back with the password and CAPTCHA boxes
8/9/2019 reputAPI Functional Specification
8/12
clear The password box allows for up to 64 characters to be typed. The password box will be
in plain text.
If the password boxes do not match, a red error message will appear above the
password box, saying "Your passwords do not match. Please try again."
The email address that the user originally typed will be pre-populated inthe email box
The Sign Up Form comes back with the password and CAPTCHA boxes
clear
The Are You Human box should be a standard CAPTCHA from the official site.
http://www.captcha.net/
If the CAPTCHA fails, a red error message will appear above the email box,
saying "Your attempts at being human have failed, however we will let you try
again."
i. The email address that the user originally typed will be pre-populated in
the email box
ii. The Sign Up Form comes back with the password and CAPTCHA boxesclear
When the form submission is successful, an email is sent to the user with a link
to confirm their ownership of the account. If the user clicks on that link, they are
taken to the Account Overview page with a green message at the top of the page
saying Congratulations, your account has been activated!
The link should be a one-time generated hash that expires after 15 days
If the user clicks on the link after 15 days, they are taken to the Sign Up form with
a red message above the email box saying Were sorry, you waited too long to
confirm. Please feel free to create another account.
i. After 15 days without account confirmation, the account should be
deleted completely so that the user can create another account with thesame address
Open Issue
Need wording for welcome / confirmation email from board of directors and the marketing
department.
reputAPI API FlowchartWe'll have time later to go into mind-numbing detail, but for now, let's look at a quick flowchart ofthe service so you get the big picture. This flowchart is mostly complete for the minimum viable
product and it gives you the right idea for the "storyboard" for the API:
API CALLS
8/9/2019 reputAPI Functional Specification
9/12
API SpecificationThe reputAPI.com API consists of only a few calls. As this is primarily a back end calculation
service. There is no visual component to the API.
The API back-end should be written in Ruby using the Ruby-on-Rails framework. This is
because it is the only language our developers know and were not about to spend the time
necessary to learn another language for this proof concept technology project.
Technical Note
The API should follow good RESTful web API practices. The primary interface will be a URL
called using the GET method.
8/9/2019 reputAPI Functional Specification
10/12
https://api.reputapi.com/rest/xml/UpdateRep?Params
Params is a string of &-separated parameters following the UpdateRep? part of the URL. The
parameters are described below.
Note that https (SSL) protocol must be used as insecure connections are not supported.
API Call
Parameters
key - api-key for site/network
This should be the email address for the account. This will likely change down the road
to allow for multiple users per account. For now, lets keep things simple though.
voter - unique-id referencing the voter
This is generated by the forum software, is site-specific and anonymous. reputAPI has
no knowledge of the identity of the person behind the ID.
user - unique-id referencing the user voted upon (i.e. the author of the item)
This is generated by the forum software, is site-specific and anonymous. reputAPI has
no knowledge of the identity of the person behind the ID.
item - unique-id referencing the item being voted upon
This is generated by the forum software, is site-specific and anonymous. reputAPI has
no knowledge of the identity of the item behind the ID.
weight - boolean (1 or 0) value
This indicates whether it was a positive (1) or negative (0) vote. The impact of the vote
is determined by the Magic Black Box Algorithm which you shall not see (i.e. this is still
being debated by our cabal of PhD researchers and when they give us an algorithm
youll be the first to know).
Example Call:
https://api.reputapi.com/rest/xml/UpdateRep?
[email protected]&voter=2739482&user=5732927&item=2987661&weight=1
API Response
Response Codes
REST methods should return the standard HTTP response codes to indicate the status of the
call (e.g. 200 OK - Success).
item - ID of the item voted upon
8/9/2019 reputAPI Functional Specification
11/12
likes - Number of like or positive votes this item has had
dislikes - Number of dislike or negative votes this item has had
itemreputation - Total reputation value this item has acquired over time
user - ID of the user who was voted upon (i.e. the author of the item)
userreputation - Total reputation value this item has acquired over time
Example Response Data:
2987661
7
1
5
5732927973
Product RoadmapThis product roadmap is for your edification and reference only. The official version is being held
by the Product Owner (Mike) and is guiding all of our efforts. However, explanation of that vision
is beyond the scope of this one.
Minimum Viable Product:
Dev (Engine) alpha release:
API Engine will accept up/down votes
Calculate reputation change of a single user and return that value
Public release:
Simple descriptive website with contact form and request for
action (i.e. get contact info for someone who would actually pay)
Public Implementation:
WP plugin to accept up/down votes, display reputation
Version 1: Dev:
Batch process reputation for multiple users (i.e. return rep for
everyone in this thread).
Public:
WP plugin to accept up/down votes, display reputation
8/9/2019 reputAPI Functional Specification
12/12
Version 2:
Dev:
Tiered billing and per comment rating.
Version 3:
Dev:
Attack resistance
see "security proof" at http://www.advogato.org/trust-
metric.html
Public:
Admin option to reorder comments by reputation
Version 4:
Dev: Local graph vs global graph vs "party" graph (major release)
Public:
Analytics and metrics dashboard
Future:
Dev:
Tag based ratings
Adjust comment rep based on personal rep
Spam reporting User removal
Scale
Hunch API(?)
Machine learning to pre-tag comments then alert mods
Proactively moderate on high certainty
Public:
Facebook app (for fun/press a la hunch)
phpBB plugin
vBulletin plugin
Recommended threads