Skip to content
HappyOrNot Documentation

Folders

Folders provide structure and hierarchy for various aspects, such as surveys and users, of the HappyOrNot-system.

Summary of available resource patterns

Section titled “Summary of available resource patterns”
Code URL
GET /v1/folders
GET /v1/folders/:key
GET /v1/folders/:key/children
GET /v1/folders/:key/alerts

Folder

Section titled “Folder”

JSON presentation of folder.

Properties
Section titled “Properties”
Name Description
key The identifier of the folder
name The name of the folder
folders An array of folders belonging to the folder (i.e. sub-folders). If a folder does not have sub-folders, this property is not included in the result.
surveys An array of surveys belonging to the folder. If no surveys are requested or the folder does not contain any surveys, this property is not included in the result.

Example JSON objects

Section titled “Example JSON objects”
Folder containing two sub-folders.
Section titled “Folder containing two sub-folders.”
{
  "key": 1,
  "name": "Acme",
  "folders": [
    {
      "key": 2,
      "name": "Tampere"
    },
    {
      "key": 3,
      "name": "New York"
    }
  ]
}

GET /v1/folders

Section titled “GET /v1/folders”

Retrieves information on company’s root folder.

Parameters
Section titled “Parameters”
Name Description
surveys optional, either true or false When true, folders will include a list of surveys belonging to them.
state optional, one of active, ended, starting When this is given and the surveys-parameter is true, folders will include only the list of surveys in the given state.

Example requests and responses

Section titled “Example requests and responses”
GET /v1/folders
Section titled “GET /v1/folders”
{
  "key": 1,
  "name": "How was your day?"
}
GET /v1/folders?surveys=true
Section titled “GET /v1/folders?surveys=true”
{
  "key": 1,
  "name": "Acme",
  "folders": [
    {
      "key": 2,
      "name": "Tampere",
      "surveys": [
        {
          "key": 2,
          "question": {
            "key": 1,
            "name": "How was your day?",
            "locale": "en-US"
          },
          "timeZone": "Europe/Helsinki"
        }
      ]
    },
    {
      "key": 3,
      "name": "New York"
    }
  ],
  "surveys": [
    {
      "key": 2,
      "question": {
        "key": 1,
        "name": "How was your day?",
        "locale": "en-US"
      },
      "timeZone": "America/New_York"
    }
  ]
}
Result
Section titled “Result”
Name Description
Success Folders
Error HTTP status code 404 when no folder is found.

GET /v1/folders/:key

Section titled “GET /v1/folders/:key”

Retrieves information on folder specified by key.

Parameters
Section titled “Parameters”
Name Description
key required, identifier of folder
surveys optional, either true or false When true, folders will include a list of surveys belonging to them.
state optional, one of active, ended, starting When true, folder-objects will include a list of surveys belonging to them.

Examples

Section titled “Examples”
GET /v1/folders/3?surveys=true&state=active
Section titled “GET /v1/folders/3?surveys=true&state=active”
{
  "key": 3,
  "name": "Tampere",
  "folders": [
    {
      "key": 4,
      "name": "Hervanta",
      "surveys": [
        {
          "key": 2,
          "question": {
            "key": 1,
            "name": "How was your day?",
            "locale": "en-US"
          },
          "timeZone": "UTC"
        }
      ]
    }
  ],
  "surveys": [
    {
      "key": 1,
      "question": {
        "key": 1,
        "name": "How was your day?",
        "locale": "en-US"
      },
      "timeZone": "UTC"
    }
  ]
}
Result
Section titled “Result”
Name Description
Success Folders
Error HTTP status code 404 when no folder is found.

GET /v1/folders/:key/children

Section titled “GET /v1/folders/:key/children”

Lists sub-folders of a specified folder.

Parameters
Section titled “Parameters”
Name Description
key required, identifier of folder
surveys optional, either true or false When true, folders will include a list of surveys belonging to them.
state optional, one of active, ended, starting When this is given and the surveys-parameter is true, folders will include only the list of surveys in the given state.
offset optional, zero-based numeric value. The index of first result returned and used to paginate results.
limit optional, numeric value in range 1..100. The number of results returned and used to paginate results Default value is 50 and maximum 100.

Examples

Section titled “Examples”
GET /v1/folders/1/children
Section titled “GET /v1/folders/1/children”
{
  "meta": {
    "offset": 0,
    "limit": 50,
    "total": 2
  },
  "data": [
    {
      "key": 3,
      "name": "Tampere"
    },
    {
      "key": 4,
      "name": "Helsinki"
    }
  ]
}
Result
Section titled “Result”
Name Description
Success Object containing two properties: meta for additional information (of pagination etc.) and data for a list of folders.
Error HTTP status code 404 when no folder is found.