Content

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:

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:

Response:

Room is composed by the following properties:

Example of response body:

Possible HTTP response status codes expected:

• OK --> 200

• Unauthorized -> 401

Get the room's meetings

Request:

• roomId refers to the room identifier

• from is in ISO8601 UTC format ("YYYY-MM-DDThh:mm:ssZ"), is optional and corresponds to "greater or equal to" (>=)

• to is in ISO8601 UTC format ("YYYY-MM-DDThh:mm:ssZ"), is optional and corresponds to "smaller or equal to" (<=)

Response:

Meeting is composed by the following properties:

Remark:

• 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:
  

  

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:

• roomId refers to the room identifier

Request body:

NewMeeting is composed by the following properties:

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:

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:

• roomId refers to the room identifier

• meetingId refers to the meeting identifier

Request body:

ModifiedMeeting is composed by the following properties:

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:

• 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: