Snipia API Documentation All snipia methods interact with the server through XML/JSON requests. Requests return either an error code or a JSON String. For error codes, success are surrounded in OK html tags, while errors have ERR tags. The list of error codes and their description is at the end of this document. We'll start with quick examples to demonstrate how easy it is. They do not include error checking for simplicity. Note that you can pass parameters are GET or POST. QUICK EXAMPLES: EXAMPLE 1: Posting a snip to the View All section: With any web browser: http://www.snipia.com/_r_postSnip?user=MY_USER_NAME&pass=MY_PASSWORD&msg=Hello+World&privacy=everyone IN PHP: EXAMPLE 2: Posting a private snip to a group: With any web browser: http://www.snipia.com/_r_postSnip?user=MY_USER_NAME&pass=MY_PASSWORD&msg=Hello+Group&privacy=team&team=G000-MYGRO-e32e6ba9-c401-455f-8c4c-44df91656a3b IN PHP: EXAMPLE 3: Getting your snips in JSON format. http://www.snipia.com/_r_getAllSnipsForUser?user=MY_USER_NAME&pass=MY_PASSWORD IN PHP: Snip Methods _r_postSnip DESCRIPTION posts a user's snip to the given team on snipia PARAMS user : the user name (optional) pass : user password (optional) msg : snip message (140 char limit) team : team ID for the snip privacy : who can see the snip ("team"|"everyone") stype : type of snip ("snip"|"task"|"confirm") RETURNS ON SUCCESS 0010 RETURNS ON FAIL (one of listed error codes) 2000 2001 1011 _r_deleteSnip DESCRIPTION deletes a selected snip based on the given snip ID PARAMS user : the user name (optional) pass : user password (optional) snip : snip ID RETURNS ON SUCCESS 0020 RETURNS ON FAIL (one of listed error codes) 1000 1020 1021 1022 _r_searchsnips DESCRIPTION searches for snips based on given search keywords PARAMS searchval : the search string onlytasks : whether to only search outstanding tasks ("true"|"false") RETURNS ON SUCCESS JSON List of snip objects each with the following structure: Itemname = unique identifier for the snip msg = the message contained with in the snip owner = the username of the snip poster privacy = the privacy level of the snip datemade = unix time based value team = team id in which this snip was made imageIndex = in the index for the user image type = the snip type (snip/task/confirm) Other possible object attributes: Tasks: task = "yes" or the user who completed the task taskdate = the date the task was completed Confirms: whoconf = comma-sparated list of all team members who have confirmed numconf = the number of team members who have confirmed Links: link = the text for the http link linksize = the length of the link's clickable text RETURNS ON FAIL (one of listed error codes) 1102 1101 _r_getAllSnipsForUser DESCRIPTION returns all snips viewable by a user basedon their teams and permission levels PARAMS requires user to already be logged in. RETURNS ON SUCCESS JSON list of snip objects. Please refer to _r_searchsnips for detail on the snip objects RETURNS ON FAIL (one of listed error codes) currently error messages are returned inside tags. Error codes will (inside tags) will be used in a later version. Team Methods _r_createNewTeam DESCRIPTION creates a new team with the creating user as creatr and for admin PARAMS team : the team name tdesc : the team DESCRIPTIONription tparent : the parent team ID (required only for making a sub group) world : whether public snips are permitted ("true"|"false") friends : allow friends view access ("true"|"false") searchable : make this group publically searchable ("true"|"false") creater : the username of the creater RETURNS ON SUCCESS 0030 RETURNS ON FAIL (one of listed error codes) 1000 1001 1030 1032 _r_deleteTeam DESCRIPTION deletes a specific team based on team ID PARAMS team : team ID RETURNS ON SUCCESS 0040 RETURNS ON FAIL (one of listed error codes) 1040 1041 2001 _r_leaveTeam DESCRIPTION a logged in user can has his/her membership in a team removed by giving the team ID PARAMS team : team ID RETURNS ON SUCCESS 0140 RETURNS ON FAIL (one of listed error codes) 1140 1141 1142 2001 _r_modifyTeam DESCRIPTION team information can be modified PARAMS team : team ID tname : team name tdesc : team description string RETURNS ON SUCCESS 0070 RETURNS ON FAIL (one of listed error codes) 1000 1032 1070 1071 _r_addUserToTeam DESCRIPTION invites a suer to join a team based on username or email address PARAMS userAsking : the username requesting to add the new person userToAdd : the username or email of the new person team : team ID perm : permission level to be given ("user_admin"|"user_view_post_delete"|"user_view_post") RETURNS ON SUCCESS 0080 RETURNS ON FAIL (one of listed error codes) 1001 1005 1080 1081 1082 1083 1084 1085 1087 _r_getSingleTeamAsList DESCRIPTION get the information on a single team base on the given team ID PARAMS team : team ID RETURNS ON SUCCESS JSON string of a Team object with the following attributes: ItemName = the unique identifier for the team name = the team name tdesc = the team description user_creator = the user who created the team user_admin = list of users with admin access user_view_post_delete = list of users with full access user_view_post = list of users with limited access parent_team = the team Id for the parent team (if this a sub-group, otherwise "!nothing") allow_world = true/false if public posts are allowed for this team allow_search = true/false if to allow this team to be publically searchable allow_friends = true/false if to allow friends view access to this team (no yet implemented) confirms = number of outstanding confirm requests for this team tasks = number of outstanding tasks for this team RETURNS ON FAIL (one of listed error codes) empty JSON list _r_getTeamInfoForUser DESCRIPTION gets the info for all the team to which a user is a member (currently only returns team list for the logged user asking from his/her self - error code not yet implemented) PARAMS userAsking : user name of user asking userWanted : user name of user whose team list is requested (currently can only be same as userAsking) RETURNS ON SUCCESS JSON list of team objects to which userWanted belongs to. Please refer to _r_getSingleTeamAsList for a DESCRIPTIONription of the team object RETURNS ON FAIL (one of listed error codes) "Possible userWanted is not userAsking" (will later be replace with error codes) _r_acceptInvite DESCRIPTION a user accepting an invitation to a team PARAMS email : the email address of the invitee that is accepting teamid : team ID src : from where the user is accepting ("url"|"script") RETURNS ON SUCCESS 0090 RETURNS ON FAIL (one of listed error codes) 1001 1003 1004 1090 1091 User Methods _r_logInU DESCRIPTION logging in to snipia PARAMS user : username pass : password RETURNS ON SUCCESS 0180 RETURNS ON FAIL (one of listed error codes) 1180 _r_loadUserInfo DESCRIPTION get the information for the logged into user from snipia PARAMS only loads info for the user that is logged in. RETURNS ON SUCCESS JSON String of the user object with the following attributes: ItemName = unique identifier for the user object user = the user name password = user password (encrypted) displayname = the name to be displayed bio = the user's bio email = the user's email address firstname = first name lastname = last name location = user's location team = list of team IDs to which the user is a member imageIndex = the referencing index for the user profile image RETURNS ON FAIL (one of listed error codes) 1000 1005 _r_modifyUserInfo DESCRIPTION Make changes to the logged in user's person information PARAMS email : user email address newpwd : new password (optional if not chaning password) firstname : user's first name lastname : user's last name bio : user's bio location : user's location RETURNS ON SUCCESS 0130 RETURNS ON FAIL (one of listed error codes) 1000 2002 Task Methods _r_taskdone DESCRIPTION Mark a task in a snip as complete PARAMS snip : snip ID RETURNS ON SUCCESS 0050 RETURNS ON FAIL (one of listed error codes) 1000 2003 _r_confirmsnip DESCRIPTION Have a user confirm a confirmation request posted in a snip PARAMS snip : snip ID RETURNS ON SUCCESS 0060 RETURNS ON FAIL (one of listed error codes) 1000 1060 1061 SUCCESS CODES 0000 - OK 0010 - Snip posted 0020 - Snip deleted. You will see the change momentarily. 0030 - Team created. You will see the change momentarily. 0040 - Team deleted. You will see the change momentarily. 0050 - Task completed 0060 - Confirm received 0070 - Team info updated. 0080 - Invitation successfully sent. 0090 - You have successfully joined the team 0100 - Search successful. 0110 - An email has been sent with the associated usernames(s). 0120 - An email has been sent with a new password. 0130 - User profile has been updated. 0140 - You have been removed from this team 0150 - File uploaded succesfully. 0160 - File successfully deleted. 0170 - Signup successful. 0180 - Login successful. 0190 - Profile Image has been uploaded. You will see the change monetarily. ERROR CODES 1000 - User identification failure 1001 - Missing or invalid paramters 1002 - You do not have proper access to this team. 1003 - Unable to access team 1004 - Team does not exist 1005 - No such user exists 1006 - The email address is not found in our database. 1007 - There was an error sending the email. 1008 - No email address given. 1009 - There was an error getting the username corresponding to the email address. 2000 - Username or password is missing or null 2001 - User is not logged in. 2002 - Invalid email address. 2003 - Snip ID not given. 2004 - User is not a member of any teams 1010 - Error posting snip 1011 - Public snips have been disabled for this team. Please contact a team administrator. 1020 - Error deleting snip 1021 - You do not have permission to delete this snip. 1022 - This snip has already been deleted. If visible, it should disappear momentarily. 1030 - Error creating team 1031 - Team created, but error adding user to team. 1032 - Team name cannot be empty. 1040 - Error deleting team 1041 - Cannot delete team. you do not have administrator access 1050 - Error completing task 1051 - Task is already marked complete 1060 - Error completing confirmation 1061 - Snip was laready confirmed by this user 1070 - Error modifying team 1071 - Cannot modify team - user is not a team administrator 1080 - You cannot invite yourself 1081 - You do not have permission to invite people to this team. 1082 - Invitation to team failed. 1083 - Email of team invitation failed. 1084 - This person has already been invited. 1085 - There was an error sending the invitation. 1086 - The name of the intived person is blank. 1087 - You cannot grant access above your permission level. 1090 - User was not invited to the team 1091 - User is already a member of this team 1092 - Error adding user to the team. 1100 - No search results 1101 - Search query failed 1102 - Empty search string 1110 - There was an error getting the email's corresponding user name(s). 1120 - There was an error while changing the password 1130 - Error updating user profile. 1140 - Error removing user from the team. 1141 - You are not a member of this team. 1142 - You are the only administrator. You cannot leave this team but you can delete it. 1150 - There was an error while uploading the file. 1151 - No file uploaded. Uploads count is 0 or less. 1152 - Unsupported file type. 1153 - Attachments found but did not match given file name. 1160 - There was an error while deleting the file. 1161 - You do not have the permission level to delete files for this team. 1170 - Error signing up new user. 1171 - User name already exists. Please choose another one. 1172 - Email address already in use. Please use a different one. 1173 - Captcha validation failed. 1174 - No email address given. 1175 - No username given. 1176 - No password given. 1177 - No captcha values given. 1178 - No first names given. 1179 - No last name given. 1180 - Login failed. 1190 - Error updating profile image. 1191 - No image was uploaded.