Content

1 Overview
2 Conventions
3 Authentication and Encryption
4 Overview
5 Get the list of rooms
6 Get the room's meetings
7 Create a new meeting
8 Update an existing meeting
9 ROOMZ Connector configuration

Overview

The ROOMZ display gets its information from a ROOMZ server. This ROOMZ server interacts with the company's booking system, such as Microsoft Exchange, IBM Domino or Google Calendar. It will read and update information using an API. Each system has its own API.

In order to support other booking systems, ROOMZ has developed a generic connector. This connector will exchange information with any booking system providing the AP following the contract specified in the following sections:

Conventions

The following conventions have been applied for the definition of the API:

The API is communicating using RESTful calls
The returned content is in JSON format
The date and time are always in UTC and ISO8601 format https://www.w3.org/TR/NOTE-datetime ("YYYY-MM-DDThh:mm:ssZ")
The success of the calls is identified by the HTTP status code(e.g. 200=OK, 401=Unauthorized)
There is no null value (Except imageUrl)

Authentication and Encryption

All the requests are executed using a HTTP Basic Authentication. As the credentials are readable, it is highly recommended to provide access to the API with HTTPS only (HTTP over TLS).

Overview

The API must support the following calls:

Method	URL	Description

Method	URL	Description
GET	/rooms	Get the list of rooms
GET	/rooms/roomId/meetings	Get the list of meetings of a room
POST	/rooms/roomId/meetings	Create a new meeting
PUT	/rooms/roomId/meetings/meetingId	Update an existing meeting

Scenario:

When associating a ROOMZ display with a room's calendar, the list of rooms will be suggested
The list of meeting will be requested in order to represent the room's calendar on the display
The user can book a room directly on the ROOMZ display for a specified duration
When any meeting is finished earlier as plan, the user can directly release the room on the screen. The endDate of the current meeting will be modified

The next sections will describe each call in more details.

Get the list of rooms

Request:

Method	URL

Method	URL
GET	/rooms

Response:

Format	Structure

Format	Structure
JSON	Room [ ]

Room is composed by the following properties:

Property	Type	Description	Example

Property	Type	Description	Example
roomId	String	The identifier of the room	"r212"
name	String	The name of the room	"Weisshorn"

Example of response body:

[{"roomId":"57","name":"Weisshorn"},{"roomId":"22","name":"Moleson"}]

Possible HTTP response status codes expected:

OK --> 200
Unauthorized -> 401

Get the room's meetings

Request:

Method	URL

Method	URL
GET	/rooms/roomId/meetings?from=2010-12-31T14:00:00Z&to=2013-01-01T08:00:00Z

roomId refers to the room identifier
from is in ISO8601 UTC format ("YYYY-MM-DDThh:mm:ssZ"), is not optional and corresponds to "greater or equal to" (>=)
to is in ISO8601 UTC format ("YYYY-MM-DDThh:mm:ssZ"), is not optional and corresponds to "smaller or equal to" (<)

Response:

Format	Structure

Format	Structure
JSON	Meeting [ ]

Meeting is composed by the following properties:

Property	Type	Description	Example

Property	Type	Description	Example
meetingId	String	The identifier of the meeting	"m1234"
subject	String	The subject of the meeting	"Product Review"
organizerId	String	The identifier of the organizer	"u567"
organizerName	String	The name of the organizer	"John Doe"
startDateUTC	String	The start date&time of the meeting	"2012-12-20T14:30:00Z"
endDateUTC	String	The end date&time of the meeting	"2012-12-20T16:30:00Z"
creationDateUTC	String	The creation date&time of the meeting	"2012-12-10T16:30:00Z"
isPrivate	Boolean	Is the meeting subject confidential	false
isCancelled	Boolean	Is the meeting cancelled	false
imageUrl	String	Image to diplay during the meeting	“https://someurl.com/images/someCoolImageToDisplay.jpg”

ISO 8601 datetimes

We don’t support the decimal fraction, this is part of the ISO8601:1-2019.

❌2024-06-25T11:17:12.67584Z
✅2024-06-25T11:17:12Z

If the information creationDateUTC is not managed by the booking system, the value must be the same as the startDateUTC
If the flag isPrivate is not managed by the booking system, the returned value must always be false
If the flag isCancelled is not managed by the booking system, the returned value must always be false
The image for the imageUrl field is optional and should be behind an HTTPS resource, and it should be public (no authentication), to use the Image shown you have to toggle on the following switch:

We strongly recommend the use of an image with a 1024x768 resolution, as this is the native resolution of the ROOMZ Displays
Before a publication, it is recommended to convert your image using our ROOMZ Image Converter. The Displays have their own greyscale threshold. Using the tool guarantees that the rendering on the Display will be the very same as on your image

Example of response body:

[
  {
    "meetingId": "m123",
    "subject": "Product Review",
    "organizerId": "u123",
    "organizerName": "John Doe",
    "startDateUTC": "2012-12-20T10:00:00Z",
    "endDateUTC": "2012-12-20T12:00:00Z",
    "creationDateUTC": "2012-12-18T10:00:00Z",
    "isPrivate": false,
    "isCancelled": false,
    "imageUrl": null
  },
  {
    "meetingId": "m456",
    "subject": "Strategy",
    "organizerId": "u445",
    "organizerName": "Mike Horn",
    "startDateUTC": "2012-12-21T14:00:00Z",
    "endDateUTC": "2012-12-21T17:00:00Z",
    "creationDateUTC": "2012-12-20T17:00:00Z",
    "isPrivate": true,
    "isCancelled": false,
    "imageUrl": "https://someurl.com/images/someCoolImageToDisplay.jpg"
  }
]

Possible HTTP response status codes expected:

OK --> 200
Malformed date in the request --> 400
Unauthorized --> 401
Unknown Room ID or Organizer ID --> 404

Create a new meeting

Request:

Method	URL

Method	URL
POST	/rooms/roomId/meetings

roomId refers to the room identifier

Request body:

Format	Structure

Format	Structure
JSON	NewMeeting

NewMeeting is composed by the following properties:

Property	Type	Description	Example

Property	Type	Description	Example
subject	String	The subject of the meeting	"Product Review"
organizerId	String	The identifier of the organizer	"u345"
startDateUTC	String	The start date&time of the meeting	"2012-12-20T14:30:00Z"
endDateUTC	String	The end date&time of the meeting	"2012-12-20T16:30:00Z"

Remark:

If the booking system is managing the information creationDateUTC, this value must be set by the booking system during this call
ROOMZ will not declare any meetings Private or Cancelled

Example of request body:

{"subject":"Product Review","organizerId":"u123", "startDateUTC":"2012-12-20T10:00:00Z","endDateUTC":"2012-12-20T12:00:00Z"}

Possible HTTP response status codes expected:

OK --> 200 or 201
Unauthorized --> 401
Unknown Room ID or Organizer ID --> 404
Conflict with existing meeting --> 409

Update an existing meeting

Request:

Method	URL

Method	URL
PUT	/rooms/roomId/meetings/meetingId

roomId refers to the room identifier
meetingId refers to the meeting identifier

Request body:

Format	Structure

Format	Structure
JSON	ModifiedMeeting

ModifiedMeeting is composed by the following properties:

Property	Type	Description	Example

Property	Type	Description	Example
startDateUTC	String	The start date&time of the meeting	"2012-12-20T14:30:00Z"
endDateUTC	String	The end date&time of the meeting	"2012-12-20T16:30:00Z"

Possible HTTP response status codes expected:

OK --> 200
Malformed information --> 400
Unauthorized --> 401
Unknown Room ID, or Meeting ID --> 404
Conflict with existing meeting --> 409

ROOMZ Connector configuration

On the ROOMZ portal, the following properties must be configured for communicating with the booking system's API:

Property	Example

Property	Example
URL	"https://mydomain.com/api/roomz/v1"
Username	"John"
Password	"1234"
OrganizerId	"u821"

The Username and Password are used for the HTTP Basic Authentication
The OrganizerId is used for the creation of new meeting
The Username and the OrganizerId could be the same value

As alternative for the authentication, you can use:

Property	Example

Property	Example
URL	"https://mydomain.com/api/roomz/v1"
Access token	“123456789”
Custom authorization header	“Security: MyHeader”
OrganizerId	"u821"