The tweaser is an API interface to creating, managing and responding to surveys. It teases end users about new features and pulls information (tweezes) out of them that we might be otherwise unable to get. Yeah, yeah I know... sorry. :D
It was written with MySQL as the backend using Buffalo, although it should support any database backend supported by Buffalo. The tweaser doesn't have a frontend component. That's on you to implement. Currently, all administrative functions are managed through the /v1/tweaser/admin/* routes and authenticated with a PSK. Responses are authenticated by a token generated by combining the user's ID, the ID of the question and a secret known only to the tweaser. Responses are just posted to /v1/tweaser/responses/{question_id}.
The tweaser has a fairly hierarchical database model with Campaigns, Questions, Answers, and Responses.
Campaigns are a logical collection of survey questions wrapped with a start date and an end date. They also have a property to enable/disable the campaign without changing the dates. A campaign has_many questions.
Questions are the main construct that responders will interface with. Questions have the text of the question, and a type (single, multi, input) and can be enabled/disabled. A question belongs_to a campaign and has_many answers.
Answers are the predefined responses to a question. Answers are created administratively and have text and a type (input, or choice). Answers can be enabled/disabled. An answer belongs_to a question.
Responses are the responses to questions from users. A response is simply POST'd to the response endpoint which is authenticated with a generated token, shared via the questions list. The response may have more than one Answer or some text if the Answer type is input. Responses have a many_to_many relationship with Answers and belongs_to a Question.
The most common use case for tweaser is to get a list of questions for a user_id from the /v1/tweaser/admin/questions?user_id=someguy endpoint. This endpoint will return all Questions that are enabled and are in an enabled and active Campaign where the user_id has not yet responded. The questions will be returned with all related Answers to make it easy to build a form from one or more of the returned questions. Each question will also be returned with a unique token used to authenticate the response. Getting a list of questions for a user_id is currently an administrative function and needs to be done serverside with the administrative X-Auth-Token header PSK.
GET http://127.0.0.1:3000/v1/tweaser/admin/questions?user_id=someguy
[
{
"id": "1ab31a6b-855d-42eb-8819-d3dbd290a0e9",
"created_at": "2018-08-28T21:44:51Z",
"updated_at": "2018-08-28T21:44:51Z",
"text": "What is the next feature you would like to see implemented?",
"campaign_id": "9f4e25dd-7c63-4642-bb90-5fed30535ee9",
"enabled": true,
"answers": [
{
"id": "6c84b473-3640-4a11-b74b-ad7e97c76f51",
"created_at": "2018-08-28T21:44:51Z",
"updated_at": "2018-08-28T21:44:51Z",
"text": "container service",
"enabled": true,
"question_id": "1ab31a6b-855d-42eb-8819-d3dbd290a0e9"
},
{
"id": "7914d679-3c1e-4281-8de6-3a007b42badd",
"created_at": "2018-08-28T21:44:51Z",
"updated_at": "2018-08-28T21:44:51Z",
"text": "serverless computing",
"enabled": true,
"question_id": "1ab31a6b-855d-42eb-8819-d3dbd290a0e9"
},
{
"id": "c0fb2383-ae5e-4ca9-97f9-61c4a2f703ff",
"created_at": "2018-08-28T21:44:51Z",
"updated_at": "2018-08-28T21:44:51Z",
"text": "standalone databases",
"enabled": true,
"question_id": "1ab31a6b-855d-42eb-8819-d3dbd290a0e9"
}
],
"type": "single",
"token": "JDJhJDEwJFBJaGZOenE3WVF3SmlHMXFFTHFQT09KeGw5RktETlZyR3I4YlpXL1dEYXpUQ1FhYVcxYTll"
},
{
"id": "ef106c97-9295-4f3e-8138-ba2be26deeca",
"created_at": "2018-08-28T21:44:51Z",
"updated_at": "2018-08-28T21:44:51Z",
"text": "How do you feel about enabled free form questions?",
"campaign_id": "d2c69373-43b8-4ac3-8993-66ac60b2c4a8",
"enabled": true,
"type": "input",
"token": "JDJhJDEwJE84cHczL1RqYjZwdWI5ZFBVRFVuUHVyWnVvcHZxTVRjM1VLMTJSZjZTVzFySjZEZjJJSDhh"
}
]
The /v1/tweaser/responses endpoint is used for posting responses to the Tweaser. Authentication is done with the generated token for the question as a query parameter for the POST.
POST http://127.0.0.1:3000/v1/tweaser/responses?token=JDJhJDEwJFBJaGZOenE3WVF3SmlHMXFFTHFQT09KeGw5RktETlZyR3I4YlpXL1dEYXpUQ1FhYVcxYTll
{
"question_id": "1ab31a6b-855d-42eb-8819-d3dbd290a0e9",
"user_id": "someguy",
"answers": [{ "id": "6c84b473-3640-4a11-b74b-ad7e97c76f51"}]
}
POST http://127.0.0.1:3000/v1/tweaser/responses?token=JDJhJDEwJE84cHczL1RqYjZwdWI5ZFBVRFVuUHVyWnVvcHZxTVRjM1VLMTJSZjZTVzFySjZEZjJJSDhh
{
"question_id": "ef106c97-9295-4f3e-8138-ba2be26deeca",
"user_id": "someguy",
"text": "They make me super happy!"
}
TODO
E. Camden Fisher camden.fisher@yale.edu
The MIT License (MIT)
Copyright (c) 2022 Yale University
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.