Folders /folders
¶
Folders endpoint provides folders data, structure and contents management: search, create, modify folders, add or remove contents, reorder data, organize folders tree, etc.
Mainly it provides:
- manage data: retrieve, create, modify or remove folders
- manage tree: retrieve parent folder data, set or remove a parent folder association
- manage contents: add, remove, search/get, reorder folders contents
Note: in the following paragraphs, (folder_id)
and {folderId}
are sample placeholders for the unique identifier of the folder, typically an integer number;
other placeholders used in this page are {parentId}
, {relatedId}
, {rightId}
, {leftId}
, {createdDate}
, {modifiedDate}
and {revisionNumber}
.
Folders data¶
Get data¶
-
GET
/folders
¶
All folders retrieval is performed through GET /folders
.
Folders endpoint provides several filters to obtain data.
Usual filters, like Field filter or Search Query filter, are available; extra filters are roots
and parent
.
Filter roots
provides a method to fetch only root folders.
Usage: GET /folders?filter[roots]
.
Filter parent
allows you to obtain folders whose parent is a specific folder, by ID.
Usage: GET /folders?filter[parent]={parentId}
.
When the api call is successfull, response with 200 OK
http status code is returned.
Example request (get root folders):
GET /folders?filter[roots] HTTP/1.1
Host: example.com
Accept: application/vnd.api+json
Example response:
HTTP/1.1 200 OK
Content-Type: application/vnd.api+json
{
"data": [
{
"id": "{folderId1}",
"type": "folders",
"attributes": {
"title": "Sample root",
},
"meta": {
"created": "{createdDate}",
"modified": "{modifiedDate}",
"path": "/{folderId}"
},
"links": {
"self": "https://example.com/folders/{folderId1}"
},
"relationships": {
"children": {
"links": {
"related": "https://example.com/folders/{folderId1}/children",
"self": "https://example.com/folders/{folderId1}/relationships/children"
}
},
"parent": {
"links": {
"related": "https://example.com/folders/{folderId1}/parent",
"self": "https://example.com/folders/{folderId1}/relationships/parent"
}
}
}
},
{
"id": "{folderId2}",
"type": "folders",
"attributes": {
"title": "Root Folder",
},
"meta": {
"created": "{createdDate}",
"modified": "{modifiedDate}",
"path": "/{folderId2}"
},
"links": {
"self": "https://example.com/folders/{folderId2}"
},
"relationships": {
"children": {
"links": {
"related": "https://example.com/folders/{folderId2}/children",
"self": "https://example.com/folders/{folderId2}/relationships/children"
}
},
"parent": {
"links": {
"related": "https://example.com/folders/{folderId2}/parent",
"self": "https://example.com/folders/{folderId2}/relationships/parent"
}
}
}
}
],
"links": {
"self": "https://example.com/folders?filter%5Broots%5D=",
"home": "https://example.com/home",
"first": "https://example.com/folders?filter%5Broots%5D=",
"last": "https://example.com/folders?filter%5Broots%5D=",
"prev": null,
"next": null
},
"meta": {
"pagination": {
"count": 2,
"page": 1,
"page_count": 1,
"page_items": 2,
"page_size": 20
},
"schema": {
"folders": {
"$id": "https://example.com/model/schema/folders",
"revision": "{revisionNumber}"
}
}
}
}
Get data for a single folder¶
-
GET
/folders/
(folder_id)¶
Retrieve folder details by folder unique identifier.
Example request (get a folder by ID):
GET /folders/{folderId} HTTP/1.1
Host: example.com
Accept: application/vnd.api+json
Example response:
HTTP/1.1 200 OK
Content-Type: application/vnd.api+json
{
"data": {
"id": "{folderId}",
"type": "folders",
"attributes": {
"title": "Root Folder"
},
"meta": {
"created": "{createdDate}",
"modified": "{modifiedDate}",
"path": "/{folderId}"
},
"relationships": {
"children": {
"links": {
"related": "https://example.com/folders/{folderId}/children",
"self": "https://example.com/folders/{folderId}/relationships/children"
}
},
"parent": {
"links": {
"related": "https://example.com/folders/{folderId}/parent",
"self": "https://example.com/folders/{folderId}/relationships/parent"
}
}
}
},
"links": {
"self": "https://example.com/folders/{folderId}",
"home": "https://example.com/home"
},
"meta": {
"schema": {
"folders": {
"$id": "https://example.com/model/schema/folders",
"revision": "{revisionNumber}"
}
}
}
}
Create a folder¶
-
POST
/folders
¶
You can create folders by using POST /folders
endpoint.
Folders data must be specified inside body JSON data.
Request body structure is:
{
"data": {
"type": "folders",
"attributes": {}
}
}
Example request (create sample folder):
POST /folders HTTP/1.1
Host: example.com
Accept: application/vnd.api+json
Content-Type: application/vnd.api+json
{
"data": {
"type": "folders",
"attributes": {
"title": "Root Folder"
}
}
}
Expected response is HTTP/1.1 201 Created
, with application/vnd.api+json
body data representing the folder just created.
When folder already exists or data is not valid (i.e. data lacks of required fields), POST fails and response is 400 Bad Request - Invalid data
.
Successful response example follows:
HTTP/1.1 201 Created
Content-Type: application/vnd.api+json
{
"data": {
"id": "{folderId}",
"type": "folders",
"attributes": {
"uname": "root-folder",
"title": "Root Folder"
},
"meta": {
"created": "{createdDate}",
"modified": "{modifiedDate}",
"path": "/{folderId}"
},
"relationships": {
"children": {
"links": {
"related": "https://example.com/folders/{folderId}/children",
"self": "https://example.com/folders/{folderId}/relationships/children"
}
},
"parent": {
"links": {
"related": "https://example.com/folders/{folderId}/parent",
"self": "https://example.com/folders/{folderId}/relationships/parent"
}
}
}
},
"links": {
"self": "https://example.com/folders",
"home": "https://example.com/home"
},
"meta": {
"schema": {
"folders": {
"$id": "https://example.com/model/schema/folders",
"revision": "{revisionNumber}"
}
}
}
}
Modify a folder¶
-
PATCH
/folders/
(folder_id)¶
A folder can be modified by calling a PATCH /folders/(folder_id)
with proper payload.
Necessary fields in payload are data.id
, data.type
and data.attributes
(not empty).
Example request (modify a folder title):
PATCH /folders/{folderId} HTTP/1.1
Host: example.com
Accept: application/vnd.api+json
{
"data": {
"id": "{folderId}",
"type": "folders",
"attributes": {
"title": "My new folder"
}
}
}
Remove a folder¶
-
DELETE
/folders/
(folder_id)¶
Move a folder to trash (soft delete) using DELETE /folders/{folderId}
.
Expected HTTP status response is 204 No Content
and an empty body is returned.
Example request (delete a folder):
DELETE /folders/{folderId} HTTP/1.1
Host: example.com
Example response:
HTTP/1.1 204 No Content
Folders tree¶
Get the parent¶
-
GET
/folders/
(folder_id)/parent
¶
When a folder is not a root folder (it’s a subfolder), parent folder data can be retrieved.
You can obtain data of parent folder, for a specified subfolder, using GET /folders/(folder_id)/parent
, as in following example.
Example request (get a parent folder):
GET /folders/{folderId}/parent HTTP/1.1
Host: example.com
Accept: application/vnd.api+json
Example response:
HTTP/1.1 200 OK
Content-Type: application/vnd.api+json
{
"data": {
"id": "{folderId}",
"type": "folders",
"attributes": {
"title": "Root Folder"
},
"meta": {
"created": "{createdDate}",
"modified": "{modifiedDate}",
"path": "/{folderId}",
"relation": {
"id": {relationId},
"object_id": {relatedId},
"parent_id": {folderId},
"root_id": {folderId},
"parent_node_id": {parentId},
"tree_left": {leftId},
"tree_right": {rightId},
"depth_level": 1,
"menu": true
}
},
"relationships": {
"children": {
"links": {
"related": "https://example.com/folders/{folderId}/children",
"self": "https://example.com/folders/{folderId}/relationships/children"
}
},
"parent": {
"links": {
"related": "https://example.com/folders/{folderId}/parent",
"self": "https://example.com/folders/{folderId}/relationships/parent"
}
}
}
},
"links": {
"available": "https://example.com/objects?filter%5Btype%5D%5B0%5D=folders",
"self": "https://example.com/folders/{folderId}/parent",
"home": "https://example.com/home"
},
"meta": {
"schema": {
"folders": {
"$id": "https://example.com/model/schema/folders",
"revision": "{revisionNumber}"
}
}
}
}
data.meta.relations
contains the tree details for the folder (nested set model has been used to store folders tree data).
Set the parent¶
-
PATCH
/folders/
(folder_id)/relationships/parent
¶
When you want to set a parent for a folder, you need to call a PATCH
, specifying the folder identifier in the url and the parent identifier in body payload.
Example request (set a parent folder):
PATCH /folders/{folderId}/relationships/parent HTTP/1.1
Host: example.com
Accept: application/vnd.api+json
{
"data": {
"type": "folders",
"id": "{parentId}"
}
}
Example response:
HTTP/1.1 200 OK
Content-Type: application/vnd.api+json
{
"links": {
"self": "https://example.com/folders/{folderId}/relationships/parent",
"home": "https://example.com/home"
}
}
Remove the parent¶
-
DELETE
/folders/
(folder_id)/relationships/parent
¶
When you want a folder be a root, you remove its association with the parent.
Removing folder parent association is performed through DELETE /folders/{folderId}/relationships/parent
,
specifying parent id in the body payload body, like in the Set the parent.
Expected HTTP status response is 204 No Content
and an empty body is returned.
Example request (remove a parent):
DELETE /folders/{folderId}/relationships/parent HTTP/1.1
Host: example.com
Accept: application/vnd.api+json
{
"data": {
"type": "folders",
"id": "{parentId}"
}
}
Example response:
HTTP/1.1 204 No Content
Folders contents¶
Get contents¶
-
GET
/folders/
(folder_id)/children
¶
Contents inside a folder are retrieved through GET /folders/(folder_id)/children
;
usual filters, like Field filter or Search Query filter, are available.
Add content¶
-
POST
/folders/{folderId}/relationships/children
¶
You can save contents inside a folder using properly POST /folders/{folderId}/relationships/children
.
Payload body must contain content object type
and content identifier id
, like in the following example.
Example request (add a content to a folder):
POST /folders/{folderId}/relationships/children HTTP/1.1
Host: example.com
Accept: application/vnd.api+json
{
"data": [
{
"type": "{contentTypeName}",
"id": "{contentId}"
}
]
}
Example response:
HTTP/1.1 200 OK
Content-Type: application/vnd.api+json
Remove content¶
-
DELETE
/folders/{folderId}/relationships/children
¶
Removing contents is performed through DELETE /folders/{folderId}/relationships/children
.
Payload body must contain content object type
and content identifier id
, like in the Add content.
Expected HTTP status response is 204 No Content
and an empty body is returned.
Example request (remove a content from a folder):
DELETE /folders/{folderId}/relationships/children HTTP/1.1
Host: example.com
Accept: application/vnd.api+json
{
"data": [
{
"type": "{contentTypeName}",
"id": "{contentId}"
}
]
}
Example response:
HTTP/1.1 204 No Content