Page Comparison

...

• Choose one

• Choose multiple

• Required (A question shouldn’t be asked if it’s not required.)

• Skippable (Would at least require an opt-out.)

• Explicitly opt-out (Are there times when a “Do not wish to answer” option is presented?)

• Other as option (would write-in ever be useful?)

Possible Endpoints:

• v3/participant/{userId}/demographics

  • POST - Create demographics

    • Expects list of demographics for the userId given in the path

      Code Block
      language json
      {[ { "category": "education", "value": "kinder" }, { "category": "height", "value": 30 }, { "category": "language", "value": ["english", "spanish"] } ]}

    • Alternatively, could have the create only add one demographic at a time. Seems better to do it in a list and reduce the requests necessary to the server.

  • GET - Get all demographics for

  list of categories? Enumerated values? Might not be necessary if those are determined by the app config.GET or POST to query stored demographic data. Seems like it

  • a participant

    • Would return a list like the one sent in a “create” request.

• v3/participant/{userId}/demographics/update

  • POST - Update demographics

    • If versioning is not required, then this route is probably not necessary. The “create” route could just update any existing categories.

    • Expects a single demographic (could be a list but it seems less likely that multiple will be submitted on an update)

      Code Block
      language json
      { "category": "education", "value": "grad" }

• v3/participant/{userId}/demographics/{category}

  • GET - Get participant demographic

    • Would only be able to return one demographic category

  • DELETE - Delete demographic

    • Delete a single demographic category record for a participant

• v5/study/{studyId}/participants/demographics/search

  • GET - Get a list of demographics based on query parameters

    • The returned list could be a paged resource list to handle the possible size.

    • This might need to be a POST route instead, allowing for

  the convenience of formatting it in JSON. (Self endpoint?)

• POST to create (or update?) user’s demographics.

• DELETE (not sure this is useful, maybe for testing)

  • • more detailed requests. (For instance, if the requester wanted the demographics of 50 specific users by passing in their IDs)

• v5/study/{studyId}participants/demographics/summary

  • GET - Get a summary of demographic totals for a study

    • Returns categories with values mapped to totals.

      Code Block
      language json
      { "education": { "kinder": 5, "grad": 8 }, "height": { "30": 4, "40": 3, "50": 6 }, "language": { "spanish": 8, "english": 7, "french": 5 } }

    • This would be easiest to implement if it calculated totals on request, harder if it tracks and updates totals during other requests.

• GET for list of categories? Enumerated values? Might not be necessary if those are determined by the app config.

Q: How do we decide what is too specific? Is it a population cutoff? As in some combination of answers could represent a group of less than 50 people?

...

Q: Is there a way to make the data easier to query for groups (get all participants with English language, Veteran, 123 postal code)? Is that even an expected use case?

Q: Is there a need for version tracking when updating demographics? For instance, if a participant moves from one country to another and updates their country code, would keeping a record or their initial country code and date be necessary?

Config:

"bridge:demographics": {
  "education": {
    "type": "enum",
    "values": ["kinder","pre","grad"],
    "format": "1"
  },
  "height": {
    "type": "int",
    "max": 120,
    "min": 12,
    "format": "1"
  },
  "language": {
    "type": "enum",
    "values": ["english","spanish","french"],
    "format": "+"
  }
}

POST body:

{[
  {
    "field":
"education",     "value": "kinder"
  },
  {
    "field":
"height",
    "value": 30
  },
  {
    "field": "language",
    "value": ["english", "spanish"]
  }
]}

Data:

...