Objects /objects

Get an object

GET /objects/(object_id)

Get an object detail.

Request Headers:
 
Parameters:
  • object_id (int|string) – identify a BEdita object. It can be the object id or the object unique name (nickname)
Query Parameters:
 
  • filter[object_type] (string) – the object type or a comma separated list of object types requested
  • filter[query] (string) – used for fulltext search
  • embed[relations] (string) – used for embedding related objects in relations key. For example embed[relations]=attach|3,seealso|2 will embed 3 objects related by “attach” and 2 related by “seealso” to main object. If no number is specified then only one relation will be embed i.e. embed[relations]=poster is the same of embed[relations]=poster|1. See the example.
  • page (int) – the page requested
  • page_size (int) – the page dimension
Response Headers:
 
Status Codes:

Note

Note that the response data fields can change depending of BEdita object type exposed and configuration.

Example request:

GET /objects/15 HTTP/1.1
Host: example.com
Accept: application/json, text/javascript

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "api": "objects",
    "data": {
        "object": {
            "id": 15,
            "start_date": "2015-01-08T00:00:00+0100",
            "end_date": null,
            "subject": null,
            "abstract": null,
            "body": "This is the body text",
            "object_type_id": 22,
            "created": "2015-01-30T10:04:49+0100",
            "modified": "2015-05-08T12:59:49+0200",
            "title": "hello world",
            "nickname": "hello-world",
            "description": "the description",
            "valid": true,
            "lang": "eng",
            "rights": "",
            "license": "",
            "creator": "",
            "publisher": "",
            "note": null,
            "comments": "off",
            "publication_date": "2015-01-08T00:00:00+0100",
            "languages": {
                "ita": {
                    "title": "ciao mondo"
                }
            },
            "relations": {
                "attach": {
                    "count": 8,
                    "url": "https://example.com/api/objects/15/relation/attach"
                },
                "seealso": {
                    "count": 2,
                    "url": "https://example.com/api/objects/15/relation/seealso"
                }
            },
            "object_type": "Document",
            "authorized": true,
            "free_access": true,
            "custom_properties": {
                "bookpagenumber": "12",
                "number": "8"
            },
            "geo_tags": [
                {
                    "id": 68799,
                    "object_id": 218932,
                    "latitude": 44.4948179,
                    "longitude": 11.33969,
                    "address": "via Rismondo 2, Bologna",
                    "gmaps_lookats": {
                        "zoom": 16,
                        "mapType": "k",
                        "latitude": 44.4948179,
                        "longitude": 11.33969,
                        "range": 44052.931589613
                    }
                }
            ],
            "tags": [
                {
                    "label": "tag one",
                    "name": "tag-one"
                },
                {
                    "label": "tag two",
                    "name": "tag-two"
                }
            ],
            "categories": [
                {
                    "id": 266,
                    "area_id": null,
                    "label": "category one",
                    "name": "category-one"
                },
                {
                    "id": 323,
                    "area_id": null,
                    "label": "category two",
                    "name": "category-two"
                }
            ]
        }
    },
    "method": "get",
    "params": [],
    "url": "https://example.com/api/objects/15"
}

Note

Every object can have relations with other objects. The count of objects related is in data.object.relations.<relation_name> where there are count (the number of related objects) and url fields. The url is the complete API request url to get the object related, for example https://example.com/api/objects/15/relations/attach

Embedding related objects

Requests with embed[relations] query string will add objects key to data.object.relations.<relation_name>, for example

GET /objects/15?embed[relations]=attach|3,seealso|2 HTTP/1.1

will have as relations key

{
    "relations": {
        "attach": {
            "count": 8,
            "url": "https://example.com/api/objects/15/relation/attach",
            "objects": [
                {
                    "id": 13,
                    "title": "attach one"
                },
                {
                    "id": 21,
                    "title": "attach two"
                },
                {
                    "id": 22,
                    "title": "attach three"
                }
            ]
        },
        "seealso": {
            "count": 2,
            "url": "https://example.com/api/objects/15/relation/seealso",
            "objects": [
                {
                    "id": 30,
                    "title": "seealso one"
                },
                {
                    "id": 31,
                    "title": "seealso two"
                }
            ]
        }
    }
}

where the objects collections have been simplified but every item inside them is a complete object.

Note

If object_id corresponds to a section or a publication then the response will contain data.object.children with the total count of children, count of contents, count of sections and the related url.

{
    "children": {
        "count": 14,
        "url": "https://example.com/api/objects/1/children",
        "contents": {
            "count": 12,
            "url": "https://example.com/api/objects/1/contents"
        },
        "sections": {
            "count": 2,
            "url": "https://example.com/api/objects/1/sections"
        }
    }
}

Get a collection of objects

The /objects endpoint can be used to retrieve a collection of objects.

GET /objects

It returns a collection of objects:

  • if called with id query string parameter the response will contain a collection of the objects requested
  • else it returns a paginated list of objects that are descendants of the related publication configured in app/config/frontend.ini.php.

Important

Note that when id query string is used, no other parameters is valid but access token.

The response will be an array of objects as shown below.

Request Headers:
 
Query Parameters:
 
  • filter[object_type] (string) – the object type or a comma separated list of object types requested
  • filter[query] (string) – used for fulltext search
  • embed[relations] (string) – used for embedding related objects in relations key. For example embed[relations]=attach|3,seealso|2 will embed 3 objects related by “attach” and 2 related by “seealso” to main object. If no number is specified then only one relation will be embed i.e. embed[relations]=poster is the same of embed[relations]=poster|1. See the example.
  • page (int) – the page requested
  • page_size (int) – the page dimension
  • id – a comma separated list of object ids. See the important note above. The max number of ids you can request is defined by ApiBaseController::$paginationOptions['maxPageSize']
Response Headers:
 
Status Codes:
  • 200 OK – Success
  • 400 Bad Request – Malformed request
  • 401 Unauthorized – The request is not authorized to access to protected publication
  • 403 Forbidden – The request is authorized but without sufficient permissions to access to protected publication

Example request:

GET /objects HTTP/1.1
Host: example.com
Accept: application/json, text/javascript

Example response:

For readability the fields of objects are limited to “title” but they are similar to GET /objects/(object_id) example

HTTP/1.1 200 OK
Content-Type: application/json

{
    "api": "objects",
    "data": {
        "objects": [
            {
                "id": 2,
                "title": "title one"
            },
            {
                "id": 3,
                "title": "title two"
            },
            {
                "id": 4,
                "title": "title three"
            },
            {
                "id": 5,
                "title": "title four"
            },
            {
                "id": 6,
                "title": "title five"
            }
        ]
    },
    "method": "get",
    "paging": {
        "page": 1,
        "page_size": 5,
        "page_count": 5,
        "total": 50,
        "total_pages": 10
    },
    "params": [],
    "url": "https://example.com/api/objects/1/children"
}

Get object’s children

GET /objects/(object_id)/children

Return the paginated children of object object_id. The object has to be a section or the publication.

Request Headers:
 
Parameters:
  • object_id (int|string) – identify a BEdita object. It can be the object id or the object unique name (nickname)
Query Parameters:
 
  • filter[object_type] (string) – the object type or a comma separated list of object types requested
  • filter[query] (string) – used for fulltext search
  • embed[relations] (string) – used for embedding related objects in relations key. For example embed[relations]=attach|3,seealso|2 will embed 3 objects related by “attach” and 2 related by “seealso” to main object. If no number is specified then only one relation will be embed i.e. embed[relations]=poster is the same of embed[relations]=poster|1. See the example.
  • page (int) – the page requested
  • page_size (int) – the page dimension
Response Headers:
 
Status Codes:

Get object’s children of type section

GET /objects/(object_id)/sections

Return the paginated children of object object_id. The object has to be a section or the publication. The children are just sections (section BEdita object type)

Request Headers:
 
Parameters:
  • object_id (int|string) – identify a BEdita object. It can be the object id or the object unique name (nickname)
Query Parameters:
 
  • filter[query] (string) – used for fulltext search
  • page (int) – the page requested
  • page_size (int) – the page dimension
Response Headers:
 
Status Codes:

Get object’s children of type contents

GET /objects/(object_id)/contents

Return the paginated children of object object_id. The object has to be a section or the publication. The children are other than sections.

Request Headers:
 
Parameters:
  • object_id (int|string) – identify a BEdita object. It can be the object id or the object unique name (nickname)
Query Parameters:
 
  • filter[object_type] (string) – the object type or a comma separated list of object types requested. “section” object type is not accepted
  • filter[query] (string) – used for fulltext search
  • page (int) – the page requested
  • page_size (int) – the page dimension
Response Headers:
 
Status Codes:

Get object’s descendants

GET /objects/(object_id)/descendants

Return the paginated children of object object_id. The object has to be a section or the publication. The children are other than sections.

Request Headers:
 
Parameters:
  • object_id (int|string) – identify a BEdita object. It can be the object id or the object unique name (nickname)
Query Parameters:
 
  • filter[object_type] (string) – the object type or a comma separated list of object types requested
  • filter[query] (string) – used for fulltext search
  • embed[relations] (string) – used for embedding related objects in relations key. For example embed[relations]=attach|3,seealso|2 will embed 3 objects related by “attach” and 2 related by “seealso” to main object. If no number is specified then only one relation will be embed i.e. embed[relations]=poster is the same of embed[relations]=poster|1. See the example.
  • page (int) – the page requested
  • page_size (int) – the page dimension
Response Headers:
 
Status Codes:

Get object’s siblings

GET /objects/(object_id)/siblings

Return the paginated siblings of object object_id.

Request Headers:
 
Parameters:
  • object_id (int|string) – identify a BEdita object. It can be the object id or the object unique name (nickname)
Query Parameters:
 
  • filter[object_type] (string) – the object type or a comma separated list of object types requested
  • filter[query] (string) – used for fulltext search
  • embed[relations] (string) – used for embedding related objects in relations key. For example embed[relations]=attach|3,seealso|2 will embed 3 objects related by “attach” and 2 related by “seealso” to main object. If no number is specified then only one relation will be embed i.e. embed[relations]=poster is the same of embed[relations]=poster|1. See the example.
  • page (int) – the page requested
  • page_size (int) – the page dimension
Response Headers:
 
Status Codes:

Get relations count

GET /objects/(object_id)/relations

Returns a summary of relations information about object object_id. It shows every relation with the count and the url to get the related objects detail.

Request Headers:
 
Parameters:
  • object_id (int|string) – identify a BEdita object. It can be the object id or the object unique name (nickname)
Query Parameters:
 
  • filter[object_type] (string) – the object type or a comma separated list of object types requested
  • filter[query] (string) – used for fulltext search
  • embed[relations] (string) – used for embedding related objects in relations key. For example embed[relations]=attach|3,seealso|2 will embed 3 objects related by “attach” and 2 related by “seealso” to main object. If no number is specified then only one relation will be embed i.e. embed[relations]=poster is the same of embed[relations]=poster|1. See the example.
  • page (int) – the page requested
  • page_size (int) – the page dimension
Response Headers:
 
Status Codes:

Example request:

GET /objects/15/relations HTTP/1.1
Host: example.com
Accept: application/json, text/javascript

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "api": "objects",
    "data": {
        "attach": {
            "count": 1,
            "url": "https://example.com/api/objects/1/relations/attach"
        },
        "seealso": {
            "count": 2,
            "url": "https://example.com/api/objects/1/relations/seealso"
        }
    },
    "method": "get",
    "params": [],
    "url": "https://example.com/api/objects/1/relations"
}

Get the relation detail between objects

Returns the relation detail between object object_id and related_id.

Request Headers:
 
Parameters:
  • object_id (int|string) – identify a BEdita object. It can be the object id or the object unique name (nickname)
  • relation_name (string) – the name of the relation that ties object_id and related_id
  • related_id (int) – the object id of the related object
Response Headers:
 
Status Codes:

Example request:

GET /objects/15/relations/attach/23 HTTP/1.1
Host: example.com
Accept: application/json, text/javascript

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "api": "objects",
  "data": {
    "priority": 3,
    "params": {
      "label": "here the label"
    }
  },
  "method": "get",
  "params": [],
  "url": "https://example.com/api/objects/1/relations/attach/2"
}

Get the child position

GET /objects/(object_id)/children/(int: child_id)

Return the position (priority key) of child_id relative to all children of parent object object_id

Request Headers:
 
Parameters:
  • object_id (int|string) – identify a BEdita object. It can be the object id or the object unique name (nickname)
  • child_id (int) – the object id of the child of object object_id
Response Headers:
 
Status Codes:

Example request:

GET /objects/1/children/2 HTTP/1.1
Host: example.com
Accept: application/json, text/javascript

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "api": "objects",
  "data": {
    "priority": 3
  },
  "method": "get",
  "params": [],
  "url": "https://example.com/api/objects/1/children/2"
}

Create an object

POST /objects

Create a new BEdita object type.

Important

To write an object it has to be configured to be writable

$config['api'] = array(
    // ....
    'validation' => array(
        // to save 'document' and 'event' object types
        'writableObjects' => array('document', 'event')
    )
);

The request body has to be a JSON as

{
    "data": {}
}

where inside "data" are placed all fields to save. User has to be authenticated and "data": {} must contain:

  • object_type i.e. the object type you want to create
  • at least a parent (parents key) accessible (with right permission for user authorized) on publication tree or at least a relation (relations key) with another object reachable (where reachable means an accessible object on tree or related to an accessible object on tree).

Required keys in JSON are shown below.

Request Headers:
 
Request JSON Object:
 
  • data.object_type (string) – (required) the object type to create
  • data.parents (array) – (required if data.relations with conditions specified below missing) a list of parents. Parents must be accessible (with right permission for user authorized) on publication tree
  • data.relations (object) –

    (required if data.parents with conditions specified above missing) an object of relations where the keys are the relations’ names. Every relation contains an array of objects of related_id and optionally of relation params

    {
        "name1": [
            {
                "related_id": 1
            },
            {
                "related_id": 2,
                "params": {
                    "name_param_one": "value param one",
                    "name_param_two": "value param two"
                }
            }
        ],
        "name2": [
            {
                "related_id": 3
            }
        ]
    }
    
  • data.custom_properties (object) –

    (optional) a list of custom properties to save. Set a custom property to null to delete it. For custom properties that supports multi options an array of values can be passed. Custom properties types are checked before save, so if type is number its value must be numeric, if it’s date its value must be a compatibile ISO 8601 format.

    {
        "custom_properties": {
            "custom_name_text": "my text here",
            "custom_name_number": 12,
            "custom_name_date": "2015-12-15T09:29:00+02:00",
            "custom_name_multiple": ["one", "two", "three"],
            "custom_name_to_remove": null
        }
    }
    
Response Headers:
 
  • Content-Type – application/json
  • Location – The url to the resource just created https://example.com/objects/(object_id)
Status Codes:

Example request:

POST /objects HTTP/1.1
Host: example.com
Accept: application/json, text/javascript
Content-Type: application/json

{
    "data": {
        "title": "My title",
        "object_type": "event",
        "description": "bla bla bla",
        "parents": [1, 34, 65],
        "relations": {
            "attach": [
                {
                    "related_id": 12,
                    "params": {
                        "label": "foobar"
                    }
                },
                {
                    "related_id": 23
                }
            ],
            "seealso": [
                {
                    "related_id": 167
                }
            ]
        },
        "categories": ["name-category-one", "name-category-two"],
        "tags": ["name-tag_one", "name-tag-two"],
        "geo_tags": [
            {
                "title": "geo tag title",
                "address": "via ....",
                "latitude": 43.012,
                "longitude": 10.45
            }
        ],
        "date_items": [
            {
                "start_date": "2015-07-08T15:00:35+0200",
                "end_date": "2015-07-08T15:00:35+0200",
                "days": [0,3,4]
            },
            {
                "start_date": "2015-09-01T15:00:35+0200",
                "end_date": "2015-09-30T15:00:35+0200"
            }
        ]
    }
}

Example response:

HTTP/1.1 201 Created
Content-Type: application/json

{
  "api": "objects",
  "data": {
      "id": 45,
      "title": "My title",
      "object_type": "event",
      "description": "bla bla bla"
  },
  "method": "post",
  "params": [],
  "url": "https://example.com/api/objects"
}

The response payload contains the created object detail. In the example above only some fileds are shown.

dates must be in ISO 8601 format.

Update an object

POST /objects

Update an existent object.

Important

To write an object it has to be configured to be writable

$config['api'] = array(
    // ....
    'validation' => array(
        // to save 'document' and 'event' object types
        'writableObjects' => array('document', 'event')
    )
);

POST request can be also used to update an existent object. In that case the object id has to be passed in "data" (as creating object) and object_type can be omitted.

Request Headers:
 
Request JSON Object:
 
  • data.id (string) – (required) the id of the object to update
Response Headers:
 
Status Codes:

Create or update relations between objects

POST /objects/(object_id)/relations/(string: relation_name)

Create relations relation_name between object_id and other objects. If the relation between objects already exists then it will be updated.

Request data must be an array of relation data or only a relation data if you need to save only one relation.

Request Headers:
 
Request JSON Array of Objects:
 
  • related_id (string) – (required) the related object id
  • params (string) – (optional) it depends from relation type
  • priority (string) – (optional) is the position of the relation. Relation with lower priority are shown before.
Response Headers:
 
Status Codes:

Example request to create/update only one relation:

POST /objects/3/relations/attach HTTP/1.1
Host: example.com
Accept: application/json, text/javascript
Content-Type: application/json

{
    "data": {
        "related_id": 34,
        "priority": 3
    }
}

Example request to create/update a bunch of relations:

POST /objects/3/relations/attach HTTP/1.1
Host: example.com
Accept: application/json, text/javascript
Content-Type: application/json

{
    "data": [
        {
            "related_id": 15,
            "params": {
                "label": "my label"
            }
        },
        {
            "related_id": 28
        }
    ]
}

Example response:

HTTP/1.1 201 Created
Host: example.com
Location: https://example.com/objects/3/relations/attach
Accept: application/json, text/javascript
Content-Type: application/json

The response body will be the same as GET /objects/(object_id)/relations/(string:relation_name)

Replace relation data between objects

Replace the relation relation_name data between object_id and related_id.

Request Headers:
 
Request JSON Object:
 
  • related_id (string) – (required) the related object id
  • params (string) – (optional) it depends from relation type
  • priority (string) – (optional) is the position of the relation. Relation with lower priority are shown before.
Response Headers:
 
Status Codes:

At least params or priority must be defined. If one of these is not passed it will be set to null.

Example request:

PUT /objects/1/relations/attach/2 HTTP/1.1
Host: example.com
Accept: application/json, text/javascript
Content-Type: application/json

{
    "data": {
        "priority": 3,
        "params": {
            "label": "new label"
        }
    }
}

Example response:

HTTP/1.1 200 Success
Host: example.com
Accept: application/json, text/javascript
Content-Type: application/json

The response body will be the same as GET /objects/(object_id)/relations/(string:relation_name)/(int:related_id)

Add or edit children

POST /objects/(object_id)/children

Add or edit children to area/section object type identified by object_id

Request data must be an array of child data or only a child data if you need to save only one child.

Request Headers:
 
Request JSON Array of Objects:
 
  • child_id (string) – (required) the child object id
  • priority (string) – (optional) is the position of the child on the tree. Relation with lower priority are shown before.
Response Headers:
 
Status Codes:

Example request to add/edit many children:

POST /objects/3/children HTTP/1.1
Host: example.com
Accept: application/json, text/javascript
Content-Type: application/json

{
    "data": [
        {
            "child_id": 15,
            "priority": 3
        },
        {
            "child_id": 28
        }
    ]
}

Example request to add/edit one child:

POST /objects/3/children HTTP/1.1
Host: example.com
Accept: application/json, text/javascript
Content-Type: application/json

{
    "data": {
        "child_id": 34,
        "priority": 3
    }
}

The response body will be the same as GET /objects/(object_id)/children

Update child position

PUT /objects/(object_id)/children/(int: child_id)

Change the child position inside the children of object_id.

Request Headers:
 
Request JSON Object:
 
  • priority (string) – (required) the position of child object id
Response Headers:
 
Status Codes:
  • 200 OK – Success. Children position (priority) updated.
  • 400 Bad Request – Required parameters are missing or the request is malformed
  • 401 Unauthorized – Request is not authorized

Example request:

POST /objects/1/children/2 HTTP/1.1
Host: example.com
Accept: application/json, text/javascript
Content-Type: application/json

{
    "data": {
        "priority": 5
    }
}

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "api": "objects",
  "data": {
    "priority": 5
  },
  "method": "get",
  "params": [],
  "url": "https://example.com/api/objects/1/children/2"
}

Delete an object

DELETE /objects/(object_id)

Delete the object object_id

Request Headers:
 
Response Headers:
 
Status Codes:

Example request:

DELETE /objects/15 HTTP/1.1
Host: example.com
Accept: application/json, text/javascript

Example response:

HTTP/1.1 204 No Content

Delete a relation between objects

Delete the relation relation_name between object_id and related_id

Request Headers:
 
Response Headers:
 
Status Codes:
  • 204 No Content – The relation relation_name between object_id and related_id was deleted.
  • 400 Bad Request – Required parameters are missing or the request is malformed
  • 401 Unauthorized – Request is not authorized
  • 404 Not Found – The relation relation_name between object_id and related_id not exists or it has already been removed

Example request:

DELETE /objects/10/relations/seealso/36 HTTP/1.1
Host: example.com
Accept: application/json, text/javascript

Example response:

HTTP/1.1 204 No Content

Remove a child from a parent

DELETE /objects/(object_id)/children/(int: child_id)

Remove child_id from object_id children

Request Headers:
 
Response Headers:
 
Status Codes:

Example request:

DELETE /objects/1/children/3 HTTP/1.1
Host: example.com
Accept: application/json, text/javascript

Example response:

HTTP/1.1 204 No Content