Skip to content
Permalink
Branch: master
Find file Copy path
Find file Copy path
Fetching contributors…
Cannot retrieve contributors at this time
980 lines (910 sloc) 28.2 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'
info:
version: 9.0.1
title: IBM Domino Data API
description: |
The data API provides access to any database for which it is enabled.
The API represents databases, views, view entries, and documents in
JSON format.
**Important**: This version of the OpenAPI spec (**data.yaml**) includes
data 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: database list
description: Read a list of databases.
- name: view list
description: Read a list of views and folders in a database.
- name: view design
description: Read the design of a view or folder.
- name: view entry list
description: Read a list of view or folder entries.
- name: folder
description: Update the contents of a folder.
- name: document
description: Create, read, update or delete a document.
- name: document list
description: Read a list of documents in a database.
paths:
/api/data:
get:
summary: |
Gets a list of databases.
tags: ['database list']
responses:
'200':
description: Successful response
schema:
$ref: '#/definitions/databaseListResponse'
/{folder}/{database}/api/data/collections:
get:
summary: |
Gets a list of views and folders in a database.
tags: ['view list']
parameters:
- $ref: '#/parameters/folderParam'
- $ref: '#/parameters/databaseParam'
responses:
'200':
description: Successful response
schema:
$ref: '#/definitions/viewListResponse'
/{folder}/{database}/api/data/collections/name/{viewName}/design:
get:
summary: |
Gets information on the columns in a view or folder.
tags: ['view design']
parameters:
- $ref: '#/parameters/folderParam'
- $ref: '#/parameters/databaseParam'
- $ref: '#/parameters/viewNameParam'
responses:
'200':
description: Successful response
schema:
$ref: '#/definitions/viewDesignResponse'
'404':
description: The specified view wasn't found.
/{folder}/{database}/api/data/collections/unid/{viewUnid}/design:
get:
summary: |
Gets information on the columns in a view or folder.
tags: ['view design']
parameters:
- $ref: '#/parameters/folderParam'
- $ref: '#/parameters/databaseParam'
- $ref: '#/parameters/viewUnidParam'
responses:
'200':
description: Successful response
schema:
$ref: '#/definitions/viewDesignResponse'
'404':
description: The specified view wasn't found.
/{folder}/{database}/api/data/collections/name/{viewName}:
get:
summary: |
Gets a list of view entries by view name.
tags: ['view entry list']
parameters:
- $ref: '#/parameters/folderParam'
- $ref: '#/parameters/databaseParam'
- $ref: '#/parameters/viewNameParam'
- $ref: '#/parameters/startParam'
- $ref: '#/parameters/countParam'
- $ref: '#/parameters/pageParam'
- $ref: '#/parameters/psParam'
- $ref: '#/parameters/entrycountParam'
- $ref: '#/parameters/searchParam'
- $ref: '#/parameters/searchmaxdocsParam'
- $ref: '#/parameters/sortcolumnParam'
- $ref: '#/parameters/sortorderParam'
- $ref: '#/parameters/startkeysParam'
- $ref: '#/parameters/keysParam'
- $ref: '#/parameters/keysexactmatchParam'
- $ref: '#/parameters/expandlevelParam'
- $ref: '#/parameters/categoryParam'
- $ref: '#/parameters/parentidParam'
- $ref: '#/parameters/systemcolumnsParam'
responses:
'200':
description: Successful response
schema:
$ref: '#/definitions/viewEntryListResponse'
headers:
Content-Range:
description: |
Range and number of items in the response. For example,
`items 0-9/29`
type: string
'404':
description: The specified view wasn't found.
put:
summary: |
Updates the contents of a folder by folder name.
tags: ['folder']
parameters:
- $ref: '#/parameters/folderParam'
- $ref: '#/parameters/databaseParam'
- $ref: '#/parameters/folderNameParam'
-
name: operations
in: body
description: Documents to be added and/or removed.
required: true
schema:
$ref: '#/definitions/folderOperations'
responses:
'200':
description: Successful response
'400':
description: |
Bad request. For example, the server was unable to parse
the JSON input.
/{folder}/{database}/api/data/collections/unid/{viewUnid}:
get:
summary: |
Gets a list of view entries by view UNID.
tags: ['view entry list']
parameters:
- $ref: '#/parameters/folderParam'
- $ref: '#/parameters/databaseParam'
- $ref: '#/parameters/viewUnidParam'
- $ref: '#/parameters/startParam'
- $ref: '#/parameters/countParam'
- $ref: '#/parameters/pageParam'
- $ref: '#/parameters/psParam'
- $ref: '#/parameters/entrycountParam'
- $ref: '#/parameters/searchParam'
- $ref: '#/parameters/searchmaxdocsParam'
- $ref: '#/parameters/sortcolumnParam'
- $ref: '#/parameters/sortorderParam'
- $ref: '#/parameters/startkeysParam'
- $ref: '#/parameters/keysParam'
- $ref: '#/parameters/keysexactmatchParam'
- $ref: '#/parameters/expandlevelParam'
- $ref: '#/parameters/categoryParam'
- $ref: '#/parameters/parentidParam'
- $ref: '#/parameters/systemcolumnsParam'
responses:
'200':
description: Successful response
schema:
$ref: '#/definitions/viewEntryListResponse'
headers:
Content-Range:
description: |
Range and number of items in the response. For example,
`items 0-9/29`
type: string
'404':
description: The specified view wasn't found.
put:
summary: |
Updates the contents of a folder by folder UNID.
tags: ['folder']
parameters:
- $ref: '#/parameters/folderParam'
- $ref: '#/parameters/databaseParam'
- $ref: '#/parameters/folderUnidParam'
-
name: operations
in: body
description: Documents to be added and/or removed.
required: true
schema:
$ref: '#/definitions/folderOperations'
responses:
'200':
description: Successful response
'400':
description: |
Bad request. For example, the server was unable to parse
the JSON input.
/{folder}/{database}/api/data/documents:
post:
summary: |
Creates a new document.
tags: ['document']
parameters:
- $ref: '#/parameters/folderParam'
- $ref: '#/parameters/databaseParam'
- $ref: '#/parameters/formParam'
- $ref: '#/parameters/computeParam'
- $ref: '#/parameters/responseParentidParam'
-
name: document
in: body
description: The document to create.
required: true
schema:
$ref: '#/definitions/document'
responses:
'201':
description: Successful response
headers:
Location:
description: The URL of the new document
type: string
'400':
description: |
Bad request. For example, the server couldn't parse
the JSON input.
get:
summary: |
Gets a list of documents.
description: |
If you don't specify any query parameters,
the response includes all the documents in the database.
To limit the number of documents returned, use the optional
`since` or `search` parameters.
tags: ['document list']
parameters:
- $ref: '#/parameters/folderParam'
- $ref: '#/parameters/databaseParam'
- $ref: '#/parameters/searchParam'
- $ref: '#/parameters/searchmaxdocsParam'
- $ref: '#/parameters/sinceParam'
responses:
'200':
description: Successful response
schema:
$ref: '#/definitions/documentListResponse'
/{folder}/{database}/api/data/documents/unid/{docUnid}:
get:
summary: |
Reads a document.
tags: ['document']
parameters:
- $ref: '#/parameters/folderParam'
- $ref: '#/parameters/databaseParam'
- $ref: '#/parameters/docUnidParam'
- $ref: '#/parameters/hiddenParam'
- $ref: '#/parameters/multipartParam'
- $ref: '#/parameters/strongtypeParam'
- $ref: '#/parameters/lowerCaseFieldsParam'
- $ref: '#/parameters/fieldsParam'
- $ref: '#/parameters/markReadParam'
- $ref: '#/parameters/ifModifiedSinceParam'
responses:
'200':
description: Successful response
schema:
$ref: '#/definitions/document'
headers:
Last-Modified:
description: |
Date and time in RFC 1123 format when this document
was last modified.
type: string
'304':
description: |
The document hasn't been modified since the date in the
request's `If-Modified-Since` header.
'404':
description: The specified document wasn't found.
patch:
summary: |
Updates selected items in a document.
tags: ['document']
parameters:
- $ref: '#/parameters/folderParam'
- $ref: '#/parameters/databaseParam'
- $ref: '#/parameters/docUnidParam'
- $ref: '#/parameters/formParam'
- $ref: '#/parameters/computeParam'
- $ref: '#/parameters/ifUnmodifiedSinceParam'
-
name: document
in: body
description: The document properties to update.
required: true
schema:
$ref: '#/definitions/document'
responses:
'200':
description: Successful response
'400':
description: |
Bad request. For example, the server couldn't parse
the JSON input.
'404':
description: The specified document wasn't found.
'412':
description: |
Precondition failed. This status code is returned only if
the `If-Unmodified-Since` header is included in the request and
the document has been modified since the specified date.
put:
summary: |
Replaces all items in a document.
tags: ['document']
parameters:
- $ref: '#/parameters/folderParam'
- $ref: '#/parameters/databaseParam'
- $ref: '#/parameters/docUnidParam'
- $ref: '#/parameters/formParam'
- $ref: '#/parameters/computeParam'
- $ref: '#/parameters/ifUnmodifiedSinceParam'
-
name: document
in: body
description: The document properties to update.
required: true
schema:
$ref: '#/definitions/document'
responses:
'200':
description: Successful response
'400':
description: |
Bad request. For example, the server couldn't parse
the JSON input.
'404':
description: The specified document wasn't found.
'412':
description: |
Precondition failed. This status code is returned only if
the `If-Unmodified-Since` header is included in the request and
the document has been modified since the specified date.
delete:
summary: |
Deletes a document.
tags: ['document']
parameters:
- $ref: '#/parameters/folderParam'
- $ref: '#/parameters/databaseParam'
- $ref: '#/parameters/docUnidParam'
- $ref: '#/parameters/ifUnmodifiedSinceParam'
responses:
'200':
description: Successful response
'404':
description: The specified document wasn't found.
'412':
description: |
The document has been modified since the date specified by
the `If-Unmodified-Since` header.
# Object definitions
definitions:
link:
type: object
properties:
rel:
type: string
description: Relationship to this resource.
href:
type: string
description: URL to linked resource.
database:
type: object
properties:
'@title':
description: Title of the database.
type: string
'@filepath':
description: File path of the database relative to the Domino data directory.
type: string
'@replicaid':
description: Replica ID of the database.
type: string
'@template':
description: |
File name of the design template of the database, or an empty
string if the database does not have a design template.
type: string
'@href':
description: The URL of the view list resource for the database.
type: string
databaseListResponse:
type: array
items:
$ref: '#/definitions/database'
view:
type: object
properties:
'@title':
description: Title of the view or folder.
type: string
'@folder':
description: |
`false` for a view, `true` for a folder.
type: boolean
'@private':
description: |
`false` for shared, `true` for private.
type: boolean
'@modified':
description: |
Last modification date and time for the view or folder.
type: string
'@unid':
description: Universal ID of the view or folder.
type: string
'@href':
description: The URL of the corresponding view entry list resource.
type: string
viewListResponse:
type: array
items:
$ref: '#/definitions/view'
viewEntry:
type: object
properties:
'@entryid':
description: |
Position of the entry in the view or folder and the universal
ID of any associated document.
type: string
'@noteid':
description: |
The note ID of the document associated with the entry, or an
empty string if the entry is a category or total (systemcolumns
bit 0x0001).
type: string
'@unid':
description: |
The universal ID of the document associated with the entry,
or an empty string if the entry is a category or total
(systemcolumns bit 0x0002).
type: string
'@position':
description: |
Position of the entry in the view or folder (systemcolumns
bit 0x0004).
type: string
'@read':
description: |
`true` if the entry is marked read for the user (systemcolumns
bit 0x0008).
type: boolean
'@siblings':
description: |
The number of siblings of the entry (systemcolumns bit 0x0010).
type: integer
'@descendants':
description: |
The number of descendants of the entry (systemcolumns bit 0x0020).
type: integer
'@children':
description: |
The number of children of the entry (systemcolumns bit 0x0040).
type: integer
'@indent':
description: |
The indent level of the entry (systemcolumns bit 0x0080).
type: integer
'@form':
description: |
The form upon which the document is based (systemcolumns
bit 0x0100).
type: string
'@category':
description: |
`true` if the entry is a category (systemcolumns bit 0x0200).
type: boolean
'@response':
description: |
`true` if the entry is a response (systemcolumns bit 0x0400).
type: boolean
'@href':
description: |
URL for the entry (systemcolumns bit 0x0800).
type: string
'@link':
$ref: '#/definitions/link'
additionalProperties:
type: object
viewEntryListResponse:
type: array
items:
$ref: '#/definitions/viewEntry'
document:
type: object
properties:
'@created':
type: string
description: The date the document was created.
'@modified':
type: string
description: The last modification date of the document.
'@unid':
type: string
description: The universal ID of the document.
'@noteid':
type: string
description: The note ID of the document.
'@href':
type: string
description: The URL of the Document resource.
'@form':
type: string
description: The name of the form used to create the document.
additionalProperties:
type: object
viewColumnDesign:
type: object
properties:
'@columnnumber':
description: |
Position of the column in the view or folder, where 1 is the first column.
type: integer
'@name':
description: |
The name of the column.
type: string
'@title':
description: |
The title of the column.
type: string
'@width':
description: |
The width of the column.
type: integer
'@alignment':
description: |
The alignment of the column.
type: integer
'@hidden':
description: |
`true` if the column is hidden.
type: boolean
'@response':
description: |
`true` if the column is for responses.
type: boolean
'@twistie':
description: |
`true` if the column is a twistie.
type: boolean
'@field':
description: |
`true` if the column is a field.
type: boolean
'@category':
description: |
`true` if the column is a category.
type: boolean
viewDesignResponse:
type: array
items:
$ref: '#/definitions/viewColumnDesign'
folderOperations:
type: object
properties:
add:
type: array
description: Array of UNIDs of documents to add to the folder.
items:
type: string
remove:
type: array
description: Array of UNIDs of documents to remove from the folder.
items:
type: string
documentListEntry:
type: object
properties:
'@modified':
type: string
description: The last modification date of the document.
'@unid':
type: string
description: The universal ID of the document.
'@href':
type: string
description: The URL of the Document resource.
documentListResponse:
type: array
items:
$ref: '#/definitions/documentListEntry'
# Common parameters
parameters:
folderParam:
name: folder
in: path
description: |
Database folder name relative to the Domino data directory. If
the database is not in a folder, use `.` to specify the data
directory itself.
type: string
required: true
databaseParam:
name: database
in: path
description: Database file name.
type: string
required: true
viewNameParam:
name: viewName
in: path
description: Name of a view or folder in the database.
type: string
required: true
viewUnidParam:
name: viewUnid
in: path
description: Universal ID of a view or folder in the database.
type: string
required: true
folderNameParam:
name: viewName
in: path
description: Name of a folder in the database.
type: string
required: true
folderUnidParam:
name: viewUnid
in: path
description: Universal ID of a folder in the database.
type: string
required: true
startParam:
name: start
in: query
description: |
Specifies the starting entry. Defaults to 0 (the first entry).
type: integer
required: false
countParam:
name: count
in: query
description: |
Specifies the number of entries to return. Defaults to 10.
Note: Use `start` and `count` together, or use `ps` and
`page` together.
type: integer
required: false
pageParam:
name: page
in: query
description: |
Page number. The API returns entries based on a multiple of
this parameter and the page size parameter (`ps`).
type: integer
required: false
psParam:
name: ps
in: query
description: |
Page size or the number of entries to return.
type: integer
required: false
entrycountParam:
name: entrycount
in: query
description: |
When `false`, disable the output of the `Content-Range` header
as a performance optimization. The default value is `true`.
type: boolean
required: false
searchParam:
name: search
in: query
description: |
Returns only documents that match a full-text query. An error
occurs if the database is not full-text indexed.
type: string
required: false
searchmaxdocsParam:
name: searchmaxdocs
in: query
description: |
Limits the number of documents returned by a full-text search.
type: integer
required: false
sortcolumnParam:
name: sortcolumn
in: query
description: |
Returns entries sorted on a column. If the column is not sorted
by design or does not exist, this parameter has no effect.
type: string
required: false
sortorderParam:
name: sortorder
in: query
description: |
Specifies the sort order. The parameter value should be either
`ascending` or `descending`. Pair this parameter with `sortcolumn`.
type: string
enum:
- ascending
- descending
required: false
startkeysParam:
name: startkeys
in: query
description: |
Returns sorted entries starting at a specified entry. Pair this
parameter with sortcolumn. Example:
`?sortcolumn=Title&sortorder=ascending&startkeys=Document0020`
type: string
required: false
keysParam:
name: keys
in: query
description: |
Returns entries whose initial characters match keys. Pair this
parameter with sortcolumn. Example:
`?sortcolumn=Title&sortorder=ascending&keys=Document001`
type: string
required: false
keysexactmatchParam:
name: keysexactmatch
in: query
description: |
Returns entries that match keys exactly. Pair this parameter
with keys. Example:
`?sortcolumn=Title&sortorder=ascending&keys=Document001&keysexactmatch=true`
type: boolean
required: false
expandlevelParam:
name: expandlevel
in: query
description: |
Returns only entries at a specified indent level or higher.
type: integer
required: false
categoryParam:
name: category
in: query
description: |
Returns only entries in a specified category.
type: string
required: false
parentidParam:
name: parentid
in: query
description: |
Returns only entries that are descendants of the specified entry
UNID. Example: `parentid=9B8F4A02A5F5254E852578950064EC03`
type: string
required: false
systemcolumnsParam:
name: systemcolumns
in: query
description: |
Limits system data to `@entryid` plus a bit mask formed by adding bit
values from the response properties table. Use hexadecimal or decimal.
For example, `systemcolumns=0x80a` returns only `@entryid`, `@unid`,
`@read`, and `@href`. In decimal format, `systemcolumns=2058` has the
same effect.
type: integer
required: false
docUnidParam:
name: docUnid
in: path
description: Universal ID of the document.
type: string
required: true
formParam:
name: form
in: query
description: |
Associates a database form with the document.
type: string
required: false
computeParam:
name: computewithform
in: query
description: |
When `true`, runs the associated form formulas against the request
data before posting the data. You must identify the form.
type: boolean
required: false
hiddenParam:
name: hidden
in: query
description: |
When `true`, emits hidden properties. Hidden properties have names
beginning with `$`, for example, `"$UpdatedBy":"CN=Admin/O=Your Org"`.
type: boolean
required: false
multipartParam:
name: multipart
in: query
description: |
When `false`, formats rich text as a single HTML part rather than
multipart. The default value is `true`.
type: boolean
required: false
strongtypeParam:
name: strongtype
in: query
description: |
When `true`, displays date-time items as objects with type and data
elements. See the examples. Rich text items always use strongtype
format.
type: boolean
required: false
ifUnmodifiedSinceParam:
name: If-Unmodified-Since
in: header
description: |
Date and time in RFC 1123 time format (for example,
`Tue, 23 Aug 2011 21:35:18 GMT`) as previously returned in the
`Last-Modified` response header of a GET for the same document.
The operation succeeds only if the document has not been modified
since the specified date.
type: string
required: false
ifModifiedSinceParam:
name: If-Modified-Since
in: header
description: |
Date and time in RFC 1123 time format (for example,
`Tue, 23 Aug 2011 21:35:18 GMT`) as previously returned in the
`Last-Modified` response header of a GET for the same document.
The operation succeeds only if the document has been modified
since the specified date.
type: string
required: false
responseParentidParam:
name: parentid
in: query
description: |
Adds the document as a response to the document specified by
the parent UNID.
type: string
required: false
sinceParam:
name: since
in: query
description: |
Returns only documents modified since a specified time. Specify
the time in ISO 8601 format. For example, `2011-08-21T20:21:00Z`.
type: string
required: false
fieldsParam:
name: fields
in: query
description: |
Specifies the list of fields expected in the response. For example,
`fields=FirstName,LastName` limits the JSON response to items matching
those field names. If the document includes items named `EMail` and
`Photo`, they are not included in the response. Use this parameter to
limit the size of the response.
type: string
required: false
lowerCaseFieldsParam:
name: lowercasefields
in: query
description: |
When `true`, the reponse property names are all lower case.
For example, a document item called `FirstName` is represented as
`firstname` in the JSON response. This parameter can help resolve
issues caused by inconsistent naming of items across documents
(`FirstName` in one document and `FIRSTNAME` in another.)
type: boolean
required: false
markReadParam:
name: markread
in: query
description: |
When `false`, the document is not marked read for the authenticated
user. When `true`, the document is marked read. When this parameter
is omitted, the default value is `true`.
type: boolean
required: false
You can’t perform that action at this time.