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