Skip to content
Permalink
Branch: master
Find file Copy path
Find file Copy path
Fetching contributors…
Cannot retrieve contributors at this time
886 lines (836 sloc) 25.1 KB
#
# © Copyright IBM Corp. 2017
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at:
#
# http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
# implied. See the License for the specific language governing
# permissions and limitations under the License.
#
swagger: '2.0'
# Document metadata
info:
title: IBM Domino Calendar API
version: "9.0.1"
description: |
The calendar API provides access to a Domino user's calendar data.
The API represents calendar data in both JSON and iCalendar format.
**Important**: This version of the OpenAPI spec (**calendar.yaml**) includes
calendar API changes from Domino 9.0.1 FP8. This includes optional new query
parameters for some operations. If you are using a version of Domino before
9.0.1 FP8, consider using an earlier version of the spec.
securityDefinitions:
basic:
type: basic
security:
- basic: []
# Tags
tags:
- name: event list
description: Read a list of calendar events within a date range
- name: event
description: Create, read, update or delete an event
- name: instance list
description: Read the list of instances of a recurring event
- name: event instance
description: Read, update or delete an instance of a recurring event
- name: notice list
description: Read a list of notice summaries
- name: notice
description: Read or act on a single notice
# Paths
paths:
# Events resource
/{folder}/{database}/api/calendar/events:
get:
tags:
- "event list"
summary: |
Reads a list of events from a user's calendar.
parameters:
- $ref: '#/parameters/folderParam'
- $ref: '#/parameters/databaseParam'
- $ref: '#/parameters/formatParam'
-
name: since
in: query
description: |
The start time of the date range in UTC (for example,
`since=2017-09-01T13:00:00Z`). If neither `since` or `sincenow`
is specified, the default is the time of the request.
type: string
-
name: before
in: query
description: |
The end time of the date range in UTC (for example,
`before=2017-10-01T13:00:00Z`). If neither `before` or `days` is
specified, the default is one year from the start time.
type: string
-
name: sincenow
in: query
description: |
The start time of the date range relative to now. For example,
`sincenow=30` indicates a start time 30 days from today. The
`since` and `sincenow` parameters are mutually exclusive.
required: false
type: integer
-
name: days
in: query
description: |
The end time of the date range expressed as the number of days
since the start time (for example, `days=15`). The `before` and
`days` parameters are mutually exclusive.
required: false
type: integer
-
name: count
in: query
description: |
Maximum number of events to return. The default count is 50 events.
type: integer
-
name: start
in: query
description: |
Start index used for paging through large event feeds.
The default start index is 0.
type: integer
-
name: fields
in: query
description: |
Filters the fields (or properties) returned for each event. By default,
all the available fields are returned. You use the fields parameter to
reduce the amount of data returned -- for example, `fields=start,end`.
type: string
# Expected responses for this operation:
responses:
# Response code
200:
description: Successful response
schema:
$ref: '#/definitions/eventListResponse'
400:
description: |
Bad request. For example, you specified an invalid parameter.
schema:
$ref: '#/definitions/errorResponse'
post:
tags:
- "event"
summary: |
Creates a new event on a user's calendar.
consumes:
- application/json
- text/calendar
parameters:
- $ref: '#/parameters/folderParam'
- $ref: '#/parameters/databaseParam'
- $ref: '#/parameters/workflowParam'
- $ref: '#/parameters/eventBody'
responses:
201:
description: Successful response
headers:
Location:
description: The URL of the new event
type: string
400:
description: |
Bad request. For example, the request body is not valid.
schema:
$ref: '#/definitions/errorResponse'
# Event resource
/{folder}/{database}/api/calendar/events/{uid}:
get:
tags:
- "event"
summary: |
Reads a single event from a user's calendar.
parameters:
- $ref: '#/parameters/folderParam'
- $ref: '#/parameters/databaseParam'
- $ref: '#/parameters/uidParam'
- $ref: '#/parameters/formatParam'
# Expected responses for this operation:
responses:
# Response code
200:
description: Successful response
schema:
$ref: '#/definitions/eventResponse'
400:
description: |
Bad request. For example, you specified an invalid parameter.
schema:
$ref: '#/definitions/errorResponse'
put:
tags:
- "event"
summary: |
Updates an event on a user's calendar.
consumes:
- application/json
- text/calendar
parameters:
- $ref: '#/parameters/folderParam'
- $ref: '#/parameters/databaseParam'
- $ref: '#/parameters/uidParam'
- $ref: '#/parameters/literallyParam'
- $ref: '#/parameters/workflowParam'
- $ref: '#/parameters/workflowCommentParam'
- $ref: '#/parameters/strictSequenceParam'
- $ref: '#/parameters/eventBody'
responses:
200:
description: Successful response
400:
description: |
Bad request. For example, the request body is not valid.
schema:
$ref: '#/definitions/errorResponse'
delete:
tags:
- "event"
summary: |
Deletes a single event from a user's calendar.
parameters:
- $ref: '#/parameters/folderParam'
- $ref: '#/parameters/databaseParam'
- $ref: '#/parameters/uidParam'
- $ref: '#/parameters/workflowParam'
# Expected responses for this operation:
responses:
# Response code
200:
description: Successful response
404:
description: |
Not found. For example, you specified an invalid uid.
schema:
$ref: '#/definitions/errorResponse'
# Event action resource
/{folder}/{database}/api/calendar/events/{uid}/action:
put:
tags:
- "event"
summary: |
Applies an action to an event.
parameters:
- $ref: '#/parameters/folderParam'
- $ref: '#/parameters/databaseParam'
- $ref: '#/parameters/uidParam'
- $ref: '#/parameters/actionTypeParam'
- $ref: '#/parameters/actionBody'
responses:
200:
description: Successful response
400:
description: |
Bad request. For example, the server could not parse the JSON body.
schema:
$ref: '#/definitions/errorResponse'
# Event instances resource
/{folder}/{database}/api/calendar/events/{uid}/instances:
get:
tags:
- "instance list"
summary: |
Reads the list of instances for a recurring event.
parameters:
- $ref: '#/parameters/folderParam'
- $ref: '#/parameters/databaseParam'
- $ref: '#/parameters/uidParam'
# Expected responses for this operation:
responses:
# Response code
200:
description: Successful response
schema:
$ref: '#/definitions/instancesResponse'
400:
description: |
Bad request. For example, you specified an invalid parameter.
schema:
$ref: '#/definitions/errorResponse'
# Event instance resource
/{folder}/{database}/api/calendar/events/{uid}/{recurrenceId}:
get:
tags:
- "event instance"
summary: |
Reads a single instance from a recurring event.
parameters:
- $ref: '#/parameters/folderParam'
- $ref: '#/parameters/databaseParam'
- $ref: '#/parameters/uidParam'
- $ref: '#/parameters/recurrenceIdParam'
- $ref: '#/parameters/formatParam'
# Expected responses for this operation:
responses:
# Response code
200:
description: Successful response
schema:
$ref: '#/definitions/eventResponse'
400:
description: |
Bad request. For example, you specified an invalid parameter.
schema:
$ref: '#/definitions/errorResponse'
put:
tags:
- "event instance"
summary: |
Updates an instance of a recurring event.
consumes:
- application/json
- text/calendar
parameters:
- $ref: '#/parameters/folderParam'
- $ref: '#/parameters/databaseParam'
- $ref: '#/parameters/uidParam'
- $ref: '#/parameters/recurrenceIdParam'
- $ref: '#/parameters/literallyParam'
- $ref: '#/parameters/workflowParam'
- $ref: '#/parameters/workflowCommentParam'
- $ref: '#/parameters/strictSequenceParam'
- $ref: '#/parameters/eventBody'
responses:
200:
description: Successful response
400:
description: |
Bad request. For example, the request body is not valid.
schema:
$ref: '#/definitions/errorResponse'
delete:
tags:
- "event instance"
summary: |
Deletes a single instance from a recurring event.
parameters:
- $ref: '#/parameters/folderParam'
- $ref: '#/parameters/databaseParam'
- $ref: '#/parameters/uidParam'
- $ref: '#/parameters/recurrenceIdParam'
- $ref: '#/parameters/recurrenceRangeParam'
- $ref: '#/parameters/workflowParam'
# Expected responses for this operation:
responses:
# Response code
200:
description: Successful response
404:
description: |
Not found. For example, you specified an invalid recurrence ID.
schema:
$ref: '#/definitions/errorResponse'
# Event instance action resource
/{folder}/{database}/api/calendar/events/{uid}/{recurrenceId}/action:
put:
tags:
- "event instance"
summary: |
Applies an action to an event instance.
parameters:
- $ref: '#/parameters/folderParam'
- $ref: '#/parameters/databaseParam'
- $ref: '#/parameters/uidParam'
- $ref: '#/parameters/recurrenceIdParam'
- $ref: '#/parameters/actionTypeParam'
- $ref: '#/parameters/recurrenceRangeParam'
- $ref: '#/parameters/actionBody'
responses:
200:
description: Successful response
400:
description: |
Bad request. For example, the server could not parse the JSON body.
schema:
$ref: '#/definitions/errorResponse'
# Invitations resource
/{folder}/{database}/api/calendar/invitations:
get:
tags:
- "notice list"
summary: |
Reads a list of invitations from a user's calendar.
parameters:
- $ref: '#/parameters/folderParam'
- $ref: '#/parameters/databaseParam'
-
name: since
in: query
description: |
Returns only the invitations for events with a start date greater
than the given date.
required: false
type: string
-
name: receivedsince
in: query
description: |
Returns only the invitations received since the given date.
required: false
type: string
# Expected responses for this operation:
responses:
# Response code
200:
description: Successful response
schema:
$ref: '#/definitions/noticeSummariesResponse'
# Event notices resource
/{folder}/{database}/api/calendar/events/{uid}/notices:
get:
tags:
- "notice list"
summary: |
Reads a list of unapplied notices for this event.
parameters:
- $ref: '#/parameters/folderParam'
- $ref: '#/parameters/databaseParam'
- $ref: '#/parameters/uidParam'
# Expected responses for this operation:
responses:
# Response code
200:
description: Successful response
schema:
$ref: '#/definitions/noticeSummariesResponse'
# Notice resource
/{folder}/{database}/api/calendar/notices/{id}:
get:
tags:
- "notice"
summary: |
Reads a single notice.
parameters:
- $ref: '#/parameters/folderParam'
- $ref: '#/parameters/databaseParam'
- $ref: '#/parameters/noticeIdParam'
- $ref: '#/parameters/formatParam'
# Expected responses for this operation:
responses:
# Response code
200:
description: Successful response
schema:
$ref: '#/definitions/noticeResponse'
404:
description: |
Not found. For example, you specified an invalid notice ID.
schema:
$ref: '#/definitions/errorResponse'
# Notice action resource
/{folder}/{database}/api/calendar/notices/{id}/action:
put:
tags:
- "notice"
summary: |
Applies an action to a single notice.
parameters:
- $ref: '#/parameters/folderParam'
- $ref: '#/parameters/databaseParam'
- $ref: '#/parameters/noticeIdParam'
- $ref: '#/parameters/actionTypeParam'
- $ref: '#/parameters/actionBody'
responses:
200:
description: Successful response
400:
description: |
Bad request. For example, the server could not parse the JSON body.
schema:
$ref: '#/definitions/errorResponse'
# Object definitions
definitions:
exDateTime:
type: object
properties:
date:
type: string
time:
type: string
utc:
type: boolean
description: true when the date and time are in the UTC time zone.
tzid:
type: string
description: |
Time zone ID. The utc and tzid properties are
mutually exclusive.
tzObservance:
type: object
properties:
start:
$ref: '#/definitions/exDateTime'
offsetFrom:
type: string
offsetTo:
type: string
recurrenceRule:
type: string
timeZone:
type: object
properties:
tzid:
type: string
description: The time zone ID.
standard:
$ref: '#/definitions/tzObservance'
daylight:
$ref: '#/definitions/tzObservance'
attendee:
type: object
properties:
role:
type: string
description: |
The attendee's role -- for example, "chair" or "req-participant".
status:
type: string
description: |
The attendee's status -- for example, "accepted" or "needs-action".
rsvp:
type: boolean
description: true if a response is expected from the attendee.
displayName:
type: string
description: The display name of the attendee.
email:
type: string
description: Email address of the attendee.
userType:
type: string
description: |
The calendar user type -- for example, "individual" or "room".
See the iCalendar CUTYPE property for more details.
organizer:
type: object
properties:
displayName:
type: string
description: Display name of the meeting organizer.
email:
type: string
description: Email address of the meeting organizer.
xProperty:
type: object
properties:
data:
type: string
description: Property value.
event:
type: object
properties:
href:
type: string
description: Relative URL for the event (self) resource.
id:
type: string
description: Universal ID for this event (see iCalendar UID property).
summary:
type: string
description: Event summary.
location:
type: string
description: Event location (see iCalendar LOCATION property).
description:
type: string
description: Event summary (see iCalendar DESCRIPTION property).
start:
$ref: '#/definitions/exDateTime'
end:
$ref: '#/definitions/exDateTime'
last-modified:
type: string
description: Date and time this event was last modified.
class:
type: string
description: Event class (see iCalendar CLASS property).
transparency:
type: string
description: Event transparency (see iCalendar TRANSP property).
sequence:
type: integer
description: Event sequence number (see iCalendar SEQUENCE property).
organizer:
$ref: '#/definitions/organizer'
attendees:
type: array
items:
$ref: '#/definitions/attendee'
recurrenceId:
type: string
description: Identifier for this instance of a recurring event.
recurrenceRule:
type: string
description: Recurrence rule.
exceptDates:
type: array
items:
$ref: '#/definitions/exDateTime'
x-lotus-summarydataonly:
$ref: '#/definitions/xProperty'
x-lotus-appttype:
$ref: '#/definitions/xProperty'
x-lotus-noticetype:
$ref: '#/definitions/xProperty'
x-lotus-broadcast:
$ref: '#/definitions/xProperty'
eventListResponse:
type: object
properties:
events:
type: array
items:
$ref: '#/definitions/event'
eventResponse:
type: object
properties:
timezones:
type: array
items:
$ref: '#/definitions/timeZone'
events:
type: array
items:
$ref: '#/definitions/event'
eventRequest:
type: object
properties:
timezones:
type: array
items:
$ref: '#/definitions/timeZone'
events:
type: array
items:
$ref: '#/definitions/event'
actionRequest:
type: object
properties:
comments:
type: string
description: |
Comments added to any outbound notice associated with
this action.
delegateTo:
type: string
description: |
Specifies the person a meeting is being delegated to.
This only applies to the `delegate` action.
counterStart:
type: string
description: |
Specifies the start date/time for a counter proposal.
This only applies to the `counter` action.
counterEnd:
type: string
description: |
Specifies the end date/time for a counter proposal.
This only applies to the `counter` action.
keepInformed:
type: boolean
description: |
Specifies whether the attendee should be kept informed of
updates to the corresponding event. This only applies to
the `decline` and `delegate` actions.
noticeSummary:
type: object
properties:
summary:
type: string
description: Summary of this notice.
scheduleMethod:
type: string
description: |
Schedule method for this notice -- for example, "request".
See the iCalendar METHOD property for more information.
href:
type: string
description: URL for reading the entire notice in JSON or iCalendar format.
noticeSummariesResponse:
type: object
properties:
notices:
type: array
items:
$ref: '#/definitions/noticeSummary'
noticeResponse:
type: object
properties:
href:
type: string
description: URL for this notice
scheduleMethod:
type: string
description: |
Schedule method for this notice -- for example, "request".
See the iCalendar METHOD property for more information.
timezones:
type: array
items:
$ref: '#/definitions/timeZone'
events:
type: array
items:
$ref: '#/definitions/event'
instance:
type: object
properties:
recurrenceId:
type: string
href:
type: string
instancesResponse:
type: object
properties:
instances:
type: array
items:
$ref: '#/definitions/instance'
errorResponse:
type: object
properties:
code:
type: integer
description: HTTP status code. For example, 400.
text:
type: string
description: HTTP status text. For example, "Bad request".
message:
type: string
description: Request specific error message. For example, "Name not found".
data:
type: string
description: |
Error specific details. When present, this may include
a server-side stack trace.
type:
type: string
description: |
When the type of the `data` property when present.
For example, "text".
# Definitions of common parameters
parameters:
folderParam:
name: folder
in: path
description: Database folder.
required: true
type: string
databaseParam:
name: database
in: path
description: Database name.
required: true
type: string
formatParam:
name: format
in: query
description: |
The desired format of the response. If you omit this
parameter, the response is in JSON format. For iCalendar
format, specify `format=icalendar`.
required: false
type: string
uidParam:
name: uid
in: path
description: Universal ID for this event.
required: true
type: string
recurrenceIdParam:
name: recurrenceId
in: path
description: |
Recurrence ID of the event instance.
required: true
type: string
noticeIdParam:
name: id
in: path
required: true
type: string
description: The notice ID.
actionTypeParam:
name: type
in: query
description: |
The type of action. Legal values include `accept`, `tentative`, `decline`,
`counter`, `delegate`, and `requestInfo`.
required: true
type: string
recurrenceRangeParam:
name: recurrenceRange
in: query
description: |
The range of instances this action should affect. Legal values
include `all`, `future`, and `previous`.
required: false
type: string
workflowParam:
name: workflow
in: query
description: |
If `workflow=false`, the service doesn't send out any notices
associated with this action.
required: false
type: boolean
workflowCommentParam:
name: workflowcomment
in: query
description: |
When updating an existing event, you often want the implied workflow
notice to be sent but you want a comment to be included with the
notice. To do this you add a workflowcomment parameter.
required: false
type: string
literallyParam:
name: literally
in: query
description: |
When you use PUT to update an event and you do not include a
description property, the calendar API preserves the existing the
existing description including attachments. You can override this
behavior by including the parameter `literally=true`.
required: false
type: boolean
strictSequenceParam:
name: strictsequence
in: query
description: |
When you use PUT to update an event and you do not include a
sequence property, the calendar API assumes your update is based
on the latest version of the event. You can override this
behavior by including the parameter `strictsequence=true`.
This parameter is only used for an event with attendees
(a meeting). The default value is `false`.
required: false
type: boolean
eventBody:
name: event
in: body
description: The event definition
required: true
schema:
$ref: '#/definitions/eventRequest'
actionBody:
name: action
in: body
description: The action definition
required: false
schema:
$ref: '#/definitions/actionRequest'
You can’t perform that action at this time.