DB and Collections

General notes

  • data follow the strict mode representation of BSON, e.g. {"_id": {"$oid":"568106e67d3126b74dc5f9af"}} for ObjectId
  • the root embeds collections
  • dbs have properties and embed collections and file buckets

Notes on READ operations

  • use page and pagesize query parameters for pagination
  • specify np (no properties) query paramenter to exclude properties from the request, i.e only embedded data.

Notes on WRITE operations

  • PATCH modifies the passed properties while PUT replaces the whole properties set
  • all write operation can use the dot notation and all mongodb update operators
  • server or client can optionally require to check the ETag to avoid ghost writes, but by default DELETE /db and DELETE /db/coll requires it
Request Description
GET / returns the paginated, existing dbs
PUT /db {"descr": "my first db"} upserts the db db
PATCH /db {"number": 1} modifies the db db
DELETE /db If-Match:<Etag> deletes the db db
GET /db returns the properties and the paginated collections and file buckets of db
PUT /db/coll {"descr": "my first collection"} upserts the collection db.coll
PATCH /db/coll {"number": 1} modifies the properties of the collection db.coll
PUT /db/coll/_indexes/name_idx { "keys":{"name":1} } create the index name_idx in the collection db.coll
DELETE /db/coll If-Match:<Etag> deletes the collection db.coll

Documents

General notes

  • use the strict mode representation of BSON, e.g. {"_id": {"$oid":"568106e67d3126b74dc5f9af"}} for ObjectId
  • use shardkey query parameter to eventually specify the shard keys, e.g. shardkey={"sk":"value"}

Notes on READ operations

  • use page and pagesize query parameters for pagination
  • specify np (no properties) query paramenter to exclude the collection properties from GET /db/coll response.
  • keys query parameter defines the properties to return (projection), e.g. keys={"a":1, "obj.prop":1}
  • filter query parameter specifies a mongodb query, e.g. filter={"n":{"$gt":5}}
  • use id_type optional query parameter to properly identify docs /db/coll/1 (string) vs /db/coll/1?id_type=number

Notes on WRITE operations

  • PATCH modifies the passed properties while PUT replaces the whole properties set
  • if the _id is not specified, it will be generated as a new ObjectId
  • all write operation can use the dot notation and all mongodb update operators
  • server or client can optionally requires to check the ETag to avoid ghost writes
Request Description
GET /db/coll returns the properties and the paginated documents of db.coll
GET /db/coll/doc returns the document doc
POST /db/coll {"_id": "doc", "n": 1} upsert a document in collection db.coll
POST /db/coll [ {"n": 1}, ... , {"n": 10} ] bulk upsert documents in db.coll
PUT /db/coll/doc {"$inc":{"obj.n":1}} upsert the document doc
PATCH /db/coll/doc {"n": 1} modifies the document doc
PATCH /db/coll/*?filter={"n":{"$lt":1}} {"n": 1} bulk modifies the documents matching the filter in db.coll
DELETE /db/coll/doc deletes the document doc
DELETE /db/coll/*?filter={"n":{"$gt":100}} bulk deletes the documents matching the filter in db.coll

Files

General notes

  • files are immutable: they cannot be modified
  • same notes for documents apply for files, e.g. the filter query parameter
  • file are automatically given the fileType property
Request Description
PUT /db/bucket.files {"descr": "my first file bucket"} upserts the file bucket db.bucket; the .files suffix marks it as a file bucket
PATCH /db/bucket.files {"number": 1} modifies the properties of the file bucket db.bucket;
GET /db/bucket.files returns the properties and the paginated files of db.bucket
GET /db/bucket.files/file returns the properties of file file
GET /db/bucket.files/file/binary returns the binary content of file file
POST /db/bucket.files properties={"a": 1} file=<binary>

creates an immutable file in bucket db.bucket

note this is a multipart request

PUT /db/bucket.files/file properties={"a": 1} file=<binary>

creates the immutable file file in the bucket db.bucket

note this is a multipart request

DELETE /bucket.files/coll/file deletes the file file