Pollo

Documentation for Pollo

General

Generate a group code

GET http://pollo-backend.cornellappdev.com/api/v2/generate/code/

Headers

NameTypeDescription

Authentication

string

'Bearer ' + accessToken

{
    success: true,
    data: {
        code: string
    }
}

Drafts

type Draft {
    id: number,
    createdAt?: number,
    text: string,
    options: string[]
}

If options are empty, assume free response question.

Get all drafts for a user

GET http://pollo-backend.cornellappdev.com/api/v2/drafts/

Headers

NameTypeDescription

Authentication

string

'Bearer ' + accessToken

{
    success: true,
    data: List<Draft>
}

Create a draft

POST http://pollo-backend.cornellappdev.com/api/v2/drafts/

Query Parameters

NameTypeDescription

text

string

options

array

string[]

Headers

NameTypeDescription

Authentication

string

'Bearer ' + accessToken

{
    success: true,
    data: <Draft>
}

Update a draft

PUT http://pollo-backend.cornellappdev.com/api/v2/drafts/:id

Path Parameters

NameTypeDescription

id

string

Query Parameters

NameTypeDescription

text

string

options

array

string[]

Headers

NameTypeDescription

Authentication

string

'Bearer ' + accessToken

{
    success: true,
    data: <Draft>
}

Delete a draft

DELETE http://pollo-backend.cornellappdev.com/api/v2/drafts/:id

Path Parameters

NameTypeDescription

id

string

Headers

NameTypeDescription

Authentication

string

'Bearer ' + accessToken

{
    success: true,
    data: null
}

Groups

type Group {
    id: number,
    name: string,
    code: string,
    updatedAt: number,
    isLive: boolean
}

Previously known as Session.

Create a group

POST http://pollo-backend.cornellappdev.com/api/v2/sessions/

Query Parameters

NameTypeDescription

name

string

code

string

Headers

NameTypeDescription

Authentication

string

'Bearer ' + accessToken

{
    success: true,
    data: <Group>
}

Get a group

GET http://pollo-backend.cornellappdev.com/api/v2/sessions/:id

Path Parameters

NameTypeDescription

id

string

Headers

NameTypeDescription

Authentication

string

'Bearer ' + accessToken

{
    success: true,
    data: <Group>
}

Get all groups

GET http://pollo-backend.cornellappdev.com/api/v2/sessions/all/:role

Path Parameters

NameTypeDescription

role

string

If role is member, this will return all groups you are in. If role is admin, this will return all groups you are an admin of.

Headers

NameTypeDescription

Authorization

string

'Bearer ' + accessToken 

{
    success: true,
    data: List<Group>
}

Each of the Group nodes has an extra field called updatedAtindicating the latest activity in Unix time & field called isLive indicating whether the group is live or not.

Update a group

PUT http://pollo-backend.cornellappdev.com/api/v2/sessions/:id/

Path Parameters

NameTypeDescription

id

string

Query Parameters

NameTypeDescription

name

string

Headers

NameTypeDescription

Authorization

string

'Bearer ' + accessToken

{
    success: true,
    data: <Group>
}

Delete a group

DELETE http://pollo-backend.cornellappdev.com/api/v2/sessions/:id/

Path Parameters

NameTypeDescription

id

string

Headers

NameTypeDescription

Authorization

string

'Bearer ' + accessToken

{
    success: true,
    data: null
}

Leave a group

DELETE http://pollo-backend.cornellappdev.com/api/v2/sessions/:id/members/

Path Parameters

NameTypeDescription

id

string

Headers

NameTypeDescription

Authorization

string

'Bearer ' + accessToken

{
    success: true,
    data: null
}

Get members

GET http://pollo-backend.cornellappdev.com/api/v2/sessions/:id/members/

Path Parameters

NameTypeDescription

id

string

Headers

NameTypeDescription

Authorization

string

'Bearer ' + accessToken

{
    success: true,
    data: List<User>
}

Get admins

GET http://pollo-backend.cornellappdev.com/api/v2/sessions/:id/admins/

Path Parameters

NameTypeDescription

id

string

Headers

NameTypeDescription

Authorization

string

'Bearer ' + accessToken

{
    success: true,
    data: List<User>
}

Add members

POST http://pollo-backend.cornellappdev.com/api/v2/sessions/:id/members/

Path Parameters

NameTypeDescription

id

string

Query Parameters

NameTypeDescription

memberIDs

array

int[]

Headers

NameTypeDescription

Authorization

string

'Bearer ' + accessToken

{
    success: true,
    data: null
}

Remove members

DELETE http://pollo-backend.cornellappdev.com/api/v2/sessions/:id/members/

Path Parameters

NameTypeDescription

id

string

Query Parameters

NameTypeDescription

memberIDs

array

int[]

Headers

NameTypeDescription

Authorization

string

'Bearer ' + accessToken

{
    success: true,
    data: null
}

Add admins

POST http://pollo-backend.cornellappdev.com/api/v2/sessions/:id/admins/

Path Parameters

NameTypeDescription

id

string

Query Parameters

NameTypeDescription

adminIDs

array

int[]

Headers

NameTypeDescription

Authorization

string

'Bearer ' + accessToken

{
    success: true,
    data: null
}

Remove admins

PUT http://pollo-backend.cornellappdev.com/api/v2/sessions/:id/admins/

Path Parameters

NameTypeDescription

id

string

Query Parameters

NameTypeDescription

adminIDs

array

int[]

Headers

NameTypeDescription

Authorization

string

'Bearer ' + accessToken

{
    success: true,
    data: null
}

Polls

type Poll {
  id: number,
  text: string,
  results: json,
  shared: boolean,
  type: string, // MULTIPLE_CHOICE OR FREE_RESPONSE
  answer: ?string[],
  correctAnswer: string
}

Answer is the user’s answer for that specific question. null if the user is the admin of the question. For multiple choice, answer is the choice. For free response, answer is an array of answer ids.

correctAnswer is the correct answer choice for multiple choice (ex. correctAnswer: 'A' ). Empty string if no correct answer selected for multiple choice or the question is free response.

Create a poll

POST http://pollo-backend.cornellappdev.com/api/v2/sessions/:id/polls/

Path Parameters

NameTypeDescription

id

string

Headers

NameTypeDescription

Authorization

string

'Bearer ' + accessToken

Request Body

NameTypeDescription

type

string

text

string

results

object

json

shared

boolean

{
    success: true,
    data: <Poll>
}

Get a poll

GET http://pollo-backend.cornellappdev.com/api/v2/polls/:id/

Path Parameters

NameTypeDescription

id

string

Headers

NameTypeDescription

Authorization

string

'Bearer ' + accessToken

{
    success: true,
    data: <Poll>
}

Get all polls for a group sorted by date (ascending)

GET http://pollo-backend.cornellappdev.com/api/v2/sessions/:id/polls/

Admin user will receive all polls Member user will receive all polls but with poll results hidden (set to {}) if poll is unshared

Path Parameters

NameTypeDescription

id

string

Headers

NameTypeDescription

Authorization

string

'Bearer ' + accessToken

{
  success: true,
  data: [ 
    {
      date: "1551846479",
      polls: [
        {
          "id": 9,
          "text": "question!",
          "results": {},
          "shared": true,
          "type": "MULTIPLE_CHOICE",
          "answer": ["A"]
        }
      ]
    }
  ]
}

Update a poll

PUT http://pollo-backend.cornellappdev.com/api/v2/polls/:id/

Path Parameters

NameTypeDescription

id

string

Headers

NameTypeDescription

Authorization

string

'Bearer ' + accessToken

Request Body

NameTypeDescription

text

string

results

string

shared

boolean

{
    success: true,
    data: <Poll>
}

Delete a poll

DELETE http://pollo-backend.cornellappdev.com/api/v2/polls/:id/

Path Parameters

NameTypeDescription

id

string

Headers

NameTypeDescription

Authorization

string

'Bearer ' + accessToken

{
    success: true,
    data: null
}

Questions

type Question {
    id: number,
    createdAt?: number,
    text: string
}

Create a question

POST http://pollo-backend.cornellappdev.com/api/v2/sessions/:id/questions/

Path Parameters

NameTypeDescription

id

string

group id

Headers

NameTypeDescription

Authorization

string

'Bearer ' + accessToken

Request Body

NameTypeDescription

text

string

{
    success: true,
    data: <Question>
}

Get a question

GET http://pollo-backend.cornellappdev.com/api/v2/questions/:id/

Path Parameters

NameTypeDescription

id

string

question id

Headers

NameTypeDescription

Authorization

string

'Bearer ' + accessToken

{
    success: true,
    data: <Question>
}

Get all questions for a group

GET http://pollo-backend.cornellappdev.com/api/v2/sessions/:id/questions/

Path Parameters

NameTypeDescription

id

string

group id

Headers

NameTypeDescription

Authorization

string

'Bearer ' + accessToken

{
    success: true,
    data: List<Question>
}

Get all questions for a group sorted by date (ascending)

GET http://pollo-backend.cornellappdev.com/api/v2/sessions/:id/questions/date/

Path Parameters

NameTypeDescription

id

string

group id

Headers

NameTypeDescription

Authorization

string

'Bearer ' + accessToken

{
  success: true,
  data: [
    {
      date: "1551846479",
      questions: [
        {
          id: string,
          text: string
        }
      ]
    }
  ]
}

Update a question

PUT http://pollo-backend.cornellappdev.com/api/v2/questions/:id/

Path Parameters

NameTypeDescription

id

string

question id

Headers

NameTypeDescription

Authorization

string

'Bearer ' + accessToken

Request Body

NameTypeDescription

text

string

{
    success: true,
    data: <Question>
}

Delete a question

DELETE http://pollo-backend.cornellappdev.com/api/v2/questions/:id/

Path Parameters

NameTypeDescription

id

string

question id

Headers

NameTypeDescription

Authorization

string

'Bearer ' + accessToken

{
    success: true,
    data: null
}

Users

type User {
  id: number,
  name: string,
  netID: string
}

Get me

GET http://pollo-backend.cornellappdev.com/api/v2/users/

Headers

NameTypeDescription

Authorization

string

'Bearer ' + accessToken

{
    success: true,
    data: <User>
}

Authentication

type UserSession {
  accessToken: string,
  refreshToken: string,
  sessionExpiration: number,
  isActive: boolean
}

If invalid accessToken is passed into request header, 401 error is thrown.

Authenticate mobile

POST http://pollo-backend.cornellappdev.com/api/v2/auth/mobile

Request Body

NameTypeDescription

idToken

string

{
    success: true,
    data: <UserSession>
}

Refresh session

POST http://pollo-backend.cornellappdev.com/api/v2/auth/refresh/

Headers

NameTypeDescription

Authorization

string

'Bearer ' + refreshToken

{
    success: true,
    data:<UserSession>
}

Socket Protocol

Built with Socket.io. Documentation found here.

Socket Connection

Connect (default socket) Make sure to visit /join/session/ before joining a socket because this will create the socket if not created yet. You will need to emit userType on connect to socket. Disconnect (default socket)

Group

Rest

Method

Body

URL

Response

Description

POST

code: string and name?: string

/start/session/

Group - The group that was created, use id as a namespace

User sends to start a group

POST

id: number or code: string

/join/session/

Group

User sends to join a group

Socket

To Server

Message

Body

Description

server/poll/start

Poll object without id

Admin sends to start a poll

server/poll/end

empty

Admin sends to stop a poll

server/poll/results

empty

Admin sends to share results

server/poll/tally

Answer object without id

User sends to reveal their chosen response to the server

server/poll/upvote

{ answerID,

googleID }

User sends to upvote an answer

server/poll/delete

pollID *same as db ID

Admin sends to delete saved poll

server/poll/deleteLive

empty

Admin sends to delete live poll

To Student

Message

Body

Description

user/poll/start

{ poll: Poll object }

User receives to display a poll

user/poll/end

{ poll: Poll object }

User receives when poll has ended

user/poll/results/

CurrentState object

User receives when if admin decides to share results

user/poll/results/live

CurrentState object

User receives when there is a live FR question when user first joins socket

user/count

{ count: user count }

User receives number of live users in socket

user/poll/delete

pollID *same as db ID

User receives when poll is deleted

user/poll/deleteLive

empty

User receives when live poll is deleted

user/answer/success

empty

User receives when FR answer is successfully registered (pass filter)

user/answer/filter

{ text: string, filter: string array }

User receives when FR answer is not registered (doesn't pass filter)

To Admin

Message

Body

Description

admin/poll/start

{ poll: Poll object }

Admin receives current poll upon entry (if there is one)

admin/poll/updateTally

CurrentState object

Admin receives state of poll i.e. tallies

admin/poll/ended

{ poll: Poll object }

Admin receives when poll has been ended

user/count

{ count: user count }

User receives number of live users in socket

Type Definitions

These objects are not saved outside of a socket.

Current State

type CurrentState {
    poll: number,
    results: {},
    answers: {}, // google id to answer choice for MC and array of answer ids for FR
    upvotes: {}  // google id to array of answer ids
}

Example of results. Note: answers is a mapping of googleID to selected option.

results = {'A': {'text': 'blue', 'count': 1}, 'B': {'text': 'red', 'count': 2}}

// FR example of answer id to answer
results = {1: {'text': 'blue', 'count': 0}, 2: {'text': 'red', 'count': 2}}

Answer

type Answer {
    id: id,
    googleID: string,
    poll: id,
    choice: string,
    text: string
}

For MC: choice should be C and text should be Saturn. For FR: choice and text should be Saturn.

Poll

type Poll {
    id: number, // id doesn't correspond to poll id when saved in db
    text: string,
    type: string,
    options: ?string[],
    shared: boolean,
    correctAnswer: string
}

options is the text of the choices. If the choices are

A) Blue B) Red C) Green D)

where D is a blank option, the choices would be: 

options = ['Blue', 'Red', 'Green', '']

Poll is saved into the database after admin ends poll.

PreviousUpliftNextEatery

Last updated