readme.md

Survey Storage

A flexibile survey storage service. Allows you to create new surveys by describing the fields used in the survey. Surveys can then be answered, where each answer is stored alongside the ip that sent in the answer (limited to IPv4). Survey answers can be accessed as a CSV export.

Creating a survey

Surveys are defined using a JSON document. Such a document can contain the following keys

Key	Type	Description
fields	array, object	definition of fields and values to accept (required)
labels	array	Can be used to specify nicer labels when exporting

Field definitions

The fields-key can either be a simple whitelist array, e.g.

{
  "fields": ["name", "gender", "weight"],
  "labels": {"weight": "Vægt (kg)"}
}

...or it can be a map of definitions for each field:

{
  "fields": {
    "name": {"is_required": true, "is_public": true},
    "gender": {"type": "enum", "values", ["M", "F"]},
    "weight": {"type": "int"}
    "misc": {}
  }
}

Field types

Type		Description
enum	values:["A", "B", "C"]	list of predefined values (whitelist)
int		Value is converted into an integer - discarded if integer conversion fails
boolean	true/false	Boolean value

API visibility, required

Type	Description
is_required	Field must be provided. Default: false
is_public	Expose field to the API. Default: false

Code sample

Here is a snippet to create a new survey. Notice: no trailing slash in the URL.

Command line:

curl -X PUT -H 'content-type: application/json' -d '{"fields": { "name": {"is_required": true}}, "gender": { "type": "enum", "values": ["M", "F", "N/A"]}}' /surveys

Javascript:

$.ajax({
  type: "PUT",
  contentType: "application/json;",
  url: "/surveys",
  data: JSON.stringify({
    fields: ["name", "gender"]
  }),
  success: function(data) {
    console.log(data.survey_id);
  },
  error: function(xhr) { /../ }
});

And with field definitions:

$.ajax({
  type: "PUT",
  url: "/surveys",
  contentType: "application/json;",
  data: JSON.stringify({
    fields: {
      name: {
        is_required: true
      },
      weight: {
        type: "int"
      },
      gender: {
        type: "enum",
        values: ["M", "F"]
      }
    }
  }),
  success: function(data) {
    console.log(data.survey_id);
  },
  error: function(xhr) { /../ }
});

Post a response

POST /surveys/:survey_id/answers

Code sample

Command line:

curl -X POST -H 'content-type: application/json' -H 'x-forwarded-for: 10.10.10.10' -d '{"name":"John Doe", "weight": "188"}' /surveys/:survey_id/answer

Javascript:

$.ajax({
  url: "/surveys/:survey_id/answers",
  data: JSON.stringify({
    name: "John Doe",
    gender: "M"
  }),
  contentType: 'application/json;',
  type: "POST",
  error: function(xhr) {console.log(xhr.responseText) }
});

Delete a response

DELETE /surveys/:survey_id/answers/:answer_id

Command line:

curl -X DELETE /surveys/lq3h0u/answers/42

Javascript:

$.ajax({
  url: "/surveys/lq3h0u/answers/42",
  contentType: 'application/json;',
  type: "DELETE",
  success: function() { /../}
});

List all entries

Paginate if content is too big to display in one go. Pagesize is configurable via config.api.pagesize.

GET /surveys/:survey_id/json?page=2

Filter responses

Fetch entries newer than an answer with a given id (12).

GET  /surveys/:survey_id/json?after_id=12

Show stats

Display number of recent/total entries for a survey.

GET /surveys/:survey_id/stats

Export all entries (CSV)

GET /surveys/:survey_id/export

---