Content#

Every content item of a site, through ContentManager. Methods take a ref, so a path, a URL inside the site, or uid:<UID> all work. A content type decides which fields an item accepts; see Content model.

Each example uses the client from How to read these pages.

client.content#

ContentManager.

Content items, through the content endpoints of plone.restapi.

client.content.get#

Serialization of an item.

See get().

Calls GET /news/release-6-2 (plone.restapi documentation).

client.content.get("/news/release-6-2")
plone-client get /news/release-6-2 -f @id,@type,title,review_state
{
  "@id": "http://localhost:8080/Plone/news/release-6-2",
  "@type": "News Item",
  "title": "Release 6.2 is out",
  "review_state": "published"
}
GET /Plone/++api++/news/release-6-2 HTTP/1.1
Host: localhost:8080
Accept: application/json
Authorization: Basic YWRtaW46YWRtaW4=
curl -i -X GET http://localhost:8080/Plone/++api++/news/release-6-2 -H 'accept: application/json' -u admin:admin
{
  "@id": "http://localhost:8080/Plone/news/release-6-2",
  "@type": "News Item",
  "review_state": "published",
  "title": "Release 6.2 is out"
}

This shows only @id, @type, title, review_state.

Expand a component#

expand puts the answer of another service inside the item.

Calls GET /news/release-6-2 (plone.restapi documentation).

client.content.get("/news/release-6-2", expand="breadcrumbs")["@components"]
plone-client get /news/release-6-2 --expand breadcrumbs -f title
{
  "title": "Release 6.2 is out"
}
GET /Plone/++api++/news/release-6-2?expand=breadcrumbs HTTP/1.1
Host: localhost:8080
Accept: application/json
Authorization: Basic YWRtaW46YWRtaW4=
curl -i -X GET 'http://localhost:8080/Plone/++api++/news/release-6-2?expand=breadcrumbs' -H 'accept: application/json' -u admin:admin
{
  "breadcrumbs": {
    "@id": "http://localhost:8080/Plone/news/release-6-2/@breadcrumbs",
    "items": [
      {
        "@id": "http://localhost:8080/Plone/news",
        "title": "News"
      },
      {
        "@id": "http://localhost:8080/Plone/news/release-6-2",
        "title": "Release 6.2 is out"
      }
    ],
    "root": "http://localhost:8080/Plone"
  }
}

This shows only breadcrumbs.

client.content.find_by_uid#

Catalog entry of the item with a UID.

See find_by_uid().

Calls GET /about, GET /@search (plone.restapi documentation).

uid = client.content.get("/about")["UID"]
client.content.find_by_uid(uid)
GET /Plone/++api++/about HTTP/1.1
Host: localhost:8080
Accept: application/json
Authorization: Basic YWRtaW46YWRtaW4=
GET /Plone/++api++/@search?UID=3788c6ac13e749709aa4f2fb771821ce HTTP/1.1
Host: localhost:8080
Accept: application/json
Authorization: Basic YWRtaW46YWRtaW4=
curl -i -X GET http://localhost:8080/Plone/++api++/about -H 'accept: application/json' -u admin:admin
curl -i -X GET 'http://localhost:8080/Plone/++api++/@search?UID=3788c6ac13e749709aa4f2fb771821ce' -H 'accept: application/json' -u admin:admin
{
  "@id": "http://localhost:8080/Plone/about",
  "@type": "Document",
  "title": "About"
}

This shows only @id, @type, title.

client.content.resolve#

Site path for a reference.

See resolve().

Calls GET /about, GET /@search (plone.restapi documentation).

uid = client.content.get("/about")["UID"]
client.content.resolve(f"uid:{uid}")
GET /Plone/++api++/about HTTP/1.1
Host: localhost:8080
Accept: application/json
Authorization: Basic YWRtaW46YWRtaW4=
GET /Plone/++api++/@search?UID=3788c6ac13e749709aa4f2fb771821ce HTTP/1.1
Host: localhost:8080
Accept: application/json
Authorization: Basic YWRtaW46YWRtaW4=
curl -i -X GET http://localhost:8080/Plone/++api++/about -H 'accept: application/json' -u admin:admin
curl -i -X GET 'http://localhost:8080/Plone/++api++/@search?UID=3788c6ac13e749709aa4f2fb771821ce' -H 'accept: application/json' -u admin:admin
"/about"

client.content.exists#

Say whether there is an item at a path.

See exists().

Calls GET /news/no-such-item.

client.content.exists("/news/no-such-item")
GET /Plone/++api++/news/no-such-item HTTP/1.1
Host: localhost:8080
Accept: application/json
Authorization: Basic YWRtaW46YWRtaW4=
curl -i -X GET http://localhost:8080/Plone/++api++/news/no-such-item -H 'accept: application/json' -u admin:admin
false

client.content.children#

Items directly inside a folder, in the folder’s order.

See children().

Calls GET /news/@search (plone.restapi documentation).

list(client.content.children("/news", portal_type="News Item"))
plone-client ls /news -t "News Item" --limit 2 -f @id,title
[
  {
    "@id": "http://localhost:8080/Plone/news/release-6-2",
    "title": "Release 6.2 is out"
  },
  {
    "@id": "http://localhost:8080/Plone/news/release-party",
    "title": "Release party in Brasília"
  }
]
GET /Plone/++api++/news/@search?path.depth=1&sort_on=getObjPositionInParent&portal_type=News+Item&b_size=100 HTTP/1.1
Host: localhost:8080
Accept: application/json
Authorization: Basic YWRtaW46YWRtaW4=
curl -i -X GET 'http://localhost:8080/Plone/++api++/news/@search?path.depth=1&sort_on=getObjPositionInParent&portal_type=News+Item&b_size=100' -H 'accept: application/json' -u admin:admin
[
  {
    "@id": "http://localhost:8080/Plone/news/release-6-2",
    "review_state": "published",
    "title": "Release 6.2 is out"
  },
  {
    "@id": "http://localhost:8080/Plone/news/release-party",
    "review_state": "private",
    "title": "Release party in Brasília"
  },
  {
    "@id": "http://localhost:8080/Plone/news/release-notes-draft",
    "review_state": "private",
    "title": "Release notes draft"
  }
]

This shows only @id, title, review_state of each entry. This shows 3 of 5 entries.

client.content.create#

Create an item inside a folder.

See create().

Calls POST /news (plone.restapi documentation).

client.content.create(
    "/news",
    "News Item",
    title="Sprint in Bonn",
    description="A week of work.",
)
plone-client create /news "News Item" --title "Sprint in Bonn" -f @id,title,review_state
{
  "@id": "http://localhost:8080/Plone/news/sprint-in-bonn",
  "title": "Sprint in Bonn",
  "review_state": "private"
}
POST /Plone/++api++/news HTTP/1.1
Host: localhost:8080
Accept: application/json
Content-Type: application/json
Authorization: Basic YWRtaW46YWRtaW4=

{
  "@type": "News Item",
  "title": "Sprint in Bonn",
  "description": "A week of work."
}
curl -i -X POST http://localhost:8080/Plone/++api++/news -H 'accept: application/json' -H 'content-type: application/json' -u admin:admin --data-raw '{"@type":"News Item","title":"Sprint in Bonn","description":"A week of work."}'
{
  "@id": "http://localhost:8080/Plone/news/sprint-in-bonn",
  "@type": "News Item",
  "id": "sprint-in-bonn",
  "review_state": "private",
  "title": "Sprint in Bonn"
}

This shows only @id, @type, id, title, review_state.

client.content.update#

Change fields of an item (PATCH).

See update().

Calls PATCH /about/team (plone.restapi documentation).

client.content.update("/about/team", title="The team")
plone-client update /about/team --title "The team" -f title
{
  "title": "The team"
}
PATCH /Plone/++api++/about/team HTTP/1.1
Host: localhost:8080
Accept: application/json
Prefer: return=representation
Content-Type: application/json
Authorization: Basic YWRtaW46YWRtaW4=

{
  "title": "The team"
}
curl -i -X PATCH http://localhost:8080/Plone/++api++/about/team -H 'accept: application/json' -H 'prefer: return=representation' -H 'content-type: application/json' -u admin:admin --data-raw '{"title":"The team"}'
{
  "@id": "http://localhost:8080/Plone/about/team",
  "title": "The team"
}

This shows only @id, title.

client.content.delete#

Delete an item.

See delete().

Calls DELETE /news/to-remove (plone.restapi documentation).

client.content.delete("/news/to-remove")
plone-client delete /news/to-remove --yes
{
  "deleted": [
    "/news/to-remove"
  ],
  "dry_run": false
}
DELETE /Plone/++api++/news/to-remove HTTP/1.1
Host: localhost:8080
Accept: application/json
Authorization: Basic YWRtaW46YWRtaW4=
curl -i -X DELETE http://localhost:8080/Plone/++api++/news/to-remove -H 'accept: application/json' -u admin:admin

The site answers 204, and the method returns None.

client.content.copy#

Copy items into a folder.

See copy().

Calls POST /news/@copy (plone.restapi documentation).

client.content.copy("/about/team", "/news")
plone-client copy /about/team --to /news
[
  {
    "source": "http://localhost:8080/Plone/about/team",
    "target": "http://localhost:8080/Plone/news/team"
  }
]
POST /Plone/++api++/news/@copy HTTP/1.1
Host: localhost:8080
Accept: application/json
Content-Type: application/json
Authorization: Basic YWRtaW46YWRtaW4=

{
  "source": [
    "/about/team"
  ]
}
curl -i -X POST http://localhost:8080/Plone/++api++/news/@copy -H 'accept: application/json' -H 'content-type: application/json' -u admin:admin --data-raw '{"source":["/about/team"]}'
[
  {
    "source": "http://localhost:8080/Plone/about/team",
    "target": "http://localhost:8080/Plone/news/team"
  }
]

client.content.move#

Move items into a folder.

See move().

Calls POST /news/@move (plone.restapi documentation).

client.content.move("/about/team", "/news")
plone-client move /about/team --to /news
[
  {
    "source": "http://localhost:8080/Plone/about/team",
    "target": "http://localhost:8080/Plone/news/team"
  }
]
POST /Plone/++api++/news/@move HTTP/1.1
Host: localhost:8080
Accept: application/json
Content-Type: application/json
Authorization: Basic YWRtaW46YWRtaW4=

{
  "source": [
    "/about/team"
  ]
}
curl -i -X POST http://localhost:8080/Plone/++api++/news/@move -H 'accept: application/json' -H 'content-type: application/json' -u admin:admin --data-raw '{"source":["/about/team"]}'
[
  {
    "source": "http://localhost:8080/Plone/about/team",
    "target": "http://localhost:8080/Plone/news/team"
  }
]

client.content.order#

Move an item within its folder.

See order().

Calls PATCH /news (plone.restapi documentation).

client.content.order("/news", "sprint-report", "top")
plone-client order /news sprint-report top
[
  "http://localhost:8080/Plone/news/sprint-report",
  "http://localhost:8080/Plone/news/release-6-2",
  "http://localhost:8080/Plone/news/release-party",
  "http://localhost:8080/Plone/news/release-notes-draft",
  "http://localhost:8080/Plone/news/old-announcement",
  "http://localhost:8080/Plone/news/to-remove"
]
PATCH /Plone/++api++/news HTTP/1.1
Host: localhost:8080
Accept: application/json
Content-Type: application/json
Authorization: Basic YWRtaW46YWRtaW4=

{
  "ordering": {
    "obj_id": "sprint-report",
    "delta": "top"
  }
}
curl -i -X PATCH http://localhost:8080/Plone/++api++/news -H 'accept: application/json' -H 'content-type: application/json' -u admin:admin --data-raw '{"ordering":{"obj_id":"sprint-report","delta":"top"}}'

The site answers 204, and the method returns None.

client.content.sort#

Sort the items of a folder by an index, once.

See sort().

Calls PATCH /news (plone.restapi documentation).

client.content.sort("/news", "sortable_title", "ascending")
PATCH /Plone/++api++/news HTTP/1.1
Host: localhost:8080
Accept: application/json
Content-Type: application/json
Authorization: Basic YWRtaW46YWRtaW4=

{
  "sort": {
    "on": "sortable_title",
    "order": "ascending"
  }
}
curl -i -X PATCH http://localhost:8080/Plone/++api++/news -H 'accept: application/json' -H 'content-type: application/json' -u admin:admin --data-raw '{"sort":{"on":"sortable_title","order":"ascending"}}'

The site answers 204, and the method returns None.

client.content.lock#

Lock an item.

See lock().

Calls POST /about/@lock (plone.restapi documentation).

client.content.lock("/about", timeout=600)
POST /Plone/++api++/about/@lock HTTP/1.1
Host: localhost:8080
Accept: application/json
Content-Type: application/json
Authorization: Basic YWRtaW46YWRtaW4=

{
  "stealable": true,
  "timeout": 600
}
curl -i -X POST http://localhost:8080/Plone/++api++/about/@lock -H 'accept: application/json' -H 'content-type: application/json' -u admin:admin --data-raw '{"stealable":true,"timeout":600}'
{
  "creator": "admin",
  "locked": true,
  "stealable": true,
  "timeout": 600
}

This shows only locked, stealable, timeout, creator.

client.content.lock_info#

Lock information of an item.

See lock_info().

Calls GET /about/@lock (plone.restapi documentation).

client.content.lock_info("/about")
GET /Plone/++api++/about/@lock HTTP/1.1
Host: localhost:8080
Accept: application/json
Authorization: Basic YWRtaW46YWRtaW4=
curl -i -X GET http://localhost:8080/Plone/++api++/about/@lock -H 'accept: application/json' -u admin:admin
{
  "locked": false,
  "stealable": true
}

This shows only locked, stealable.

client.content.refresh_lock#

Extend the lock of an item.

See refresh_lock().

Calls PATCH /about/@lock (plone.restapi documentation).

client.content.refresh_lock("/about")
PATCH /Plone/++api++/about/@lock HTTP/1.1
Host: localhost:8080
Accept: application/json
Authorization: Basic YWRtaW46YWRtaW4=
curl -i -X PATCH http://localhost:8080/Plone/++api++/about/@lock -H 'accept: application/json' -u admin:admin
{
  "locked": true,
  "stealable": true,
  "timeout": 600
}

This shows only locked, stealable, timeout.

client.content.unlock#

Remove the lock of an item.

See unlock().

Calls DELETE /about/@lock (plone.restapi documentation).

client.content.unlock("/about")
DELETE /Plone/++api++/about/@lock HTTP/1.1
Host: localhost:8080
Accept: application/json
Authorization: Basic YWRtaW46YWRtaW4=
curl -i -X DELETE http://localhost:8080/Plone/++api++/about/@lock -H 'accept: application/json' -u admin:admin
{
  "locked": false,
  "stealable": true
}

This shows only locked, stealable.