Elements

Summary of element endpoints

• GET /admin/api/elements - list all available elements for the current site.
• POST /admin/api/elements - create a new element for the current site.
• GET /admin/api/elements/1 - get data for a single element.
• PUT /admin/api/elements/1 - update attributes of a single element.
• PUT /admin/api/elements/1/move - relocate a element.
• DELETE /admin/api/elements/1 - remove a element.

List all available elements for the current site

GET /admin/api/elements

By default, this requests returns a list of all elements for the current site ordered by definition_id and position columns.

This endpoint also allows anonymous access that return only a elements under public pages.

Example response (authenticated request):

Status: 200 OK

[
  {
    "id": 2,
    "created_at": "2015-01-27T11:33:29.000Z",
    "updated_at": "2015-01-27T17:49:45.000Z",
    "position": 1,
    "path": "bill-gates",
    "title": "Bill Gates",
    "path_with_page": "people/bill-gates",
    "url": "http://helloworld.voog.co/admin/api/elements/2",
    "move_url": "http://helloworld.voog.co/admin/api/elements/2/move",
    "public_url": "http://helloworld.voog.co/people/bill-gates",
    "element_definition": {
      "id": 1,
      "title": "Person",
      "created_at": "2015-01-27T11:22:47.000Z",
      "updated_at": "2015-01-27T11:22:47.000Z",
      "url": "http://helloworld.voog.co/admin/api/element_definitions/1"
    },
    "page": {
      "id": 2,
      "title": "People",
      "path": "people",
      "language_id": 1,
      "created_at": "2015-01-27T11:26:19.000Z",
      "updated_at": "2015-01-27T11:26:42.000Z",
      "content_type": "elements",
      "published_at": "2015-01-27T11:26:19.000Z",
      "url": "http://helloworld.voog.co/admin/api/pages/2",
      "public_url": "http://helloworld.voog.co/people",
    }
  }, {
    "id": 1,
    "created_at": "2015-01-27T11:29:51.000Z",
    "updated_at": "2015-01-27T11:29:51.000Z",
    "position": 2,
    "path": "marilyn-monroe",
    "title": "Marilyn Monroe",
    "path_with_page": "people/marilyn-monroe",
    "url": "http://helloworld.voog.co/admin/api/elements/1",
    "move_url": "http://helloworld.voog.co/admin/api/elements/1/move",
    "public_url": "http://helloworld.voog.co/people/marilyn-monroe",
    "element_definition": {
      "id": 1,
      "title": "Person",
      "created_at": "2015-01-27T11:22:47.000Z",
      "updated_at": "2015-01-27T11:22:47.000Z",
      "url": "http://helloworld.voog.co/admin/api/element_definitions/1"
    },
    "page": {
      "id": 2,
      "title": "People",
      "path": "people",
      "language_id": 1,
      "created_at": "2015-01-27T11:26:19.000Z",
      "updated_at": "2015-01-27T11:26:42.000Z",
      "content_type": "elements",
      "published_at": "2015-01-27T11:26:19.000Z",
      "url": "http://helloworld.voog.co/admin/api/pages/2",
      "public_url": "http://helloworld.voog.co/people"
    }
  }
]

Example response (anonymous request):

Status: 200 OK

[
  {
    "id": 2,
    "created_at": "2015-01-27T11:33:29.000Z",
    "updated_at": "2015-01-27T17:49:45.000Z",
    "position": 1,
    "path": "bill-gates",
    "title": "Bill Gates",
    "path_with_page": "people/bill-gates",
    "url": "http://helloworld.voog.co/admin/api/elements/2",
    "public_url": "http://helloworld.voog.co/people/bill-gates",
    "element_definition": {
      "id": 1,
      "title": "Person"
    },
    "page": {
      "id": 2,
      "title": "People",
      "path": "people",
      "public_url": "http://helloworld.voog.co/people",
    }
  }, {
    "id": 1,
    "created_at": "2015-01-27T11:29:51.000Z",
    "updated_at": "2015-01-27T11:29:51.000Z",
    "position": 2,
    "path": "marilyn-monroe",
    "title": "Marilyn Monroe",
    "path_with_page": "people/marilyn-monroe",
    "url": "http://helloworld.voog.co/admin/api/elements/1",
    "move_url": "http://helloworld.voog.co/admin/api/elements/1/move",
    "public_url": "http://helloworld.voog.co/people/marilyn-monroe",
    "element_definition": {
      "id": 1,
      "title": "Person"
    },
    "page": {
      "id": 2,
      "title": "People",
      "path": "people",
      "public_url": "http://helloworld.voog.co/people",
    }
  }
]

Parameters

• per_page - elements per response (default: 50; maximum: 250).
• page - requested page (default: 1).
• page_id - parent page id (e.g. ?page_id=1). Returns only elements for requested parent page.
• language_id - language id (e.g. ?language_id=1). Returns only elements that are related to requested language.
• language_code - language code (e.g. ?language_code=en). Returns only elements that are related to requested language.
• element_definition_id - element definition id (e.g. ?element_definition_id=1). Returns only elements with requested definition id.
• element_definition_title - element definition title (e.g. ?element_definition_title=Person). Returns only elements with requested definition title.
• page_path - path (e.g. ?page_path=products/books). Returns only elements under requested page.
• page_path_prefix - path prefix (e.g. ?page_path_prefix=products/). Returns only those elements whose parent path begins with the given prefix.
• include_values - if value is true (e.g. ?include_values=true) then values are included to response.

Filter attributes

Read more about filters.

• Object element attributes: id, element_definition_id, page_id, title, path, position, created_at, updated_at. Elements API also supports filtering and sorting over element properties (element.values.PROPERTYNAME): e. g. ?q.element.values.birthday.$lt=1580-01-01,s=element.values.gender.$asc.
• Object element_definition attributes: id, title, created_at, updated_at.
• Object page attributes: id, language_id, node_id, layout_id, title, path, content_type, keywords, description, hidden, publishing, privacy, created_at, updated_at, published_at.

Create a new element for the current site

POST /admin/api/elements

This request adds a new element to the end of elements list on given page.

Example data:

{
  "element_definition_id": 1,
  "page_id": 2,
  "title": "John Smith",
  "values": {
    "description": "John Smith (c. January 1580 – 21 June 1631) Admiral of New England was an English soldier",
    "gender": "Male",
    "public": true,
    "birthday": "1580-01-01"
  }
}

Example response:

Status: 201 Created

{
  "id": 3,
  "created_at": "2015-01-27T11:29:51.000Z",
  "updated_at": "2015-01-27T11:29:51.000Z",
  "position": 4,
  "path": "john-smith",
  "title": "John Smith",
  "path_with_page": "people/john-smith",
  "url": "http://helloworld.voog.co/admin/api/elements/3",
  "move_url": "http://helloworld.voog.co/admin/api/elements/3/move",
  "contents_url": "http://helloworld.voog.co/admin/api/elements/3/contents",
  "public_url": "http://helloworld.voog.co/people/john-smith",
  "element_definition": {
    "id": 1,
    "title": "Person",
    "created_at": "2015-01-27T11:22:47.000Z",
    "updated_at": "2015-01-27T11:22:47.000Z",
    "url": "http://helloworld.voog.co/admin/api/element_definitions/1"
  },
  "page": {
    "id": 2,
    "title": "People",
    "path": "people",
    "language_id": 1,
    "created_at": "2015-01-27T11:26:19.000Z",
    "updated_at": "2015-01-27T11:26:42.000Z",
    "content_type": "elements",
    "published_at": "2015-01-27T11:26:19.000Z",
    "url": "http://helloworld.voog.co/admin/api/pages/2",
    "public_url": "http://helloworld.voog.co/people"
  },
  "values": {
    "description": "John Smith (c. January 1580 – 21 June 1631) Admiral of New England was an English soldier",
    "photo": "",
    "public": true,
    "gender": "Male",
    "birthday": "1580-01-01"
  }
}

Parameters

Required parameters:

• element_definition_id - related existing element definition id.
• element_definition_title - related existing element definition title. When both element_definition_id and element_definition_title is included to request then element_definition_id value is used.
• page_id - related existing page id to element definition id.
• title - name of the element.

Optional parameters:

• path - unique url part under given page (e.g. john). By default the path is generated from value of the element title. Path collision is solved automatically.
• values - hash of values where allowed keys is defined in related element definition, all other keys are ignored (e.g. {"gender": "Male", "birthday": "1580-01-01"}).

Get data for a single element

GET /admin/api/elements/1

Example request:

GET http://helloworld.voog.co/admin/api/elements/1

Get detailed data for single element.

This endpoint also allows anonymous access.

Example response (authenticated request):

Status: 200 OK

{
  "id": 1,
  "created_at": "2015-01-27T11:29:51.000Z",
  "updated_at": "2015-01-27T11:29:51.000Z",
  "position": 2,
  "path": "marilyn-monroe",
  "title": "Marilyn Monroe",
  "path_with_page": "people/marilyn-monroe",
  "url": "http://helloworld.voog.co/admin/api/elements/1",
  "move_url": "http://helloworld.voog.co/admin/api/elements/1/move",
  "contents_url": "http://helloworld.voog.co/admin/api/elements/1/contents",
  "public_url": "http://helloworld.voog.co/people/marilyn-monroe",
  "element_definition": {
    "id": 1,
    "title": "Person",
    "created_at": "2015-01-27T11:22:47.000Z",
    "updated_at": "2015-01-27T11:22:47.000Z",
    "url": "http://helloworld.voog.co/admin/api/element_definitions/1"
  },
  "page": {
    "id": 2,
    "title": "People",
    "path": "people",
    "language_id": 1,
    "created_at": "2015-01-27T11:26:19.000Z",
    "updated_at": "2015-01-27T11:26:42.000Z",
    "content_type": "elements",
    "published_at": "2015-01-27T11:26:19.000Z",
    "url": "http://helloworld.voog.co/admin/api/pages/2",
    "public_url": "http://helloworld.voog.co/people"
  },
  "values": {
    "description": "Marilyn Monroe was an American actress, model, and singer.",
    "photo": "",
    "birthday": "1926-06-01",
    "gender": "Female",
    "public": true
  }
}

Example response (anonymous request):

Status: 200 OK

{
  "id": 1,
  "created_at": "2015-01-27T11:29:51.000Z",
  "updated_at": "2015-01-27T11:29:51.000Z",
  "position": 2,
  "path": "marilyn-monroe",
  "title": "Marilyn Monroe",
  "path_with_page": "people/marilyn-monroe",
  "url": "http://helloworld.voog.co/admin/api/elements/1",
  "public_url": "http://helloworld.voog.co/people/marilyn-monroe",
  "element_definition": {
    "id": 1,
    "title": "Person"
  },
  "page": {
    "id": 2,
    "title": "People",
    "path": "people",
    "public_url": "http://helloworld.voog.co/people",
  },
  "values": {
    "description": "Marilyn Monroe was an American actress, model, and singer.",
    "photo": "",
    "birthday": "1926-06-01",
    "gender": "Female",
    "public": true
  }
}

Update attributes of a single element

PUT /admin/api/elements/1

This request updates the element with provided attributes. Only provided attributes are updated.

Example request:

PUT http://helloworld.voog.co/admin/api/elements/3

Example data:

Status: 200 OK

{
  "title": "John Smith I",
  "path": "john",
  "values": {
    "description": "John Smith (c. January 1580 – 21 June 1631) Admiral of New England."
  }
}

Example response:

Status: 200 OK

{
  "id": 3,
  "created_at": "2015-01-27T11:29:51.000Z",
  "updated_at": "2015-01-27T11:44:01.000Z",
  "position": 4,
  "path": "john",
  "title": "John Smith I",
  "path_with_page": "people/john-smith",
  "url": "http://helloworld.voog.co/admin/api/elements/3",
  "move_url": "http://helloworld.voog.co/admin/api/elements/3/move",
  "contents_url": "http://helloworld.voog.co/admin/api/elements/3/contents",
  "public_url": "http://helloworld.voog.co/people/john",
  "element_definition": {
    "id": 1,
    "title": "Person",
    "created_at": "2015-01-27T11:22:47.000Z",
    "updated_at": "2015-01-27T11:22:47.000Z",
    "url": "http://helloworld.voog.co/admin/api/element_definitions/1"
  },
  "page": {
    "id": 2,
    "title": "People",
    "path": "people",
    "language_id": 1,
    "created_at": "2015-01-27T11:26:19.000Z",
    "updated_at": "2015-01-27T11:26:42.000Z",
    "content_type": "elements",
    "published_at": "2015-01-27T11:26:19.000Z",
    "url": "http://helloworld.voog.co/admin/api/pages/2",
    "public_url": "http://helloworld.voog.co/people",
  },
  "values": {
    "description": "John Smith (c. January 1580 – 21 June 1631) Admiral of New England.",
    "photo": "",
    "public": true,
    "gender": "Male",
    "birthday": "1580-01-01"
  }
}

Relocate a element

PUT /admin/api/nodes/1/move

Reorders or moves element around elements list of current page and/or some other page.

Example request:

PUT http://helloworld.voog.co/admin/api/elements/3/move?before=1

Example response:

Status: 200 OK

{
  "id": 3,
  "created_at": "2015-01-27T11:29:51.000Z",
  "updated_at": "2015-01-27T11:53:02.000Z",
  "position": 1,
  "path": "john",
  "title": "John Smith I",
  "path_with_page": "people/john-smith",
  "url": "http://helloworld.voog.co/admin/api/elements/3",
  "move_url": "http://helloworld.voog.co/admin/api/elements/3/move",
  "contents_url": "http://helloworld.voog.co/admin/api/elements/3/contents",
  "public_url": "http://helloworld.voog.co/people/john",
  "element_definition": {
    "id": 1,
    "title": "Person",
    "created_at": "2015-01-27T11:22:47.000Z",
    "updated_at": "2015-01-27T11:22:47.000Z",
    "url": "http://helloworld.voog.co/admin/api/element_definitions/1"
  },
  "page": {
    "id": 2,
    "title": "People",
    "path": "people",
    "language_id": 1,
    "created_at": "2015-01-27T11:26:19.000Z",
    "updated_at": "2015-01-27T11:26:42.000Z",
    "content_type": "elements",
    "published_at": "2015-01-27T11:26:19.000Z",
    "url": "http://helloworld.voog.co/admin/api/pages/2",
    "public_url": "http://helloworld.voog.co/people"
  }
}

Parameters

• page_id - new parent page id (e.g. ?page_id=1).
• before - existing element id on current page (or on new parent page if page_id is provided (e.g. ?page_id=1&before=1).
• after - existing element id on current page (or on new parent page if page_id is provided (e.g. ?page_id=1&before=1)).

Remove a element

DELETE /admin/api/elements/1

This request deletes the element from the database.

Example request:

DELETE http://helloworld.voog.co/admin/api/elements/1

Example response:

Status: 204 No Content