Skip to content

API 2.0 spec #222

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
bmeike merged 1 commit into from
Jun 23, 2025
Merged

API 2.0 spec #222

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
43 changes: 24 additions & 19 deletions spec/api/api.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -46,6 +46,11 @@ info:
```

Changes
2.0.0 (06/13/2025)
* This is a breaking change: CBLTest-API-Version is now "2"
* deprecate dataset_version
* In ResetConfiguration, change the value for the "dataset" key to a url.

1.2.1 (06/04/2025)
* Add authenticator property to [/startMultipeerReplicator](#operation/startMultipeerReplicator)

Expand Down Expand Up @@ -330,20 +335,21 @@ paths:
- **updatedBlobs**:

A dictionary whose keys are the key paths into the document to be updated with the blob objects and values are
the blob file names listed in the blob dataset.
the urls from which to retrieve the blobs to be put at the key path location.

The logic to update blobs is similar to the logic when updating properties. The value at the location specified
by the keypath is replaced with the blob object in the object regardless of its type. When a path in the keypath
refers to a non-existent property, the key is added and its value set as a dictionary or an array depending on
by the keypath is replaced with the blob object regardless of the value's type. When a path in the keypath
refers to a non-existent property, the key is added and its value set as a dictionary or an array depending on
the type of the path. When a path in the keypath includes an array index that is out of bounds, the array
is padded with nulls until it is exactly large enough to make the specified index legal.

The blob object is created from the content of the blob file refered by the blob file name, the dictionary value
associated with each key path. If the blob file name refers to non-existing blob file, 400 request error will
be returned.
The blob object is created from the content of the blob file to which the blob url refers: the value associated
with the keypath in the request. If the name of the file retrieved from the url ends with the extension ".zip"
the file is unzipped, first, to recover the blob. If the blob file name refers to non-existing blob file,
a 400 request error will be returned.

The content_type of the blob used when creating a blob object can be detected from the blob file name's extension
as the following rules:
(after it is unzipped, if necessary) according to the following rules:
* "image/jpeg" for the .jpg
* "application/octet-stream" for others

Expand Down Expand Up @@ -1044,10 +1050,10 @@ components:
example: ['people[22].address', 'people[3]']
updatedBlobs:
description: A dictionary whose keys are the key paths into the document to be updated with the
blob objects and values are the blob keys in the dataset.
blob objects and values are the urls from which to obtain the blob files.
type: object
additionalProperties: {}
example: {'photo.thumbnail': 's1.jpg'}
example: {'photo.thumbnail': 'https://media.githubusercontent.com/media/blob/s1.jpg'}
Error:
type: object
required: ['domain', 'code']
Expand Down Expand Up @@ -1084,10 +1090,6 @@ components:
description: The Session ID to appear in the header of all subsequent requests
type: string
example: 'c64aae38-87c1c-4524-823a-e267fc39c3c4'
dataset_version:
description: The version of the dataset to use for this session (default 3.2)
type: string
example: 4.0
logging:
type: object
required: ['url', 'tag']
Expand Down Expand Up @@ -1327,9 +1329,9 @@ components:
* Null or an empty dictionary for creating an empty database.
* A dictionary contains a single key named "collections", with a list of the collection names
as its value, for creating a database with those collections.
* A dictionary contains a single key named contains a key named "dataset",
with a dataset name as its value, for creating a database from the specified dataset
which is a prebuilt database. '
* A dictionary that contains the single key "dataset",
whose value is the url for a dataset. A dataset is a file named <dbname>.cblite2.zip
which when unzipped is the prebuilt database named <dbname>.
type: object
properties:
test:
Expand All @@ -1356,10 +1358,13 @@ components:
example: ["_default.employees", "_default.departments"]
- properties:
dataset:
description: 'Dataset name. Cannot be used together with collections.'
description: 'Dataset url. Cannot be used together with collections.'
type: string
example: "travel"
example: {'db1': {}, 'db2': {'collections': ["_default.employees"]}, 'db3': {'dataset': "travel"}}
example: "https://media.githubusercontent.com/media/couchbaselabs/couchbase-lite-tests/refs/heads/main/dataset/4.0/travel.cblite2.zip"
example: {
'db1': {},
'db2': {'collections': ["_default.employees"]},
'db3': {'dataset': "https://media.githubusercontent.com/media/couchbaselabs/couchbase-lite-tests/refs/heads/main/dataset/4.0/travel.cblite2.zip"}}
ServerInfo:
type: object
required: ['version', 'apiVersion', 'cbl', 'device']
Expand Down