When to call the API directly#
plone-client offers three levels for the same request, and the choice between them is mostly a question of what you want to stop thinking about.
A manager method names a task and knows its URL and its parameters.
A generic method such as client.get takes a path and leaves the rest to you.
client.request returns the raw response.
from plone_client import PloneClient
client = PloneClient("http://localhost:8080/Plone", username="admin", password="admin")
print(client.workflow.get("/news/release-6-2")["state"]["id"])
print(client.get("/news/release-6-2/@workflow")["state"]["id"])
print(client.request("GET", "/news/release-6-2/@workflow").status_code)
published
published
200
Start with the manager#
The manager is the right default because it hides the details that are easy to get wrong.
client.search.search("/news", depth=1) knows that a search on a folder restricts the results to it, which works the same behind a virtual host.
client.content.update adds the header that asks for the changed item.
client.groups.add_members knows the shape of a body that says {"users": {"jdoe": true}}.
Refs work everywhere, so a path, a URL, and a uid: are the same to it.
Go generic when no manager fits#
A service that an add-on registers has no manager, and neither does a query parameter a manager has not learned yet.
That is what client.get, post, patch, put, and delete are for.
Nothing is lost by using them: authentication, retries, errors, read_only, and dry_run all sit below the managers.
That last point matters most.
Everything that goes through the client goes through the same checks, so a generic client.post is refused by a read-only client like any other change.
There is one judgment built in: every POST counts as a change, except @querystring-search, @login, and @login-renew.
An add-on service that uses POST to read is refused, and a dry run skips it.
Go raw when the answer is not JSON#
client.request is for what the decoded body does not tell you: a status code, a header, a body that is an image.
client.request("GET", path, raise_for_status=False) also lets you look at an error answer without an exception, which is how exists() works.
Leave the client when it is in the way#
A plain HTTP client makes sense when the program has no reason to depend on plone-client, as with a frontend written in another language, or a one-off curl command to see what a site answers.
In Python, on a site you manage, it rarely pays off.
You give up the retries and the safety switches, and you write again what ++api++ and batching already solve.
Replace a hand-written client shows what that kind of code looks like, and how little of it remains.
Read the plone.restapi documentation#
The documentation of plone.restapi describes each service as an HTTP request, and the translation is mechanical.
In the documentation |
In plone-client |
|---|---|
|
|
|
Nothing: the client sends it. |
|
Nothing: the client’s credentials. |
|
|
A JSON body |
The |
|
Usable as paths, as they are. |
|