reputapi functional specification

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


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:


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


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


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


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


About reputAPI.com


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


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!


About reputAPI.com


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/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


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.


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)


no knowledge of the identity of the person behind the ID.

item - unique-id referencing the item being voted upon


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


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


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

reputapi functional specification

Documents