Skip to content

API Documentation

Jump to bottom
Isaac Dontje Lindell edited this page Dec 13, 2013 · 9 revisions

###API

The API is made up of a series of JSON endpoints that can be utilized to do all operations related to creating, presenting, editing, and removing surveys.

The base URL is %host%/.

API methods
/addQuestions
/createSurvey
/deVote
/getSurveyInfo
/getSurveyResults
/removeQuestion
/vote

####/addQuestions

POST request body:

{ 
  "surveyId": 1, 
  "questions": [
                 {
                   "question": "Which is best?", 
                   "type": "MCSR",
                   "answers": ["Puppies", "Cheese", "Joss Whedon", "Naps"]
                 }
               ],
  "password": "supersecretpassword" 
}

POST response body:

{"status": "success"}

Possible Errors:

  • 404 Not Found: questionId does not exist - returned when the specified questionId does not exist in the database

back to top

####/createSurvey

Sends information needed to create a new survey. Returns the new survey ID.

POST request body:

{ 
  "title": "Because clickers are SO 1999.", 
  "questions": [
                 {
                   "question": "Which is best?", 
                   "type": "MCSR",
                   "answers": ["Puppies", "Cheese", "Joss Whedon", "Naps"]
                 }
               ],
  "password": "supersecretpassword"
}

Note that the attribute type of a question object can by any one of {"MCSR", "MCMR", "MCRANK", "FR"}

POST response body:

{"surveyId": 2}

back to top

####/deVote

Removes a vote from the database. This will be used if/when a user changes their vote.

POST request body:

{"questionId" : 1, "answerId": 3}

POST response body:

{"status": "success"}

Possible errors:

  • 400 Bad Request: questionId and answerId don't match - returned when the specified answerId isn't associated with the specified questionId.

back to top

####/getSurveyInfo

Gets all information needed to present a survey to the user. Requires a survey ID, responds with all survey data.

GET request body:

{"surveyId" : 2}

GET response body:

{ 
  title: "A sweet survey",
  questions: [
               { 
                 "id":12,
                 "value": "What is your favorite color?",
                 "type": 'MCSR',
                 "answers": [
                              {id:45, value:"blue"},
                              {id:32, value:"red"}
                            ] 
               },
               { 
                 "id": 14,
                 "value": "What is your favorite food?",
                 "type": "MCSR",
                 "answers": [
                              {id:21, value:"pizza"},
                              {id:18, value:"cake"},
                              {id:12, value:"brains"}
                            ]
               }
             ]
}

Possible Errors:

  • 404 Not Found: Non-existent survey ID - returned when requesting info for non-existent survey ID

back to top

####/getSurveyResults

Get the results of a survey. The returned data contains a count of the votes for each answer. Note that the answers in the result of this call are not separated by question; it's assumed that the client already has that information from a call to /getSurveyInfo.

GET request body:

{"surveyId": 1}

GET response body (object keys are answerIds, object values are a count of the number of votes for that answer) :

{
  1: 13,
  2: 21,
  3: 12
}

Possible Errors:

  • 404 Not Found: Non-existent survey ID - returned when requesting results for non-existent survey ID

back to top

####/removeQuestion

POST request body:

{"questionId": 3}

POST response body:

{"status": "success"}

back to top

####/vote

Record a vote to the database.

POST request body:

{"questionId": 1, "answerId": 3}

POST response body:

{"status": "success"}

Possible Errors:

  • 400 Bad Request: questionId and answerId don't match - returned when the specified answerId isn't associated with the specified questionId.

back to top

Clone this wiki locally