Folders

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

Note

The folders endpoint does not return all of the folders. It returns only the folder structure two levels down, so only immediate children, and their children, of the requested folder are returned. The /v1/folders/:key endpoint can be used to get rest of the folders.

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

JSON presentation of folder.

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

Folder containing two sub-folders.

{
  "key": 1,
  "name": "Acme",
  "folders": [
    {
      "key": 2,
      "name": "Tampere"
    },
    {
      "key": 3,
      "name": "New York"
    }
  ]
}

---

GET /v1/folders

Retrieves information on company’s root folder.

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

GET /v1/folders

{
  "key": 1,
  "name": "How was your day?"
}

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

Name	Description
Success	Folders
Error	HTTP status code 404 when no folder is found.

---

GET /v1/folders/:key

Retrieves information on folder specified by key.

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

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

Name	Description
Success	Folders
Error	HTTP status code 404 when no folder is found.

---

GET /v1/folders/:key/children

Lists sub-folders of a specified folder.

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

GET /v1/folders/1/children

{
  "meta": {
    "offset": 0,
    "limit": 50,
    "total": 2
  },
  "data": [
    {
      "key": 3,
      "name": "Tampere"
    },
    {
      "key": 4,
      "name": "Helsinki"
    }
  ]
}

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.

---