POST /document/:collection
Headers: See authorization header in the General Remarks
Description: Create a new document into the specified collection. The collection must exist and must have been previously created by the admin.
Body payload Any valid JSON string.
Returns:
NOTE on Record Security Level
The owner can update and delete documents. Their friends (feature not fully implemented) can only see the documents. All other users but the admins cannot have any kind of access to the documents.
PUT /document/:collection/ID
Headers: See authorization header in the General Remarks
Description: Updates the document content. WARNING: the content is replaced, neither added nor merged. Only the owner of the document and the admin, or backoffice users, can modify it.
Body payload Any valid JSON string.
Returns:
GET /document/:collection/ID
Headers: See authorization header in the General Remarks
Description: Retrieves the specified document Only the owner of the document and the admin or backoffice users can retrieve it.
Anonymous users can retrieve documents
Returns:
DELETE /document/:collection/ID
Headers: See authorization header in the General Remarks
Description: Delete a document in the specified collection. Only the owner of the document and the admin or backoffice users can delete it.
Returns:
GET /document/:collection/count
Headers: See authorization header in the General Remarks
Description: Returns the number of documents that the USER COULD READ in a collection. Pay attention because there could be documents that the user cannot read, and therefore are not included
Returns:
GET /document/:collection
Headers: See authorization header in the General Remarks
Description: Returns the documents that the USER CAN READ in a collection. Pay attention because there could be documents that the user cannot read, and therefore will not be retrieved
Returns:
PUT /document/:collection/:id/:action/user/:username
or
PUT /document/:collection/:id/:action/role/:rolename
Headers: See authorization header in the General Remarks
Description: Returns the documents that the USER CAN READ in a collection. where:
- collection is the name of the collection
- id is the unique id of the document belonging to the :collection
- action is the kind of grant you want to give:”read”, “update”, “delete”, “all”
- username is the user to give the grant
- rolename is the name of a role. In this case every user belonging to that role will have the specified grant.
Returns:
To revoke a permission just use DELETE instead of PUT
Available since version 0.7.2
Starting from version 0.7.2 it is possible to update single fields of an object in a collection without sending the whole object JSON representation to the server .
A new endpoint was added to the BaasBox Document API
PUT /document/:collection/:id/(.:fieldName)+
Headers: See authorization header in the General Remarks
Description: Modify a single field specified by the fieldname parameter: the fieldName must start with a . (dot). It could be a simple property or a complex JSON object or even an array using the notation .array[index] where the index is a valid integer.
Body payload: A JSON object with a “data” field (see examples below)
Returns:
We will use the simple object below to explain the new feature modifying its fields:
{"title":"a simple post","content":"the content of this awesome post"}
Saving the object to a posts collection will return the object with the following ID a1b45ea7-7005-4f24-ae5e-76a6840ab856
Let’s say we want to modify the title
Making a PUT request to the following URL /document/posts/a1b45ea7-7005-4f24-ae5e-76a6840ab856/.title and with the following request body
{"data":"this is the new title"}
Will return the following JSON
{
"result": "ok",
"data": {
"@ID": "#24:0",
"@version": 3,
"@class": "posts",
"title": "this is the new title",
"content": "the content of this awesome post",
"id": "a1b45ea7-7005-4f24-ae5e-76a6840ab856"
},
"http_code": 200
}
As you can see we are using a dot before the field name in the URL of the request.
A post without tags is not a real post so let’s add it as an array of strings:
Making a PUT request to the following URL /document/posts/a1b45ea7-7005-4f24-ae5e-76a6840ab856/.tags and with the following request body
{"data":["awesomeness","tag1","tag2"]}
Will return the following JSON:
{
"result": "ok",
"data": {
"@ID": "#24:0",
"@version": 4,
"@class": "posts",
"title": "this is the new title",
"content": "the content of this awesome post",
"id": "a1b45ea7-7005-4f24-ae5e-76a6840ab856",
"tags": [
"awesomeness",
"tag1",
"tag2"
]
},
"http_code": 200
}
As you can see a tags field was added to the object.
Now let’s say that we want to add an element to this tags array:
Making a PUT request to the following URL /document/posts/a1b45ea7-7005-4f24-ae5e-76a6840ab856/.tags[3] with the following request body
{"data":"new tag"}
Will return:
{
"result": "ok",
"data": {
"@ID": "#24:0",
"@version": 5,
"@class": "posts",
"title": "this is the new title",
"content": "the content of this awesome post",
"id": "a1b45ea7-7005-4f24-ae5e-76a6840ab856",
"tags": [
"awesomeness",
"tag1",
"tag2",
"new tag"
]
},
"http_code": 200
}
And what if we want to modify a tag at a specific index?
Making a PUT request to the following URL /document/posts/a1b45ea7-7005-4f24-ae5e-76a6840ab856/.tags[3] with the following request body
{"data":"new tag modified"}
Will return
{
"result": "ok",
"data": {
"@ID": "#24:0",
"@version": 6,
"@class": "posts",
"title": "this is the new title",
"content": "the content of this awesome post",
"id": "a1b45ea7-7005-4f24-ae5e-76a6840ab856",
"tags": [
"awesomeness",
"tag1",
"tag2",
"new tag modified"
]
},
"http_code": 200
}
And what about nested objects:
Making a PUT request to the following URL /document/posts/a1b45ea7-7005-4f24-ae5e-76a6840ab856/.author with the following request body
{"data":{"name":"admin","roles":["admin","superawesome","superuser"]}}
Will return
{
"result": "ok",
"data": {
"@ID": "#24:0",
"@version": 9,
"@class": "posts",
"title": "this is the new title",
"content": "the content of this awesome post",
"id": "a1b45ea7-7005-4f24-ae5e-76a6840ab856",
"tags": [
"awesomeness",
"tag1",
"tag2",
"new tag modified"
],
"author": {
"roles": [
"admin",
"superawesome",
"superuser"
],
"name": "admin"
}
},
"http_code": 200
}
The author object was added and we can also modify its inner properties
Making a PUT request to the following URL /document/posts/a1b45ea7-7005-4f24-ae5e-76a6840ab856/.author/.roles[3] with the following request body
{“data”:”optimus prime”}
Will return:
{
"result": "ok",
"data": {
"@ID": "#24:0",
"@version": 10,
"@class": "posts",
"title": "this is the new title",
"content": "the content of this awesome post",
"id": "a1b45ea7-7005-4f24-ae5e-76a6840ab856",
"tags": [
"awesomeness",
"tag1",
"tag2",
"new tag modified"
],
"author": {
"roles": [
"admin",
"superawesome",
"superuser",
"optimus prime"
],
"name": "admin"
}
},
"http_code": 200
}