Recommended Client’s API Design

Overview

If a client does not use a calendar management system supported by SyncSign, such as Google Calendar / Office 365, the SyncSign system needs to be customized to interface with the client’s reservation system.

This document describes the recommended APIs provided by the client’s private system. This API description is similar to the Google Calendar API.

Concepts to Understand

• Reservation System: The system contains multiple Resource Calendars, authorized users can query and update event schedules in different calendars;

• Resources Calendar: Each resource calendar corresponds to the reservation of a conference room space, and the schedule at different times can be recorded respectively;

• Events: A specific meeting event. A single event can take place in one or more conference room spaces with defined time duration, a summary title, and some other parameters.

Brief Description

First of all, SyncSign requires authentication for access to the client’s private system interface, and we recommend the standard OAuth 2.0. That is, get the AccessToken first through the login process. Then, use the AccessToken to access the data.

Secondly, the essential interfaces required for SyncSign are:

• listEvent: SyncSign can invoke this interface to get a list of current and future events, thereby refreshing the display of the screen accordingly.

Then, whenever the events in the client’s private system created or updated, the SyncSign needs to update the display synchronously, usually in two ways:

1. SyncSign provides a webhook URL. After each update, the client’s private system actively invokes the URL, to notify the SyncSign which calendar has been changed.

2. If the above notification is not feasible, then SyncSign can be configured to query the listEvent interface periodically to check for the latest events. The disadvantage is that the load on the client’s server is slightly increased, and the synchronized speed is adversely affected by the query interval.

Furthermore, if a webhook notification mechanism is employed, SyncSign can require the client’s private system to send notifications only when necessary, in order to alleviate the burden on the client’s private system (The implementation is optional):

• registerWatch: Requires the client’s private system to send a notification to the webhook URL when the specified calendar changes;

• stopWatch: Tell the client’s private system, no longer need to send notifications for the specified calendar.

Implementation

Client’s private API definition:

List Events (Mandatory)

Invoke this method to fetch the latest events list.

• Request Type: HTTP request

• Method: GET

• URL Example: https://domain/resources/id/events

• Parameters:

  • id

    • Position: Path parameters

    • Data Type: string

    • Description: Resource identifier.

  • timeMin

    • Position: query parameters

    • Data Type: datetime

    • Description: Lower bound (exclusive) for an event’s end time to filter by. Optional. The default is not to filter by end time. Must be an RFC3339 timestamp with mandatory time zone offset, for example, 2011-06-03T10:00:00-07:00, 2011-06-03T10:00:00Z. Milliseconds may be provided but are ignored. If timeMax is set, timeMin must be smaller than timeMax.

  • maxResults

    • Position: query parameters

    • Data Type: number

    • Description: Return events’ maximum items count (optional)

  • orderBy

    • Position: query parameters

    • Data Type: string

    • Description: The order of events returned (optional), accepted value: startTime / updated

  • singleEvents

    • Position: query parameters

    • Data Type: boolean

    • Description: Whether to expand recurring events into instances and only return single one-off events and instances of recurring events, but not the underlying recurring events themselves. Optional. The default is False.

• Response:

  • summary

    • Title of the calendar. Read-only.

  • items[]

    • List of events on the calendar.

{
  "summary": "The Alps",
  "items": [
    events Resource
  ]
}

• events Resource:

  • summary

    • Title of the event.

  • creator.displayName

    • The creator’s name, if available.

  • start.dateTime

    • The time, as a combined date-time value (formatted according to RFC3339). A time zone offset is required unless a time zone is explicitly specified in timeZone.

  • end.dateTime

    • The time, as a combined date-time value (formatted according to RFC3339). A time zone offset is required unless a time zone is explicitly specified in timeZone.

  • attendees

    • The number of attendees.

{
  "summary": "Welcome",
  "creator": {
    "displayName": "nextags"
  },
  "start": {
    "dateTime": "2019-02-09T18:30:00-08:00"
  },
  "end": {
    "dateTime": "2019-02-09T19:30:00-08:00"
  },
  "attendees": 2
}

Notification (Optional)

If a resource has been watched, the calendar system must call this webhook to notify the watcher whenever the resource updated.

In this example, the SyncSign is the Watcher.

• Request Type： HTTP request

• Method： POST

• URL Example: https://api.sync-sign.com/v2/nodes/notifies/{clientId} (The watcher will submit this URL upon register Watch)

• Parameters:

  • Header:

    • X-Channel-ID： A UUID or similar unique string that identifies this channel.

    • X-Resource-ID：A version-specific identifier for the watched resource (Use to cancel the watch)

    • X-Channel-Token： An arbitrary string delivered to the target address with each notification delivered over this channel (Optional)

  • Body: TBD.

• Response:

  • Success:

    • 200: The notification has been received, will forward to SyncSign’s Hub and Displays

  • Failure:

    • Not 200: The notification is not processed, retry is recommended.

Watch (Optional)

SyncSign calls this API to tell the client’s system: whenever a resource created/updated, call the webhook URL.

• Request Type： HTTP request

• Method： POST

• URL Example: https://domain/spaces/{{id}}/events/watch

• Parameters:

  • id

    • Position: Path parameters

    • Data Type: string

    • Description: spaces identifier

• Body:

{
    "id": string,
    "token": string,
    "type": string,
    "address": string,
    "params": {
        "ttl": string
    }
}

• Body Description:

  • id

    • Data Type: string

    • Description: A UUID or similar unique string that identifies this channel.

  • token

    • Data Type: string

    • Description: A string that should be carried to every notification as a parameter.

  • type

    • Data Type: string

    • Description: Subscribe and notify resources changes

  • address

    • Data Type: string

    • Description: Webhook’s URL

  • params

    • Data Type: Object

    • Description: (optional)

  • params.ttl

    • Data Type: number

    • Description: The expiry period of the watch. No need to send a notification when expired (default: 3600s)

• Response (Success):

{
  "kind": "api#channel",
  "id": string,
  "resourceId": string,
  "resourceUri": string,
  "token": string,
  "expiration": long
}

• Response Parameters Description:

  • kind

    • Data Type：string

    • Description: Identifies this as a notification channel used to watch for changes to a resource. Value: the fixed string “api#channel”.

  • id

    • Data Type： string

    • Description: string A UUID or similar unique string that identifies this channel.

  • resourceId

    • Data Type：string

    • Description: A version-specific identifier for the watched resource.

  • token

    • Data Type：string

    • Description: string An arbitrary string delivered to the target address with each notification delivered over this channel. Optional. (Optional)

  • expiration

    • Data Type： date

    • Description: Date and time of notification channel expiration, expressed as a Unix timestamp, in milliseconds. Optional.

Stop Watch (Optional)

SyncSign calls this API to tell the client’s server no longer sends the notification when the specific resource updates.

• Request Type： HTTP request

• Method： POST

• URL Example: https://domain/spaces/{{id}}/events/watch

• Parameters:

  • id

    • Position: Path parameters

    • Data Type: string

    • Description: Space identifier.

• Request Body:

{
  "id": string,
  "resourceId": string
}

• Body Description:

  • id

    • Data Type：string

    • Description: A UUID or similar unique string that identifies this channel.

  • resourceId

    • Data Type：string

    • Description: An opaque ID that identifies the resource being watched on this channel. Stable across different API versions.