NAV
http

Introduction

This is the documentation for the API of CompanyMood.

This API follows the JSONAPI specification but without hypermedia.

There are a lot of different librabies for all kinds of languages out there to consume JSON-API APIs.

API Request and Versions

GET / HTTP/1.1
Host: api.company-mood.com
Accept: application/vnd.company-mood-v1+json

You need to specify the API version you want use via the Accept header.

Format

application/vnd.company-mood-v<VERSION>+json

Application Token

GET / HTTP/1.1
Host: api.company-mood.com
X-App-Token: 27f50875-9a43-4d6c-a376-6968f09858db

You need to send your application token with every request in the X-App-Token header.

Authentication

GET / HTTP/1.1
Host: api.company-mood.com
Authorization: Bearer 795665b4-53da-468c-a0d7-ab2d82e58406

For every authenticated request (all but /sessions) you need to send the auth_token (see /sessions endpoint) in the Authorization header as a Bearer token.

Heartbeat

Get the heartbeat

GET /heartbeat HTTP/1.1
Host: api.company-mood.com
Content-Type: application/json
Accept: application/vnd.company-mood-v1+json
Authorization: Bearer 795665b4-53da-468c-a0d7-ab2d82e58406
X-App-Token: 27f50875-9a43-4d6c-a376-6968f09858db
HTTP/1.1 200 OK
Content-Type: application/json

A heartbeat endpoint which return a 200 status if the API is operational.

Sessions

Create a new session

POST /sessions HTTP/1.1
Host: api.company-mood.com
Content-Type: application/json
Accept: application/vnd.company-mood-v1+json
Authorization: Bearer 795665b4-53da-468c-a0d7-ab2d82e58406
X-App-Token: 27f50875-9a43-4d6c-a376-6968f09858db

{
  "data": {
    "type": "sessions",
    "attributes": {
      "email": "invalid@example.com",
      "password": "secret"
    }
  }
}
HTTP/1.1 201 CREATED
Content-Type: application/json

{
  "data": {
    "id": "1d7f7eea-b088-46dd-b29c-51ccfa4085e7",
    "type": "users",
    "attributes": {
      "firstname": "John",
      "lastname": "Doe",
      "email": "j.doe1@example.com",
      "locale": "de",
      "image_url": "https://gravatar.com/avatar/829afce351884fcde132544bf9686221",
      "role": "admin",
      "auth_token": "5c3dad26-31a4-4f6d-a799-b3cd9053dc83",
      "company_id": "8f40670c-9927-4712-979f-81a2fa4c7253"
    }
  }
}

You can create a new session and get the auth_token and other important informations about the just logged in user by sending the email and password to this endpoint.

The returned role can be “admin”, “employee” or “department_manager”.

POST Attributes

Paramteter Description
email Email for session
password Password for session

Response Attributes

Paramteter Description
firstname Firstname of the sessions user
lastname Lastname of the sessions user
email Email of the sessions user
locale Locale of the sessions user
image_url Url to the profile image of the sessions user
role Role of the sessions user (admin, department_manager or employee)
auth_token Auth token for users session, use this for further authorization on enpoints
company_id ID of the company, the user belongs to. Empty if the user does’t belong to a company, yet.

CustomTags

Retrieve the tags pool for logged in user

Custom tags specify the tags you can use to describe your mood. It’s id and name is the same value. Returns with an 401 if the user does not belong to a company.

GET /custom_tags HTTP/1.1
Host: api.company-mood.com
Content-Type: application/json
Accept: application/vnd.company-mood-v1+json
Authorization: Bearer 795665b4-53da-468c-a0d7-ab2d82e58406
X-App-Token: 27f50875-9a43-4d6c-a376-6968f09858db
HTTP/1.1 200 OK
Content-Type: application/json

{
  "data": [
     {
       "id": "f7559f2a-8f1c-461e-8a9b-7efea5564edb",
       "type": "custom_tags",
       "attributes": {
         "name": "Workload",
         "de_translation": "Arbeitspensum",
         "en_translation": "Workload"
       }
     },
     {
       "id": "c23e5e7d-162f-4fdc-9243-5e6349ce2bd1",
       "type": "custom_tags",
       "attributes": {
         "name": "Private",
         "de_translation": "Privat",
         "en_translation": "Private"
       }
     },
     {
       "id": "a9767fd1-a187-40e2-954c-872cebff5e70",
       "type": "custom_tags",
       "attributes": {
         "name": "Management",
         "de_translation": "Vorgesetzte",
         "en_translation": "Management"
       }
     }
  ]
}

Response Attributes

Paramteter Description
id id of the tag (used for custom_tag_ids in mood creation)
name name (DEPRECATED)
de_translation German translation of the tag
en_translation English translation of the tag

Departments

Retrieve the departments of the users company

Returns with an 401 if the user does not belong to a company or isn’t an admin of the company.

GET /departments HTTP/1.1
Host: api.company-mood.com
Content-Type: application/json
Accept: application/vnd.company-mood-v1+json
Authorization: Bearer 795665b4-53da-468c-a0d7-ab2d82e58406
X-App-Token: 27f50875-9a43-4d6c-a376-6968f09858db
HTTP/1.1 200 OK
Content-Type: application/json

{
  "data": [
     {
       "id": "f7559f2a-8f1c-461e-8a9b-7efea5564edb",
       "type": "departments",
       "attributes": {
         "name": "Services",
         "breadcrumb": "Development > In House > Services"
       }
     },
     {
       "id": "a9767fd1-a187-40e2-954c-872cebff5e70",
       "type": "departments",
       "attributes": {
         "name": "Management",
         "breadcrumb": "Management"
       }
     }
  ]
}

Response Attributes

Paramteter Description
id id of the department
name name
breadcrumb All names in path to the department incl. it’s own

EventPins

Retrieve the event_pins of the users company

Returns with an 401 if the user does not belong to a company.

GET /event_pins HTTP/1.1
Host: api.company-mood.com
Content-Type: application/json
Accept: application/vnd.company-mood-v1+json
Authorization: Bearer 795665b4-53da-468c-a0d7-ab2d82e58406
X-App-Token: 27f50875-9a43-4d6c-a376-6968f09858db
HTTP/1.1 200 OK
Content-Type: application/json

{
  "data": [
     {
       "id": "f7559f2a-8f1c-461e-8a9b-7efea5564edb",
       "type": "event_pins",
       "attributes": {
         "name": "New office manager",
         "description": "The new office manager got employed.",
         "date": "2016-03-11",
         "visible_for_role": "employee",
         "department_ids": [
           "094822c8-d81f-4639-8197-9a586f10edcd"
         ]
       }
     },
     {
       "id": "a9767fd1-a187-40e2-954c-872cebff5e70",
       "type": "event_pins",
       "attributes": {
         "name": "Off-Site in Berlin",
         "description": "We spend a week in Berlin together.",
         "date": "2016-05-27",
         "visible_for_role": "department_manager",
         "department_ids": []
       }
     }
  ]
}

Response Attributes

Paramteter Description
id id of the department
name Name of the event pin
description Description of the event pin
department_ids Department ids for departments the event pin belong. Belongs to whole company if empty
date Date of the event pin
visible_for_role Shows what users should be able to see it.

TerminalSpots

Retrieve the terminal spots of the users company

Returns with an 401 if the user does not belong to a company

You’ll need the terminal_spot_id and its accorind department_id if you want to track a terminal mood. More under /moods

Note

In this endpoint you’ll get all dependend departments and terminal_spot_department_settings as sideloaded relationships and includes.

GET /terminal_spots HTTP/1.1
Host: api.company-mood.com
Content-Type: application/json
Accept: application/vnd.company-mood-v1+json
Authorization: Bearer 795665b4-53da-468c-a0d7-ab2d82e58406
X-App-Token: 27f50875-9a43-4d6c-a376-6968f09858db
HTTP/1.1 200 OK
Content-Type: application/json

{
  "data": [{
     "id": "f7559f2a-8f1c-461e-8a9b-7efea5564edb",
     "type": "terminal_spot",
     "attributes": {
       "name": "Production exit terminal",
       "description": "This terminal gets placed at the facility A.1-5s exits",
       "soft_cap_rate": 10,
       "hard_cap_rate": 25
     },
     "relationships": {
       "terminal_spot_department_settings": {
         "data": [
           {
             "id": "0cc30da9-ffc7-40ff-9c88-ef03aa692b98",
             "type": "terminal_spot_department_settings"
           }
         ]
       }
     }
   }],
   "included": [{
    "id": "0cc30da9-ffc7-40ff-9c88-ef03aa692b98",
    "type": "terminal_spot_department_settings",
    "attributes": {
      "users_count": 9,
      "department_id": "ea985df4-2c38-4c44-bda9-5bbe031f6755"
    },
    "relationships": {
      "department": {
        "data": {
          "id": "ea985df4-2c38-4c44-bda9-5bbe031f6755",
          "type": "departments"
        }
      }
    }
  },{
    "id": "ea985df4-2c38-4c44-bda9-5bbe031f6755",
    "type": "departments",
    "attributes": {
      "name": "Design",
      "breadcrumb": "German HQ > Development > Design"
    }
  }]
}

Response Attributes

terminal_spot

Paramteter Description
id id of the terminal spot
name name of the terminal spot
description description of the terminal spot
soft_cap_rate Soft cap rate defines at what rate (not amount) of overtracked moods, a warning should get shown fir a terminals department
hard_cap_rate Hard cap rate defines at what rate (not amount) of overtracked moods, a terminal should not allow the tracking for a terminals department

side loaded department

Paramteter Description
id id of the terminal spot
name name of the terminal spot
breadcrumb All names in path to the department incl. it’s own

side loaded terminal_spot_department_settings

Paramteter Description
id id of the terminal spot
users_count how much users are supposed to track via this terminal_spot_department_setting
department_id department id for this terminal_spot_department_setting (needed for tracking terminal mood)

Moods

Retrieve moods of the logged in user

GET /moods HTTP/1.1
Host: api.company-mood.com
Content-Type: application/json
Accept: application/vnd.company-mood-v1+json
Authorization: Bearer 795665b4-53da-468c-a0d7-ab2d82e58406
X-App-Token: 27f50875-9a43-4d6c-a376-6968f09858db

{
  "meta": {
    "from": "2015-01-30",
    "to": "2015-04-30"
  }
}
HTTP/1.1 200 OK
Content-Type: application/json

{
  "meta": {
    "from": "2015-01-30",
    "to": "2015-04-30",
    "last_weeks_mood_id": "e96afc28-f27e-49b9-9f27-94dd3e2a296b"
  },
  "data": [
     {
       "id": "094822c8-d81f-4639-8197-9a586f10edcd",
       "type": "moods",
       "attributes": {
         "rating": 100,
         "calendar_week": 46,
         "year": 2015,
         "reason": "It was pretty noisy this week",
         "tag_list": [],
         "custom_tag_ids": [],
         "feeling": "happy",
         "department_id": "f7559f2a-8f1c-461e-8a9b-7efea5564edb",
         "created_at": "2015-11-21T05:59:42.517Z"
       }
     },
     {
       "id": "e96afc28-f27e-49b9-9f27-94dd3e2a296b",
       "type": "moods",
       "attributes": {
         "rating": 75,
         "calendar_week": 47,
         "year": 2015,
         "reason": "Got a new place in the basement! :)",
         "tag_list": ["Management"],
         "custom_tag_ids": ["f7559f2a-8f1c-461e-8a9b-7efea5564edb"],
         "feeling": "satisfied",
         "department_id": "a9767fd1-a187-40e2-954c-872cebff5e70",
         "created_at": "2015-11-18T19:18:42.517Z"
       }
     }
  ]
}

Request the moods for the logged in user.

Possibility to filter the collection by from, to, all_in_company and deparment_idparameters.

POST META Attributes

Paramteter Description
from optional Date to limit the moods results (in ISO8601)
to optional Date to limit the moods results (in ISO8601)
all_in_company optional Return all moods of that company (true or false) - only works for company admins
department_id optional Return all moods of that department (true or false) - only works for company admins

Response META Attributes

Paramteter Description
from Date to limit the moods results (in ISO8601)
to Date to limit the moods results (in ISO8601)
last_weeks_mood_id ID of the last weeks mood for given user (can be empty, means no mood given)

Response Attributes

Paramteter Description
rating Rating as a number between 0 - 100
calendar_week Calendar week of the mood
year Year of the mood
reason Optional given reason
tag_list tag list of CustomTags as Array (DEPRECATED)
custom_tag_ids list of CustomTags IDs as Array
feeling Feeling of the mood (happy, satisfied, ok, unhappy, sad)
department_id The moods department id
created_at Date of the mood creation (in ISO8601)

Create a new mood for last week - For the authorized user

POST /moods HTTP/1.1
Host: api.company-mood.com
Content-Type: application/json
Accept: application/vnd.company-mood-v1+json
Authorization: Bearer 795665b4-53da-468c-a0d7-ab2d82e58406
X-App-Token: 27f50875-9a43-4d6c-a376-6968f09858db

{
  "data" : {
    "type": "moods",
    "attributes": {
      "feeling": "happy",
      "reason": "Got a new place in the basement! :)",
      "tag_list": "Management",
      "custom_tag_ids": ["f7559f2a-8f1c-461e-8a9b-7efea5564edb"],
    }
  }
}
HTTP/1.1 201 CREATED
Content-Type: application/json

{
  "data": {
    "id": "e96afc28-f27e-49b9-9f27-94dd3e2a296b",
    "type": "moods",
    "attributes": {
      "rating": 100,
      "calendar_week": 25,
      "year": 2015,
      "reason": "Got a new place in the basement! :)",
      "tag_list": ["Management", "Others"],
      "custom_tag_ids": ["f7559f2a-8f1c-461e-8a9b-7efea5564edb"],
      "feeling": "happy",
      "department_id": "a9767fd1-a187-40e2-954c-872cebff5e70",
      "created_at": "2015-06-25T11:18:42.517Z"
    }
  }
}

Creates the mood for the latest calendar week.

You MUST provide a reason or at least one tag in the tag_list parameter.

POST Attributes

Parameter Description
feeling required Feeling of the mood can be (“sad”, “unhappy”, “ok”, “satisfied”, “happy”) - in rating it’s 0, 25, 50, 75, 100
reason required Text reason for the mood
custom_tag_ids required list of CustomTags IDs as Array (Only tags from /custom_tags allowed)

Response Attributes

Paramteter Description
rating Rating as a number between 0 - 100
calendar_week Calendar week of the mood
year Year of the mood
reason Optional given reason
tag_list tag list of CustomTags as Array (DEPRECATED)
custom_tag_ids list of CustomTags IDs as Array
feeling Feeling of the mood (happy, satisfied, ok, unhappy, sad)
department_id The moods department id
created_at Date of the mood creation (in ISO8601)

Create a new mood for last week - For a terminal (no user get assigned)

POST /moods HTTP/1.1
Host: api.company-mood.com
Content-Type: application/json
Accept: application/vnd.company-mood-v1+json
Authorization: Bearer 795665b4-53da-468c-a0d7-ab2d82e58406
X-App-Token: 27f50875-9a43-4d6c-a376-6968f09858db

{
  "data" : {
    "type": "moods",
    "attributes": {
      "feeling": "happy",
      "reason": "Got a new place in the basement! :)",
      "custom_tag_ids": ["f7559f2a-8f1c-461e-8a9b-7efea5564edb"],
      "terminal_spot_id": "0f4d29f7-34e0-4ce9-b985-a90cccbd9f86",
      "department_id": "f53ac2a2-2917-4b4a-84ac-8874f406dc97"
    }
  }
}
HTTP/1.1 201 CREATED
Content-Type: application/json

{
  "data": {
    "id": "e96afc28-f27e-49b9-9f27-94dd3e2a296b",
    "type": "moods",
    "attributes": {
      "rating": 100,
      "calendar_week": 25,
      "year": 2015,
      "reason": "Got a new place in the basement! :)",
      "tag_list": ["Management", "Others"],
      "custom_tag_ids": ["f7559f2a-8f1c-461e-8a9b-7efea5564edb"],
      "feeling": "happy",
      "department_id": "a9767fd1-a187-40e2-954c-872cebff5e70",
      "created_at": "2015-06-25T11:18:42.517Z"
    }
  }
}

Creates the mood for the latest calendar week.

You MUST provide a reason or at least one tag in the tag_list parameter.

POST Attributes

Parameter Description
feeling required Feeling of the mood can be (“sad”, “unhappy”, “ok”, “satisfied”, “happy”) - in rating it’s 0, 25, 50, 75, 100
reason required Text reason for the mood
custom_tag_ids required list of CustomTags IDs as Array (Only tags from /custom_tags allowed)
terminal_spot_id required ID of the terminal spot for which you want to track the mood
department_id required ID of the department for which you want to track the terminals mood (need to be assigned to the particular terminal)

Response Attributes

Paramteter Description
rating Rating as a number between 0 - 100
calendar_week Calendar week of the mood
year Year of the mood
reason Optional given reason
tag_list tag list of CustomTags as Array (DEPRECATED)
custom_tag_ids list of CustomTags IDs as Array
feeling Feeling of the mood (happy, satisfied, ok, unhappy, sad)
department_id The moods department id
created_at Date of the mood creation (in ISO8601)

Update a mood

PUT /moods/{mood_id} HTTP/1.1
Host: api.company-mood.com
Content-Type: application/json
Accept: application/vnd.company-mood-v1+json
Authorization: Bearer 795665b4-53da-468c-a0d7-ab2d82e58406
X-App-Token: 27f50875-9a43-4d6c-a376-6968f09858db

{
  "data" : {
    "type": "moods",
    "attributes": {
      "feeling": "satisfied",
      "reason": "Got a new place in the basement! :)",
      "tag_list": "Management",
      "custom_tag_ids": ["f7559f2a-8f1c-461e-8a9b-7efea5564edb"],
    }
  }
}
HTTP/1.1 201 CREATED
Content-Type: application/json

{
  "data": {
    "id": "e96afc28-f27e-49b9-9f27-94dd3e2a296b",
    "type": "moods",
    "attributes": {
      "rating": 75,
      "calendar_week": 25,
      "year": 2015,
      "reason": "Got a new place in the basement! :)",
      "tag_list": ["Management"],
      "custom_tag_ids": ["f7559f2a-8f1c-461e-8a9b-7efea5564edb"],
      "feeling": "satisfied",
      "department_id": "a9767fd1-a187-40e2-954c-872cebff5e70",
      "created_at": "2015-06-25T11:18:42.517Z"
    }
  }
}

Update a specific mood (by mood_id in the URI)

You can only update the mood for last calendar week and if its creation (created_at) is not older than 24h.

You MUST provide a reason or at least one tag in the tag_list parameter.

POST Attributes

Parameter Description
feeling required Feeling of the mood can be (“sad”, “unhappy”, “ok”, “satisfied”, “happy”) - in rating it’s 0, 25, 50, 75, 100
reason required Text reason for the mood
tag_list required CustomTags for the mood seperated by a ; (Only tags from /custom_tags allowed) (DEPRECATED)
custom_tag_ids list of CustomTags IDs as Array (Only tags from /custom_tags allowed)

Response Attributes

Paramteter Description
rating Rating as a number between 0 - 100
calendar_week Calendar week of the mood
year Year of the mood
reason Optional given reason
tag_list tag list of CustomTags as Array (DEPRECATED)
custom_tag_ids list of CustomTags IDs as Array
feeling Feeling of the mood (happy, satisfied, ok, unhappy, sad)
department_id The moods department id
created_at Date of the mood creation (in ISO8601)

Delete a mood

DELETE /moods/{mood_id} HTTP/1.1
Host: api.company-mood.com
Content-Type: application/json
Accept: application/vnd.company-mood-v1+json
Authorization: Bearer 795665b4-53da-468c-a0d7-ab2d82e58406
X-App-Token: 27f50875-9a43-4d6c-a376-6968f09858db
HTTP/1.1 200 OK
Content-Type: application/json

Delete a specific mood (by mood_id in the URI)

You can only delete the mood for last calendar week.