Web Services API Specification Docfedora.cis.cau.edu/~asazegar/_profile/assets/WS... · 1...

1 ©Copyright 2014-2017, MohammadAli Sazegarnejad. Unauthorized use is prohibited.

Web Services API Specification Doc

Version Date Author Description

1.10.5 Apr 5,16 M. Ali Sazegarnejad - updated Social Network

Authentication p7

1.10.4 Apr 4,16 M. Ali Sazegarnejad - added new message & notification

count p. 61

1.10.3 Mar 13,16 M. Ali Sazegarnejad - added new API call get challenge

by id p.43.

- New field for All Participant

added:

[Total_supported_achieved]

1.10.2 Mar 7, 16 M. Ali Sazegarnejad - changed Message & Notification

tags field to data. Section 5

1.10.1 Jan 18, 16 M. Ali Sazegarnejad - Updated search with filter tags

option sec. 6.3 (added cat &

selected cat. Id, num. of records,

removed oid page 73

- updated filter list to group tags as

list or categorized by setting format

param. page 71

1.10.0 Jan 18, 16 M. Ali Sazegarnejad - added search with filter tags

option sec. 6.3 page 72

1.9.1 Jan 11, 16 M. Ali Sazegarnejad - change of service call name

participantchallenges to

participantprofile (p 34)

- removal of a duplicate service call

1.12 which listed all participants

1.9.0 Jan 9, 16 M. Ali Sazegarnejad - request for new activation link

1.8.0 Jan 8, 16 M. Ali Sazegarnejad -added service for filter list (p.71)

1.7.1 Sep 5, 15 M. Ali Sazegarnejad -special-event flag added to event

object

- list of orgs involved in an event is

added to event-info of event object

(p.28,29)

1.7.0 Aug 17, 15 M. Ali Sazegarnejad

-add is_nonprofit flag to

organization

-8.1, 8.2 added support for donation

to participant only

-8.3 itemized donation by date of

payment. Check description and

donateTo fields of response for

additional info

-1.8, 1.9 added

charitable_tax_deduction to

user_profile


-6.2, 6.3 added recent and trends

1.6.0 Aug 11, 15 M. Ali Sazegarnejad -1.9 update first & last name

-8.1,8.2 post donation expanded for

PayPal accounts vs CC payments

1.5.0 Aug 3, 15 M. Ali Sazegarnejad - 3.9 List of Participants

- updated the table of content

1.4.0 Aug 2, 15 M. Ali Sazegarnejad - added 3.8 get challenge

participants

1.3.0 July 29, 15 M. Ali Sazegarnejad

- 1.8 gender added for user profile

- 1.9 update user profile

- 1.10 upload avatar

- 1.11 get active participants

- 3.1,3.2 get events and challenges

1.2.0 July 28, 15 M. Ali Sazegarnejad

- Added User Profile

- ch.1 title changed to User

Management

- combined calls to list of all events

for each organization

1.1.2 July 13, 15 M. Ali Sazegarnejad - removed participant_id from the

post comment service

1.1.1 July 11, 15 M. Ali Sazegarnejad - Auth. support for Instagram

1.1.0 July 7, 15 M. Ali Sazegarnejad - donation services add - Mobile Asset service (bg img etc)

- p45 changed param device_id to

device - api-key added for sys. ws calls.

(Appendix)

1.0.1 June 10, 15 M. Ali Sazegarnejad - typos correction - p.13 password update user_id is

set to UUID - p.29 Fav. changed to Follow

1.0 June 9, 15 M. Ali Sazegarnejad Mobile App Client Services


Table of Contents

1. User Management ...................................................................................................................................... 6

1.1 Using user name and password ........................................................................................................ 6

1.2 Social Network Login......................................................................................................................... 8

1.3 Returning User Authentication ....................................................................................................... 10

1.4 User Logout ..................................................................................................................................... 12

1.5 User Sign-up .................................................................................................................................... 13

1.6 Request New Activation Link .......................................................................................................... 15

1.7 Forgot Password ............................................................................................................................. 16

1.8 Update Password ............................................................................................................................ 17

1.9 User Profile ..................................................................................................................................... 19

1.10 Update Profile ............................................................................................................................. 21

1.11 Upload User Avatar ..................................................................................................................... 23

2. Organization ............................................................................................................................................. 24

2.1 List of all available organizations .................................................................................................... 24

3. Events & Challenges ................................................................................................................................. 27

3.1 List of All Ongoing & Upcoming Events .......................................................................................... 27

3.2 List of All Ongoing & Upcoming Challenges .................................................................................... 27

3.3 List of All Ongoing & Upcoming Events for The Given Organization .............................................. 29

3.4 List of Participants for The Given event id ...................................................................................... 33

3.5 List of Events & Challenges for The Given Participant .................................................................... 35

3.6 List of Challenges for The Given Organization ................................................................................ 38

3.7 List of Challenges For The Given Event ........................................................................................... 40

3.8 List of Participants For The Given Challenge .................................................................................. 42

3.9 List of Challenge For The Given Challenge Id .................................................................................. 44

3.10 List of Participants ....................................................................................................................... 45

4. User Follow & Like .................................................................................................................................... 48

4.1 Follow an Organization ................................................................................................................... 48

4.2 Like an Organization ....................................................................................................................... 49

4.3 Follow an Event ............................................................................................................................... 50

4.4 Like an Event ................................................................................................................................... 52

4.5 Follow a Participant ........................................................................................................................ 54

4.6 Like a Participant ............................................................................................................................. 56

4.7 Follow a Challenge .......................................................................................................................... 58


4.8 Like a Challenge .............................................................................................................................. 60

5. Messages & Notifications ......................................................................................................................... 62

5.1 Message & Notification Count ........................................................................................................ 62

5.2 List of Messages .............................................................................................................................. 63

5.3 Accept a Message ........................................................................................................................... 65

5.4 Delete a Message ............................................................................................................................ 67

5.5 Seen Messages ................................................................................................................................ 68

5.6 List of Notifications ......................................................................................................................... 69

5.7 Seen Notifications ........................................................................................................................... 71

6. Search & Trends ........................................................................................................................................ 72

6.1 Searching all entities ....................................................................................................................... 72

6.2 Search Filter List .............................................................................................................................. 75

6.3 Search with Filter/Tags ................................................................................................................... 76

6.4 Recent Entities ................................................................................................................................ 78

6.5 Trends ............................................................................................................................................. 80

7. Comments ................................................................................................................................................ 82

7.1 Post Comment ................................................................................................................................ 82

8. Donations ................................................................................................................................................. 84

8.1 Post Donation ................................................................................................................................. 84

8.2 Post Donation ................................................................................................................................. 88

8.3 Donor Donation Report .................................................................................................................. 91

9. System Services ........................................................................................................................................ 93

9.1 Mobile Asset Retrieval .................................................................................................................... 93

Appendix ............................................................................................................................................................... 95

Conventions .............................................................................................................................................. 95

Status Codes ............................................................................................................................................. 95

Entity Structure ......................................................................................................................................... 97

System Structure ...................................................................................................................................... 98


.................................................................................................................................................................. 98


Methods

1. User Management

1.1 Using user name and password

Authenticate the user with the system and obtain the auth_token/session_token

Request

Method URL

POST api/usrmng/usrauth

Type Params Values

POST

POST

POST POST

username

password device_id isMob

string

string string string

session

The session that is given in response to successful login /api/usrmng/usrauth and will be used with all requests that require authentication and authorization.

device_id

Each mobile or web client will generate a unique device id that will be used along with almost all requests

isMob

It will be either y or n to track activities of devices.


Response

Status Response

200 { session: "" code:

"status_code" message: "Success or error message" user_id:

"UUID" group_id: "donor, student, staff" changePass: “true or false. True is when password reset

has been requested” fname: "" lname: "" org_id: "organization_id" }

session (string) – will be used with all requests

changePass (string) –user should reset password

org_id (string) – students and staff will have org association

errors 501, 502, 503,504,505,506,507,508


1.2 Social Network Login

This method is used for third party authentication (Facebook, twitter, Google+,

Instagram). If the user is new to Count on Me, then a new account is created for him. Since Twitter and Instagram are not sharing user email address, an email verification step is required for the first time. Please read the notes below for more info.

Request

Method URL

POST api/usrmng/usrauthsn

Type Params Values

POST

POST

POST POST

type

device_id isMob data

string

string string object

type

Set the source of authentication which can be TW for twitter, GP Goolge+, FB for

Facebook and INST for Instagram.

device_id


isMob


data

The data contains all possible information extracted from user’s public record. First Name, Last Name, email and user_id are essential field that should be transferred for authentication process i.e. "data": {

"name": "John Robinson",

"first_name": "John",

"middle_name": "nil",

"last_name": "Robinson",

"birthday": "yyyy-mm-dd",

"username": "user_name",

"user_id": "user_name",

"link": "https://www.facebook.com/app_scoped_user_id/1396675714/", "email": "[email protected]",

"gender": "male"


}

Response

Status Response

200

{ session: ""

code:

"status_code" message: "Success or error message"

user_id: "UUID" group_id: "donor, student, staff" changePass: “true or false. True is when password reset

has been requested and user should be asked to rest its

password via website.” fname: "" lname: "" org_id: "organization_id" }




errors 506, 507, 508, 526, 527

**Notes:

To ease the process for the Twitter & Instagram users and to avoid asking for their email address every time the following

message exchange will happen:

1. The app will do the authentication using the Twitter or Instagram API.

2. Then the app sends the data received from the API, once the authentication is verified.

3. If it is the first time for the user that uses the app, then error 526 will be generated which means the credential is

not valid (which in this case it is due to missing email address)

a. Now the app asks the user for email address

b. Then if the address email format is validated, an activation link is sent to the user’s email address

4. If the user uses multiple social media and/or COM account to authenticate, the user will get 527 error and should

use only the first account used to login.


1.3 Returning User Authentication

If a user is returning it is required to use a new session token. This service call will invalidate the previous session token and issues a new one in the

Response message.

Request

Method URL

POST api/usrmng/usrauthret

Type Params Values

POST

POST

POST

POST

POST

username user_id session device_id isMob

string

string string string string

username

The email address of the returning user

user_id

A UUID provide at the initial user authentication

session

Current session token received by last authentication request

device_id


isMob



Response

Status Response

200 { session: "" code:

"status_code" message: "Success or error message" user_id:

"UUID" group_id: "donor, student, staff" changePass: “true or false. True is when password reset

has been requested and user should be asked to rest its

password via website.”

fname: ""

lname: "" org_id: "organization_id" }




errors 501, 502, 503,504, 505, 506, 507, 508, 509


1.4 User Logout

This addresses the logout process and invalidation of current session token

Request

Method URL

POST api/usrmng/signout

Type Params Values

POST

POST

POST

session device_id isMob


session


device_id


isMob


Response

Status Response

200 { session: "UUID"

code: "status_code" message: "Success or error message" }


errors 508,509,516


1.5 User Sign-up

This addresses the signup process. On success an activation link will be sent to the provided email address. This also checks for duplicate user name and invalid email address.

Request

Method URL

POST api/usrmng/sigup

Type Params Values

POST

POST

POST

POST

POST

POST

email fname lname password device_id isMob

string string string string string string

username

User’s email address which will be used to send temp password.

fname

First name of the user who is signing up

lname

Last name of the user who is signing up

device_id


isMob



Response

Status Response




errors 508,514,517


1.6 Request New Activation Link

Will generate a new activation key and emails the user to new link to activate his/her account.

Request

Method URL

POST api/usrmng/newactivation

Type Params Values

HEAD

POST

device username

string string

username

This will be used as username. If it is not valid duplicate error will be issued

device


Response

Status Response

200 { session:””,


session (string) – will be empty

errors 508,509


1.7 Forgot Password

Will reset user’s password and will email a temp password to user. Once the temp password is set the user should update his/her password at the next successful login attempt. Check for changePass flag of authentication service call response.

Request

Method URL

POST api/usrmng/resetpassword

Type Params Values

POST

POST

POST

username device_id isMob


username

This will be used as username. If it is not valid duplicate error will be issued

device_id


isMob


Response

Status Response

200 { session: "UUID" code:

"status_code" message: "Success or error message" }


errors 508,515


1.8 Update Password

Will reset user’s password and will email a temp password to user. Once the temp password is set the user should update his/her password at the next successful login attempt. Check for changePass flag of authentication service call response.

Request

Method URL

POST api/usrmng/updatepassword

Type Params Values

POST

POST

POST

POST

session


string string string object

session


device_id


isMob


data

This a json object containing the following key/values:

- user_id: UUID that has been provided in successful authentication response

- old_password: current password of the user

- new_password: new password of the user


Response

Status Response




errors 504,508,509,510


1.9 User Profile

To retrieve user information such as followed/liked items and personal information (i.e. contact info). If a user is not following or did not like any item of a category, such category will not be included in the response. For example, if a user does not follow any participant, the response will not include participants array in under follows key.

Request

Method URL

GET api/usrmng/profile/{user_id}

Type Params Values

HEAD

HEAD

GET

Authorization device User_id

string

string string

Authorization

This value is the same as session token being used in other service calls. It is case sensitive and has to be set as “Authorization” in the header of the http request and its value is the current session token received by last authentication request

device

Each mobile or web client will generate a unique device id that will be used

along with almost all requests

user_id

After the path only the user_id value is supplied as a parameter

Example: api/usrmng/profile/b6e2accb-8909-442a-9201-722a9426c28a


Response

Status Response


code: "status_code" message: "Success or error message"

data:{} }


data (object) – will contain complete user profile

errors 504,508,509,510

"data": {

"profile_id": "0f93b7de-e3a0-4ab2-86b5-b43d9cd5fd42",

"avatar": "https://s3.amazonaws.com/user-data/avatar-male.png",

"email_address": "[email protected]",

"cell_number": "1234567890",

"phone_number": "1234567890",

"address1": "123 ABC St",

"address2": "#100",

"address_city": "atlanta",

"state": "ga",

"zipcode": "13245",

"user_id": "0eabc8c7-a4aa-4532-a1b2-c375bfc2314b",

"social_network": "instagram",

"gender": "male",

"charitable_tax_deduction": true|false

"likes": {

"organizations": [],

"events": [],

"challenges": [],

"participants": []

}

"followes": {


"events": [],

"challenges": [],

"participants": []

}

}


1.10 Update Profile

A limited number of fields are available for user to update at this point.

Request

Method URL

POST api/usrmng/profile/{user_id}

Type Params Values

HEAD

HEAD

POST

Authorization device user_profile

string

string object

Authorization


device



user_profile

The payload/data portion of the POST is a JSON object with the following format

containing all the profile information (both existing and updated) is sent as

follow:

{

"first_name": "name",

"last_name": "name",

"gender": "male",

"charitable_tax_deduction":true|false,

"cell_number": "1234567890",

"phone_number": "1234567890",

"address1": "45 EFGH St",

"address2": "#12",

"address_city": "los angeles",

"state": "ca",

"zipcode": "10005"

}

Example: api/usrmng/profile/b6e2accb-8909-442a-9201-722a9426c28a


Response

Status Response



data:{} }


errors 508,509,510


1.11 Upload User Avatar

Allows users to change their avatar picture.

Request

Method URL

POST api/usrmng/profile/avatar

Type Params Values

HEAD

HEAD

FORM_DATA

Authorization device image_file

string

string fileupload

Authorization


device



image_file

For file upload the content should be Multipart and therefore the content-type

should be set as Content-Type: multipart/form-data

Response

Status Response



data:{ "url":"https://s3.amazon.com... "} }


errors 508,509,510


2. Organization

2.1 List of all available organizations

List of organizations and along with a brief statistical info about each organization

Request

Method URL

POST api/orgmng/orgprofiles

Type Params Values

POST

POST POST

session

device_id isMob

string

string

string

session


device_id


isMob


Response

Status Response

200

{ session: "2bd21a01-228f-490d-8a84-

81eccedfc553" code: "200" message: "success" data:[{organization_1},{ organization_2}] }


data (array) – contains a list of organization objects and by default it

is ordered by name. Refer to the glossary for structure of organization in

JSON

errors 508,509

Organization:


{

"organization_id": "28cf424b-686f-4653-ae4f-2fc0b6977cdd",

"name": "Hills High School", "primary_contact_name": "Brian Smith",

"address_1": "241 Moreno Drive",

"city": "Hills",

"state": "CA", "zipcode": "01234",

"gps_latitude": "0.0",

"gps_longitude": "0.0",

"web_url": "http://school-web.org", "created_by": "sys",

"creation_date": 1424580208318,

"last_updated_by": "sys",

"last_update_date": 1424580208318, "logo_url": " http://school-web.org/log.jpg ",

"student_count": "2406", // Number of Students

"collection_amount": "0", //Total amount of collected donation

"commitment_amount": "0",//Total amount of collected donation with fulfilled challenges

"num_events": "0",//Total number of events hosted so far

"event_list":[{event1, event2,…}],// contains all ongoing and upcoming events for this oraganization. "num_upcoming_events": "0",//Total on going and future events up to next 20 days

"num_followers": "2",//Count of users following this organization

"total_goals": "510000",// Total annual budget for the current school year "description": "Hills High School is the only major public high school in Hills, California…", "isFollowed": "false", // true if current user has followed this organization "followed": "false", //same as isFollowed, is deprecated

"isLiked": "false",// true if current user has liked this organization

"liked": "false",// same as isLiked, is deprecated

"phone_num": "3101234567",// organization phone number

// an array of budget items for the current school year. The last item of the array has the total annual budget "orgination_budget": [ { "budget_id": "54ec758a-9ce3-471f-860d-0eb56384de0f",

"title": "Coordinator of Info. Tech.",

"description": "Testing 15",

"organization_id": "28cf424b-686f-4653-ae4f-2fc0b6977cdd", "amount": 8900990,

"school_year": "2015-2016"

},

{ "budget_id": "e531c7a1-43a7-4ca5-9c3c-7a44516208c1",

"title": "Coordinator of Info. Tech.",

"description": "Testing",

"organization_id": "28cf424b-686f-4653-ae4f-2fc0b6977cdd", "amount": 5600910,

"school_year": "2015-2016"

},

{ "title": "",

"description": "TOTAL",

"organization_id": "28cf424b-686f-4653-ae4f-2fc0b6977cdd",

"amount": 14501900,


"school_year": "2015-2016"

} ], }


3. Events & Challenges

3.1 List of All Ongoing & Upcoming Events

List of events available globally. Each event has a set of challenges and participants/students can attend an event accepting one or more challenges of an event.

Request

Method URL

POST api/eventmng/events

Type Params Values

POST

POST

POST

session

device_id isMob

string

string

string

session


device_id


isMob


Response

Status Response

200

{ session: "2bd21a01-228f-490d-8a84-

81eccedfc553" code: "200" message: "success" data:[{event_1},{ event_2}] }


data (array) – contains a list of event objects and by default it is

ordered by start date. Refer to the glossary for structure of event in JSON

errors 508,509

3.2 List of All Ongoing & Upcoming Challenges

List of all available challenges. Each challenge has a list of participants and general information about the challenge itself.


Request

Method URL

POST api/eventmng/challenges

Type Params Values

POST

POST

POST

session

device_id isMob

string

string

string

session


device_id


isMob


Response

Status Response

200 { session: "2bd21a01-228f-490d-8a84-



data (array) – contains a list of challenge objects and by default it is

ordered by start date. Refer to the glossary for structure of challeneg in

JSON

errors 508,509


3.3 List of All Ongoing & Upcoming Events for The Given Organization

Each organization/school has a list of events. Each event has a set of challenges and participants/students can attend an event accepting one or more challenges of an event. This is an event structure of a given organization/school:

Request

Method URL

POST api/eventmng/orgevents

Type Params Values

POST

POST

POST POST

session

device_id isMob organization_id

string

string

string string

session


device_id


isMob


organization_id

The id of the selected organization for which its events are being pulled by this service call


Response

Status Response

200

{ session: "2bd21a01-228f-490d-8a84-



data (array) – contains a list of event objects and by default it is

ordered by start date. Refer to the glossary for structure of event in JSON

errors 508,509

{ "event_id": "id", "created_by": "UUID", //usually it is an id of a staff member "creation_date": 1422810222850, "last_updated_by": "UUID", "last_update_date": 1422810222850, "address1": "140 South Av.",//address of venue where the event takes place "city": "Denver", "state": "CA", "zipcode": "01234", "title": "Baseball Varsity Season - 2015 ",//title of the event "description": "The emphasis of Saturn’s Baseball team is spiritual growth, ...", "event_type": "sport", //current types of events are {sport, academic, art, other} "organization_id": "UUID", "start_date": 1423535190593, "end_date": 1428200790593, "coordinator_id": "UUID",//a staff member in charge of this event "coordinator": { "staff_id": "715e83b3c447e674826bacd4532", "title": "Student Dean", "work_phone": "3101234567", "work_phone_ext": "100", "mobile": "818456789", "last_updated": 1423501070048, "email": "[email protected]", "isAdmin": true, //no use on the client side "user_id": "bf1b2567-0edf-49a4-8f94-4e609994b0ad", "first_name": "Brian", "last_name": "Green", "org_id": "9a5add5b-3c9a-4575-a366-12ea2ce1af66", "admin": true//no use on the client side }, "isFollowed": "false", // true if current user has followed this organization "followed": "false", //same as isFollowed, is deprecated "isLiked": "false",// true if current user has liked this organization

"isSpecial": "false" //true if this is a special event and one or more schools are participating. Look at eventInfo for more details using organizations list;

//this is an object containing 2 arrays which one contains list of challenges for this event and the other one contains list of participants for this event. The last object is event_stat congaing


"eventInfo": { //a single challenge can be accepted by more than one participant. Challenges come with two types of individual and team challenge "organizations": [ ], "challenges": [ { "challenge_id": "b5db5686-86ba-4c47-be15-33de12eccd13", "event_id": "event_id", "template_id": "template_id", "data_value": " 1", //ignored on the client side "created_on": 1433273942274, "created_by": "0eabc8c7-a4aa-4532-a1b2-c375bfc2314b", "start_date": 1423535190593, "end_date": 1428200790593, "ch_type": "individual", // there two types currently {individual and team} "category": "sport",// current category challenges are {sport, academic, art, other} "title": "Will walk more than 1 times", "description": "This is an individual challenge for the upcoming game event", "logo_url": "https://s3.amazonaws.com/organizationassets/bb_field.jpg", "sub_category": "baseball",// here is the current settings{ sport: [baseball, basketball, football], art:[music, theater, painting], academic:[]}. More items to come "added_by": "sys", //ignored on the client side "creation_date": 1426276964436, "suggested_donations": "{$10,$25, $40}", //These are the suggested donations set by school "default_data_value": "3",//ignored on the client side "organization_id": "9a5add5b-3c9a-4575-a366-12ea2ce1af66", "isPublished": "true", "isLiked": "false",//if current user likes this challenge "isFollowed": "false"//if current user follows this challenge } ], "participants": [ { "num_challenges": "1",//count of accepted challenges "num_achievements": "1",//count of fulfilled challenges out of all accepted challenges "total_amount_support": "123.00",//total amount of collected donation support "num_donors": "1",//count of donors supported this participant in general "num_followers": "1", "num_likes": "1", "isLiked": "false",//if current user likes this challenge "liked": "false", "followed": "true", "isFollowed": "true"//if current user follows this challenge //list of teams that this participant is a member of. Teams can be sport teams, academic class or grade, as well as any subject matter group or club such as biology club. "teams": [ { "team_id": "c4487f5b-b6fb-4451-a609-a0ac6a6739f4", "team_name": "VA Boys Baseball", "team_type": "sport", "team_description": "Varsity baseball team", "organization_id": "9a5add5b-3c9a-4575-a366-12ea2ce1af66" } ],


"first_name": "John", "last_name": "Smith", "group_id": "1310",//student group code "admin_flag": "false",/no use on the client side "participant_id": "UUID" } ], //eventually this object will be completed to be the source of all stat info about events "event_stat": { "event_id": "cb9653810cd945be3f005756db6094253586037c32d8337539", "title": "Baseball Varsity Season - 2015 ", "description": " will learn life skills and physical level…", "event_type": "sport", "published": "true", "start_date": 1423535190593, "end_date": 1428200790593, "total_donors": "0", "likes": "0", "followers": "1", "accepted_challenges": "1", "fulfilled_challeneges": "1" } }, }


3.4 List of Participants for The Given event id

Request

Method URL

POST api/eventmng/eventparticipants

Type Params Values

POST

POST

POST POST

session device_id isMob event_id

string

string

string string

session


device_id


isMob


Response

Status Response

200 { session: "2bd21a01-228f-490d-8a84-81eccedfc553"

code: "200" message: "success" data:[{participant_1},{ participant_2}] }


data (array) – contains a list of participant objects and by default it is

ordered by their last name. Refer to the glossary for structure of event in

JSON

errors 508,509


data: [

{ "num_challenges": "1",//count of accepted challenges

"num_achievements": "1",//count of fulfilled challenges out of all accepted challenges "total_amount_support": "123.00",//total amount of collected donation support "num_donors": "1",//count of donors supported this participant in general "num_followers": "1", "num_likes": "1",

"isLiked": "false",//if current user likes this challenge "liked": "false", "followed": "true",

"isFollowed": "true"//if current user follows this challenge

//list of teams that this participant is a member of. Teams can be sport teams, academic class or grade, as well as any subject matter group or club such as biology club. "teams": [

{

"team_id": "c4487f5b-b6fb-4451-a609-a0ac6a6739f4", "team_name": "VA Boys Baseball",

"team_type": "sport",

"team_description": "Varsity baseball team",

"organization_id": "9a5add5b-3c9a-4575-a366-12ea2ce1af66" }

],

"first_name": "John", "last_name": "Smith",

"group_id": "1310",//student group code

"admin_flag": "false",/no use on the client side

"participant_id": "UUID" }

]


3.5 List of Events & Challenges for The Given Participant

The response from the participant events & challenges service contains a participant object which includes two list of events and challenges which this participant has accepted/attened. The structure of participant as follow:

Request

Method URL

POST api/eventmng/participantprofile

Type Params Values

POST

POST

POST POST

session device_id isMob participant_id

string

string

string string

session


device_id


isMob


Response

Status Response


code: "200" message: "success" data:{“participant”:{participant},”challenges”:[{

challenge_1},{ challenge_2}]} }


data (array) – contains a participant object and a list of challenges

that he/she has accepted.

errors 508,509

participant:


{ "num_challenges": "1",//count of accepted challenges "num_achievements": "1",//count of fulfilled challenges out of all accepted challenges "total_amount_support": "123.00",//total amount of collected donation support "num_donors": "1",//count of donors supported this participant in general "num_followers": "1", "num_likes": "1", "isLiked": "false",//if current user likes this challenge "liked": "false", "followed": "true", "isFollowed": "true"//if current user follows this challenge //list of teams that this participant is a member of. Teams can be sport teams, academic class or grade, as well as any subject matter group or club such as biology club. "teams": [ { "team_id": "c4487f5b-b6fb-4451-a609-a0ac6a6739f4", "team_name": "VA Boys Baseball", "team_type": "sport", "team_description": "Varsity baseball team", "organization_id": "9a5add5b-3c9a-4575-a366-12ea2ce1af66" } ], "first_name": "John", "last_name": "Smith", "group_id": "1310",//student group code "admin_flag": "false",//no use on the client side "participant_id": "UUID" ,

challenges: [{

"challenge_participant_id": "id", "type": "individual",// it can be a “team” or “individual” challenge

"team_id": "id",// if it is a team challenge then this field is set with to the team id

"default_data_value": "3",// no need on the client side "data_value": "2",// maximum score possible for a challenge and it is always set "score": "2", // if a challenge is fulfilled, then this field is set with respect to participant performance "score_date": 1432170611673, // the date that challenge has been fulfilled "fulfilled": "true", //set to true if the challenge has been fulfilled, if it is false it is still in progress "fulfill_date": 1421712300000, "accepted": "true", // whether the participant has accepted the challenge or not "acceptance_date": 1426287352603, // "rejected": "false",// if a challenge has been rejected by the participant "published": "true", // the client side only receives published challenges "challenge_id": "id", // id of the challenge "event_id": "id",// id of the event that this challenge belongs to "organization_id": "id", // the organization that this hosting the event and this challenge "template_id": "id", "creation_date": 1426277204604,

"start_date": 1423535190593, "end_date": 1428200790593, "created_by": "sys", // either the default system created challenges or contains the id of a person creating the challenge "title": "Will walk more than 2 times", // title of the challenge


"description": "This is an individual challenge for the upcoming game event", "category": "sport",// current category challenges are {sport, academic, art, other} "sub_category": "baseball",// here is the current settings{ sport: [baseball, basketball, football], art:[music, theater, painting], academic:[]}. More items to come "suggested_donations": "{$10,$25, $40}",// this is a suggested amount for a given challenge "challenge_stat": { "challenge_id": "uuid", "fulfileld_count": "1", "participants": "1", "total_donations": "123.00", "total_donors": "1", "asOfDate": 1433616107828, "likes": "0", "followers": "0" } }], events:[//similar to other events ]


3.6 List of Challenges for The Given Organization

(since two weeks ago)

Request

Method URL

POST api/eventmng/orgchallenges

Type Params Values

POST

POST

POST POST

session device_id isMob organization_id

string


session


device_id


isMob


Response

Status Response


code: "200" message: "success" data:[{ challenge_1},{ challenge_2}] }


data (array) – contains list of challenges which their end date was set

after two weeks ago for the given organization

errors 508,509

data:[{

"challenge_participant_id": "id",


"type": "individual",// it can be a “team” or “individual” challenge


"default_data_value": "3",// no need on the client side

"data_value": "2",// maximum score possible for a challenge and it is always set "score": "2", // if a challenge is fulfilled, then this field is set with respect to

participant performance

"score_date": 1432170611673, // the date that challenge has been fulfilled

"fulfilled": "true", //set to true if the challenge has been fulfilled, if it is false it is still in progress "fulfill_date": 1421712300000,

"accepted": "true", // whether the participant has accepted the challenge or not

"acceptance_date": 1426287352603, // "rejected": "false",// if a challenge has been rejected by the participant

"published": "true", // the client side only receives published challenges

"challenge_id": "id", // id of the challenge

"event_id": "id",// id of the event that this challenge belongs to "organization_id": "id", // the organization that this hosting the event and this challenge "template_id": "id",

"creation_date": 1426277204604, "start_date": 1423535190593, "end_date": 1428200790593,

"created_by": "sys", // either the default system created challenges or contains the id of a person creating the challenge

"title": "Will walk more than 2 times", // title of the challenge

"description": "This is an individual challenge for the upcoming game event",

"category": "sport",// current category challenges are {sport, academic, art, other}

"sub_category": "baseball",// here is the current settings{ sport: [baseball, basketball, football], art:[music, theater, painting], academic:[]}. More items to come "suggested_donations": "{$10,$25, $40}",// this is a suggested amount for a given challenge "challenge_stat": {

"challenge_id": "uuid", "fulfileld_count": "1",

"participants": "1",

"total_donations": "123.00",

"total_donors": "1", "asOfDate": 1433616107828,

"likes": "0",

"followers": "0"

} }]


3.7 List of Challenges For The Given Event

Request

Method URL

POST api/eventmng/eventchallenges

Type Params Values

POST

POST

POST POST

session device_id isMob event_id

string

string

string string

session


device_id


isMob


Response

Status Response


code: "200" message: "success" data:[{ challenge_1},{ challenge_2}] }

session (string) – will be used with all requests data (array) – contains list of challenges for the given event

errors 508,509


data:[{ "challenge_participant_id": "id",

"type": "individual",// it can be a “team” or “individual” challenge


"default_data_value": "3",// no need on the client side

"data_value": "2",// maximum score possible for a challenge and it is always set

"score": "2", // if a challenge is fulfilled, then this field is set with respect to participant performance "score_date": 1432170611673, // the date that challenge has been fulfilled

"fulfilled": "true", //set to true if the challenge has been fulfilled, if it is false it is still in progress "fulfill_date": 1421712300000,

"accepted": "true", // whether the participant has accepted the challenge or not

"acceptance_date": 1426287352603, // "rejected": "false",// if a challenge has been rejected by the participant

"published": "true", // the client side only receives published challenges

"challenge_id": "id", // id of the challenge

"event_id": "id",// id of the event that this challenge belongs to "organization_id": "id", // the organization that this hosting the event and this challenge "template_id": "id",

"creation_date": 1426277204604, "start_date": 1423535190593, "end_date": 1428200790593,

"created_by": "sys", // either the default system created challenges or contains the id of a person creating the challenge

"title": "Will walk more than 2 times", // title of the challenge

"description": "This is an individual challenge for the upcoming game event",

"category": "sport",// current category challenges are {sport, academic, art, other}

"sub_category": "baseball",// here is the current settings{ sport: [baseball, basketball, football], art:[music, theater, painting], academic:[]}. More items to come "suggested_donations": "{$10,$25, $40}",// this is a suggested amount for a given challenge "challenge_stat": {

"challenge_id": "uuid", "fulfileld_count": "1",


"total_donations": "123.00",

"total_donors": "1", "asOfDate": 1433616107828,

"likes": "0",

"followers": "0" }

}]


3.8 List of Participants For The Given Challenge

Request

Method URL

POST api/eventmng/ch/participants

Type Params Values

POST

POST

POST POST

session device_id isMob challenge_id

string

string

string string

session


device_id


isMob


challenge_id

to retrieve participants of this challenge

Response

Status Response


code: "200" message: "success" data:[{ participant_1},{ participant_2}] }


data (array) – contains list of participants for the for the

given challenge

errors 508,509

"data": {


"participant": [

{

"participant": {

"num_challenges": "1",

"num_achievements": "1",

"total_amount_support": "123.50",

"num_donors": "1",

"num_followers": "1",

"num_likes": "1",

"isFollowed": "true",

"isLiked": "false",

"teams": [

{

"team_id": "c4487f5b-b6fb-4451-a609-a0ac6a6739f4",

"team_name": "VA Boys Baseball",



"organization_id": "9a5add5b-3c9a-4575-a366-12ea2ce1af66"

},

{

"team_id": "c07a7d3c-2252-4102-9d75-ef5784c56388",

"team_name": "Biology Club",

"team_type": "academic",

"team_description": "The Biology Club provides opportunities for

students to share and promote interest in the biological sciences. Activities include preparing

and presenting experiments and technical information before groups and sharing information about

career, technical training, and college opportunities.",


}

],

"first_name": "",

"last_name": "",

"group_id": "",

"admin_flag": "false",

"followed": "true",

"liked": "false",

"participant_id": "1cd7c002-cecae36eb7d"

}

}

]

}


3.9 List of Challenge For The Given Challenge Id

Request

Method URL

POST api/eventmng/ch/{id}

Type Params Values

HEAD HEAD GET

Authorization device

id

string

string

string

Authorization

This value is the same as session token being used in other service calls. It is

case sensitive and has to be set as “Authorization” in the header of the http

request and its value is the current session token received by last

authentication request

device


id

To retrieve complete challenge info for this challenge id

Response

Status Response


code: "200" message: "success" data:{ "challenges":[]}


data (array) – contains complete challenge for the given

challenge id

errors 508,509

{

"session": "eceb1f20-5612-4c1d-b3ad-a420b09618a7",


"code": "200",

"message": "success",

"data": {

"challenges": [

{

"challenge_id": "60793037-5dfd-41e0-b0a5-76d088f4c57d",

"event_id": "85a1bbeb-c9e8-4d4d-83a3-01fcaeecbe9b",

"template_id": "3d654e96-99c8-4f55-be80-b9a6ae39c699",

"data_value": " 5",

"created_on": 1450731645546,

"created_by": "c3cc2592-f6a9-4c02-91af-d1176a77e9d1",

"start_date": 1453525200000,

"end_date": 1461128400000,

"ch_type": "individual",

"category": "sport",

"title": "Innings pitched 5",

"description": "Accomplished by the pitcher successfully producing three outs on the

defensive turn of the team. Innings can also be represented in fractions such as 1/3 and 2/3

representing 1 out and 2 outs in the inning, respectively.\n",

"logo_url": "http://company.com/_cmimgs/ch-sport-bbb.png",

"sub_category": "baseball",

"added_by": "sys",

"creation_date": 1438714988817,

"ch_template_id": "3d654e96-99c8-4f55-be80-b9a6ae39c699",

"suggested_donations": "{$5}",

"default_data_value": "5",

"organization_id": "9a5add5b-3c9a-4575-a366-12ea2ce1af66",

"isPublished": "true",

"isLiked": "false",

"isFollowed": "false",

"challenge_stat": {

"challenge_id": "60793037-5dfd-41e0-b0a5-76d088f4c57d",

"fulfileld_count": "0",


"total_donors": "0",

"asOfDate": 1458192313663,

"likes": "0",

"followers": "0"

},

"participantList": [],

"status": "In Progress",

"tags": "high school,individual,non-profit,baseball,sport"

}

]

}

}

3.10 List of Participants

To retrieve a list of active participants and can be filtered by organization id


Request

Method URL

GET api/usrmng/participants

Type Params Values

HEAD

HEAD

GET GET

Authorization device oid max

string

string string (optional) int (optional)

Authorization


device



oid

If this value is set the participant result set will be filtered by the given

organization id

max

This filed sets the max number of records to retrieve. If not provided the

default is 50 records.


Response

Status Response


code: "200" message: "success" data:[{ participant_1},{ participant_2}] }


data (array) – contains list of participants

errors 508,509,510


4. User Follow & Like

4.1 Follow an Organization

A user can follow and unfollow an organization to receive notification and updates about it.

Request

Method URL

POST api/usrmng/followorg

Type Params Values

POST

POST

POST

POST POST

session device_id isMob organization_id follow

string

string

string string boolean

session


device_id


isMob


follow

Set either true or false to follow and unfollow an organization

Response

Status Response

200 { session: "2bd21a01-228f-490d-8a84-

81eccedfc553" code: "200" message: "success" }


errors 508,509,515


4.2 Like an Organization

A user can like and unlike an organization to receive notification and updates about it.

Request

Method URL

POST api/usrmng/likeorg

Type Params Values

POST

POST

POST

POST POST

session device_id isMob organization_id like

string

string


session


device_id


isMob


like

Set either true or false to like and unlike an organization

Response

Status Response


code: "200" message: "success" }


errors 508,509,515

50 This document is property of MohammadAli Sazegarnejad and subject to copyright law. Unauthorized use is prohibited.

4.3 Follow an Event

A user can follow and unfollow an event to receive notification and updates about it.

Request

Method URL

POST api/usrmng/followevent

Type Params Values

POST

POST

POST

POST POST

session device_id isMob event_id follow

string

string string string boolean

session


device_id


isMob


follow

Set either true or false to follow and unfollow an event


Response

Status Response




errors 508,509,515


4.4 Like an Event

A user can like and unlike an event.

Request

Method URL

POST api/usrmng/likeevent

Type Params Values

POST

POST

POST

POST POST

session device_id isMob organization_id like

string

string


session


device_id


isMob


like

Set either true or false to like and unlike an event


Response

Status Response

200 { session: "2bd21a01-228f-490d-8a84-



errors 508,509,515


4.5 Follow a Participant

A user can follow and unfollow a participant to receive notification and updates about it.

Request

Method URL

POST api/usrmng/followparticipant

Type Params Values

POST

POST

POST

POST POST

session device_id isMob participant_id follow

string

string


session


device_id


isMob


follow

Set either true or false to follow and unfollow a participant


Response

Status Response

200 { session: "2bd21a01-228f-490d-8a84-



errors 508,509,515


4.6 Like a Participant

A user can like and unlike a participant.

Request

Method URL

POST api/usrmng/likeparticipant

Type Params Values

POST

POST

POST

POST POST

session device_id isMob participant_id like

string

string


session


device_id


isMob


like

Set either true or false to like and unlike a participant


Response

Status Response

200 { session: "2bd21a01-228f-490d-8a84-



errors 508,509,515


4.7 Follow a Challenge

A user can follow and unfollow a challenge to receive notification and updates about it.

Request

Method URL

POST api/usrmng/followchallenge

Type Params Values

POST

POST

POST

POST POST

session device_id isMob challenge_id follow

string

string


session


device_id


isMob


follow

Set either true or false to follow and unfollow a challenge


Response

Status Response




errors 508,509,515


4.8 Like a Challenge

The authenticated user can like and unlike a challenge.

Request

Method URL

POST api/usrmng/likechallenge

Type Params Values

POST

POST

POST

POST POST

session device_id isMob challenge_id like

string

string


session


device_id


isMob


like

Set either true or false to like and unlike a challenge


Response

Status Response




errors 508,509,515


5. Messages & Notifications

5.1 Message & Notification Count

This service call is based on GET method and provides count of messages with not action

(not rejected nor accepted) and unread notifications.

Request

Method URL

GET api/ msgsrvc/counts

Type Params Values

HEAD

HEAD


string

string

Authorization


device


Response

Status Response


code: "200" message: "success", data:{ {"msgCount":"1","noteCount":"6"}} }


data (object) – will contain message &

notification count

errors 508,509

{"session":"session_id","code":"200", "message":"success", "data":{"msgCount":"1","noteCount":"6"}}


5.2 List of Messages

Gets list of last 100 messages for the authenticated user

Request

Method URL

POST api/msgsrvc/allmsg

Type Params Values

POST

POST

POST


string

string

string

session


device_id


isMob


Response

Status Response

200

{ session: "2bd21a01-228f-490d-8a84-

81eccedfc553" code: "200" message: "success",

data:[] } session (string) – will be used with all

requests

errors 508,509,515


"data": [

{

"message_id": "id", "message_subject": "Will walk more than 1 times",

"message_body": "This is an individual challenge for the upcoming game event",

"recipient": "id",

"creation_date": 1433277999862, "sender_id": "id",

"sender_name": "Brian Green",

"read": "false", "data": "{"cpid":"55d7f2b1-c4a1-44ee-ba30-37a843b2bfc2","cid":"b5db5686-86ba-4c47-be1533de12eccd13"}",

"accepted": "false", "rejected": "false",

"last_sent": 1433741775413

}]


5.3 Accept a Message

User will be able to accept or reject a challenge

Request

Method URL

POST api/msgsrvc/acceptmsg

Type Params Values

POST

POST

POST

POST

session device_id isMob data

string

string string object

data:{“message_id”:”id”,

“accepted”:”true|false”}

session


device_id


isMob


data

This is an object that contains a message id and the answer from the user if the challenge has been accepted or not (true or false)

Response

Status Response


code: "200" message: "success", }


errors 508,509


"data": [

{

"message_id": "id",

"message_subject": "Will walk more than 1 times",

"message_body": "This is an individual challenge for the upcoming game event", "recipient": "id",

"creation_date": 1433277999862,

"sender_id": "id", "sender_name": "Brian Green",

"read": "false",

"data": "{"cpid":"id","cid":"id"}",

"accepted": "false", "rejected": "false",

"last_sent": 1433741775413

}]


5.4 Delete a Message

The authenticated user will be able to delete a message

Request

Method URL

POST api/msgsrvc/delmsg

Type Params Values

POST

POST

POST

POST

session device_id isMob message_id

string

string

string string

session


device_id


isMob


Response

Status Response


code: "200" message: "success",

} session (string) – will be used with all

requests

errors 508,509


5.5 Seen Messages

Once a list of messages are viewed by the authenticated user, this call will mark all the seen messages by the user as seen/read.

Request

Method URL

POST api/msgsrvc/seenmsg

Type Params Values

POST

POST

POST

POST


string

string

string array

[“msg_id1”, “msg_id2”,…]

session


device_id


isMob


data

This contains a list of message_ids that the authenticated user has seen and will be marked as read.

Response

Status Response


code: "200" message: "success",

} session (string) – will be used with all

requests

errors 508,509


5.6 List of Notifications

To retrieve all notification for the authenticated user (last 100)

Request

Method URL

POST api/msgsrvc/allnotes

Type Params Values

POST

POST

POST


string string

string

session


device_id


isMob


Response

Status Response

200

{ session: "2bd21a01-228f-490d-8a84-81eccedfc553"

code: "200" message: "success", data:[] }


data (array) – list of notifications

errors 508,509


"data": [

{

"notification_id": "ba996145-c5a1-48a4-bfa3-d053401d3ee0",

"recipient_id": "55d7f2b1-c4a1-44ee-ba30-37a843b2bfc2", "title": "Will walk more than 2 times",

"body": "J. Smith 'Will walk more than 2 times'",

"creation_date":1432170813259, "read": "false",

"data":

"{\"cpid\":\"1c4dca626bfb4082a953e58f582124568\",\"cid\":\"1c4dca626bfb4082a953e58f58217f31234\"}", "created_date": 1432170813259 } ]


5.7 Seen Notifications

Once a list of notifications are viewed by the authenticated user, this call will mark all the seen notifications by the user as seen/read.

Request

Method URL

POST api/msgsrvc/seennotes

Type Params Values

POST

POST

POST

POST


string

string

string array

[“note_id1, note_id2,…”]

session


device_id


isMob


data

This array contains a list of notification_ids that the authenticated user has seen and will be marked as read.

Response

Status Response


code: "200" message: "success", }


errors 508,509


6. Search & Trends

6.1 Searching all entities

This service call is based on GET method and provides varieties of search options. Request

Method URL

GET api/searchsrvc/searchall

Type Params Values

HEAD

HEAD

GET

GET

GET

GET

Authorization device keyword org_id cat max

string

string

string

string (optional) string (optional) integer(optional)

Authorization

This value is the same as session token being used in other service calls. It is case sensitive and has to be set as “Authorization” in the header of the http request and its value is the current session token received by last


device


keyword

It can contains at least three character for processing. Otherwise an empty list will return. Search keyword may contain name of student, organization, title/description of events and challenges as well as name of state, city or zipcode.

org_id

This is an optional value. If it is set, all the scope of search will change to be within the given organization; otherwise, the search is done globally

cat

This is an optional value. Possible values available are “org”, “event”,

“challenge” and “participant”. If it is not set, the search will look into all of these categories. If it is set, then the will be conducted for the provided category


max

This value is an optional value. The value range for this is 5 to 20 records.

Sets the limit for the records in the search result.

Response

Status Response

200



session (string) – will be used with all requests data (object) – will contain 4 arrays

errors 508,509,515

"data": {

"users": [],


"events": [],

"challenges": []

}

i.e. example:

Request: searchsrvc/searchall?keyword=adr+tomm+baseball+Saturn

Result data:

"data": {

"users": [

{



"total_amount_support": "123.00",

"num_donors": "1",


"num_likes": "1",

"teams": [

{

"team_id": "c4487f5b-b6fb-4451-a609-a0ac6a6739f4",

"team_name": "VA Boys Baseball",




}

],


"last_name": "Smith",

"participant_id": "1cd7c002-7624-489c-bf16-8cecae36eb7d"


},

{



"total_amount_support": "null",

"num_donors": "0",


"num_likes": "0",

"first_name": "Patrick",

"last_name": "Rice",

"participant_id": "2bf2ce6a-5a3b-4384-b5ff-945966aa36c8"

}

],

"organizations": [

{

"organization_id": "9a5add5b-3c9a-4575-a366-12ea2ce1af66",

"name": "Saturn High School",

"primary_contact_name": "Brian Green",

"address_1": "14830 South Van Ness Avenue",

"city": "Denver",

"state": "CA",

"zipcode": "90249",

"gps_latitude": "0.0",

"gps_longitude": "0.0",

"web_url": "http://www.Saturnhs.org",

"created_by": "sys",

"creation_date": 1422637336542,

"last_updated_by": "sys",

"last_update_date": 1422637336542,

"logo_url": "https://s3.amazonaws.com/organizationassets/Saturn_denver_ca.jpeg",

"student_count": "2900",

"phone_num": "3773456789"

}

],

"events": [],

"challenges": []

}


6.2 Search Filter List

This service call is based on GET method and provides a list of tags/filter options for all

entities.

Request

Method URL

GET api/searchsrvc/filters

Type Params Values

HEAD

HEAD GET

Authorization device format

string string string(optional)

Authorization



device


format

This value sets the format the filter to be displayed as list or a categorized

breakdown list. The default is a list and possible values are:

cat: to return a categorized list by Sport, Academic, Art, etc.

list: to return total of four arrays of tags for organizations, events, challenges,

and participants

Response

Status Response




data (object) – will contain an array of arrays containing filter

tags for org, events, challenges and participants.

errors 508,509,515


6.3 Search with Filter/Tags

This service call is based on GET method and provides advanced search using list of

tags/filter options.

Request

Method URL

GET api/searchsrvc/searchbyfilter

Type Params Values

HEAD

HEAD GET GET GET GET GET GET GET GET

Authorization device c cat cid tag kw start end n

string

string string string(optional) string(optional) string(optional) string(optional) string(optional) number(optional)

Authorization


device


c

This value sets the code for the context in which the search is done as well as the list format of the result set. The possible values for c are:

100 organization

101 event

102 challenge

103 participant


cat

If a selection has been made for any of the four major categories (org, event,

challenge, or participant), this value is set to identify the type of selection and

add cid should be set to the id of the current selected object.

The possible values for cat are:

100 organization

101 event

102 challenge

103 participant

cid

This value holds the id number of the selected object which its type identified by

value of the cat.

tag

This value will have a string of existing tags, comma separated, for filtering

search results matching all tags

kw

This value has a string of search phrases in addition to filters and other provided

information

start

This value sets the beginning of a date range in format of YYYY-MM-DD

end

This value sets the end of a date range in format of YYYY-MM-DD

n

This value sets the max. number of item in the result-set

Response

Status Response




data (object) – will contain an array of arrays containing

search results as organizations, events, challenges or participants

depending of the provided code

errors 508,509,515


6.4 Recent Entities

This service call is based on GET method and provides recently added Organizations,

Events, Special Events and Challenges in the past 35 days.

Request

Method URL

GET api/trends/recent

Type Params Values

HEAD

HEAD


string

string

Authorization



device


Response

Status Response

200




errors 508,509,515


6.5 Trends

This service call is based on GET method and provides trending entities including

Organizations, Events, Special Events and Challenges sorted by number of followers or

supported donations.

Request

Method URL

GET api/trends

Type Params Values

HEAD

HEAD

GET

Authorization device filter

string

string

int

Authorization



device


filter

set either of the following values:

- 100: by num. of followers, result contains all entities - 101: by amount of support, result contains all entities* - 102: by participants with most achievements, result contains participants

only - 103: by challenges with most success rate, result contains challenges only

*Commitment is total donation received and once events and challenges are met, it will reflect on collection amount for

organizations.


Response

Status Response

200




errors 508,509,515


7. Comments

7.1 Post Comment

To post a comment for an entity such as organization, event, challenge

Request

Method URL

POST api/commentssrv/postcomment

Type Params Values

POST

POST

POST POST

session


string

string

string object

session


device_id


isMob


data

Should contain the following optional and mandatory values

i.e.: “data”:{“comment_text“:”this is a comment”, “event_id”:”id”}

comment_text: is set with the comment text. Mandatory

One of the following list should be set

organization_id: comment text will be posted to for this organization event_id: comment text will be posted to for this event

challenge_id: comment text will be posted to for this challenge


Response

Status Response

200 { session: "de6880b4-4adb-4263-92c9-2efc2d088f92"

comment_id: "3b9e6aa8-e794-4bfc-9594-

da598e819d39" code: "200" message: "Success" }

errors 508,509


8. Donations

8.1 Post Donation

To post an approved or not approved PayPal credit card transaction. (will collect unapproved/declined transactions for possible customer support follow ups)

Request

Method URL

POST api/donationsrvc/donateppcc

Type Params Values

HEAD

HEAD

POST

Authorization device data

string

string object*

Authorization



device


data

This a JSON format containing the following information:

- payment: this contains the exact response from PayPal iOS SDK after submitting a transaction. It looks like:

{

"payment": {

"id": "PAY-3AF33469GE649135YKEYTIEQ",

"create_time": "2013-03-01T23: 04: 50Z",

"update_time": "2013-03-01T23: 04: 55Z",

"state": "approved",

"intent": "sale",

"payer": {

"payment_method": "credit_card",

"funding_instruments": [

{

"credit_card": {

"type": "mastercard",

"number": "xxxxxxxxxxxx5559",


"expire_month": "12",

"expire_year": "2018",

"first_name": "Betsy",

"last_name": "Buyer"

}

}

]

},

"transactions": [

{

"amount": {

"total": "7.47",

"currency": "USD",

"details": {

"subtotal": "7.47"

}

},

"description": "Thisisthepaymenttransactiondescription.",

"related_resources": [

{

"sale": {

"id": "5YY3007569986962J",

"create_time": "2013-03-01T23: 04: 50Z",

"update_time": "2013-03-01T23: 04: 55Z",

"state": "completed",

"amount": {

"total": "7.47",

"currency": "USD"

},

"parent_payment": "PAY-3AF33469GE649135YKEYTIEQ",

"links": [

{

"href": "https:

//api.sandbox.paypal.com/v1/payments/sale/5YY3007569986962J",

"rel": "self",

"method": "GET"

},

{

"href": "https:

//api.sandbox.paypal.com/v1/payments/sale/5YY3007569986962J/refund",

"rel": "refund",

"method": "POST"

},

{

"href": "https:

//api.sandbox.paypal.com/v1/payments/payment/PAY-3AF33469GE649135YKEYTIEQ",

"rel": "parent_payment",

"method": "GET"

}

]

}

}

]

}


],

"links": [

{

"href": "https: //api.sandbox.paypal.com/v1/payments/payment/PAY-

3AF33469GE649135YKEYTIEQ",

"rel": "self",

"method": "GET"

}

]

}

}

- donor_id: user id of the donor

- anonymous: true|false if it is a considered anonymous donation or not.

- option_code: this the check-out option for donor to decide what to when a challenge is not met. For now we have the following options:

o 11: Support the challenge regardless of the outcome

o 12: Support similar successful challenge with the same school

o 13: Support the school

- items: contains an array of shopping cart entries in form of JSON. Each item has:

o type: determines the type of each item with the following values:

▪ 100: organization

▪ 101: event

▪ 102: challenge

▪ 103: challenge_participant

▪ 104: participant

o id: contains the id of the given type object(i.e. organization_id,

event_id etc)

o ch_id: contains challenge id and it is set only if the item type is a participant(type=103).

o amount: dollar amount set for this entry.

{

"type": "103",

"ch_id": "",

"id": "id",

"amount": 50

}

All together: { "data": { "payment": {}, "option_code": 11, "items": [ { "type": "103", "ch_id": "",

"id": "id", "amount": 50


} ] } }

Response

Status Response

200 { session: "session_id"

code: "200" message:

"success" data: []

data (object) – will contain the payment conf. as an acknowledgement of success **it is recommended to store a copy processed tx till this

confirmation message is received( in case of loss of

network connection)

errors 508,509,524

{

"session": "session_id",

"code": "200",


"data": {

"payment_conf": "PAY-3AF33469GE"

}

}


8.2 Post Donation

To post an approved or not approved PayPal account transaction. (will collect unapproved/declined transactions for possible customer support follow ups)

Request

Method URL

POST api/donationsrvc/donateppacc

Type Params Values

HEAD

HEAD

POST

Authorization device data

string

string object*

Authorization



device


data

This a JSON format containing the following information:

- payment: this contains the exact response from PayPal iOS SDK after submitting a transaction. It looks like:

{

"payment": {

{

"client": {

"environment": "sandbox",

"product_name": "PayPal iOS SDK",

"paypal_sdk_version": "2.11.1",

"platform": "iOS"

},

"response_type": "payment",

"response": {

"id": "PAY-24W68931YR095290LKXBFK6A",

"state": "approved",

"create_time": "2015-08-05T18:27:04Z",

"intent": "sale"

}


}

}

- donor_id: user id of the donor

- anonymous: true|false if it is a considered anonymous donation or not.

- option_code: this the check-out option for donor to decide what to when a challenge is not met. For now we have the following options:

o 11: Support the challenge regardless of the outcome

o 12: Support similar successful challenge with the same school

o 13: Support the school

- items: contains an array of shopping cart entries in form of JSON. Each item has:

o type: determines the type of each item with the following values:

▪ 100: organization

▪ 101: event

▪ 102: challenge

▪ 103: challenge_participant

▪ 104: participant

o id: contains the id of the given type object(i.e. organization_id,

event_id etc)

o ch_id: contains challenge id and it is set only if the item type is a participant (type=103).

o amount: dollar amount set for this entry.

{

"type": "103",

"ch_id": "",

"id": "id",

"amount": 50

}

All together: { "data": { "payment": {}, "option_code": 11, "items": [ { "type": "103", "ch_id": "",

"id": "id", "amount": 50 } ] } }


Response

Status Response



"success" data: []

data (object) – will contain the payment conf. as an acknowledgement of success **it is recommended to store a copy processed tx till this

confirmation message is received( in case of loss of

network connection)

errors 508,509,524

{


"code": "200",


"data": {

"payment_conf": "PAY-3AF33469GE"

}

}


8.3 Donor Donation Report

Retrieve history of payments for the current authentication user grouped by the date of payment along with itemized entities

Request

Method URL

GET api/donationsrvc/report

Type Params Values

HEAD

HEAD


string

string

Authorization


device


Response

Status Response



"success" data: []

data (object) – will contain an array of donation history for the current authenticated user

errors 508,509


{


"code": "200",


"data": {

"donations": {

"2015-08-11 04:56:22.096": [

{

"date": 1439268982096,

"user_id": "0eabc8c7-a4aa-4532-a1b2-c375bfc2314b",

"amount": 100.0,

"description": "Donation to Hills High School",

"isApproved": "true",

"methodOfPayment": "PayPalAccount",

"donatedTo": {


"events": [],

"participants": [],

"challengeParticipantInfo": [

{

"participant": {

"suggested_donations": "{$5}",


"last_name": "Smith",

"group_id": "1310",

"admin_flag": "false",

"participant_id": "1cd7c002-7624-489c-bf16-8cecae36eb7d"

},

"challenges": []

}]

}

}

}


9. System Services

9.1 Mobile Asset Retrieval

Get mobile assets such as background images, audio or videos

Request

Method URL

GET api/documentsrv/assets

Type Params Values

HEAD

HEAD

GET

Device api-key type

string string int

device


api-key

Refer to the conventions under appendix.

type

Available values are:

- 10: picture

- 11: audio

- 12: video

- 13: background image

Response

Status Response

200 { session: "session_id" code: "200" message: "success"

data: [] data (array) – list of urls corresponding to the requested asset

errors 508,509


{ "code": "200", "message": "success", "data": [ "https://s3.amazonaws.com/static-content/img/bg/fon-kosmos-30243.jpg", "https://s3.amazonaws.com/static-content/img/bg/bg-blue.jpg" ] }


Glossary

Appendix

Conventions

● Client - Client application.

● Status - HTTP status code of response.

● api - referees to the url of the host for web-services. The current url is:

● http://url:8080/masnws/rest OR https://url/masnws/rest

● api-key – for system service calls with no authentication this api-key is used as a header parameter.

bf7646b2-f27c-4c65-8809-4e4e69e502c6cb4a62e6-0fed-45bb-9d35-c68d4c6df0a2

● Organization - you may see school or organization are being used interchangeably. In all request

responses term organization is being used

● Participant – if a user is a student and there are related items to student such as events or challenge, the

term participant is used.

● All the possible responses are listed under ‘Responses’ for each method. Only one of them is issued per

request server.

● All response are in JSON format.

● All request parameters are mandatory unless explicitly marked as [optional]

● All values are sample data, but data structures are valid

Status Codes

All status codes are standard HTTP status codes. The below ones are used in this API.

2XX - Success of some kind

5XX - Error occurred in server’s part

Status Code Description

200 OK

501 Account is not activated. Please check your email for activation link

502 Account is locked. Please contact support.

503 Account is disabled. Please contact support.

504, 505 invalid password

506 invalid user name/ Invalid Email address.

507 Login failed. please contact support

http://url:8080/masnws/rest


508 Internal Server Error and operation failure

509 invalid authentication token (session)

510 User is not authorized.

513 failed to remove organization from user profile

514 Please choose a different username. Duplicate username

515 cannot locate the user

516 User sign out failed

517 Incomplete user information

518 Account activation failed

524 Donor Identity Mismatch

525 Duplicate payment conf. code.

526 Invalid Credentials.

527 If you have an account with us, please try again using your account.


Entity Structure

Here is a list of all major entities used in the Responses as JSON format:


System Structure


Initial Design:


Scale up design:

Availability Zone #1

Elastic Load

Balancing Elastic Load

Balancing

Amazon

Route

Auto Scaling group

security group

web app server

Auto Scaling group

security group

API app server

Slave RDS DB

instance standby (multi-AZ)

RDS DB instance

read replica Master

database

Auto Scaling group

security group

Processing

App Server

User Authentication

Management

Auto Scaling group

security group

Plugin API Server

S3 File/Log

Storage

client mobile client Internet

Message Queue

Web Services API Specification Docfedora.cis.cau.edu/~asazegar/_profile/assets/WS... · 1...

Documents

Transcript of Web Services API Specification Docfedora.cis.cau.edu/~asazegar/_profile/assets/WS... · 1...