How to use Plone.restapi

While using Postman, i added the following and it didn't get any response...

You need to use a full url, ie http://localhost:8080/Plone/front-page

It returns this html content for some reason, not the meta data in json format

You need to set the accept header to application/json, ie Accept: application/json
Also see https://plonerestapi.readthedocs.io/en/latest/content.html#reading-a-resource-with-get

Hey! I was starting up with the Plone REST API and I wanted to know where I can find the instructions for local development setup. I found the documentation site but that had nothing much about installation and setup for usage with postman. Can someone help me out here?

Seriously, the documentation

http://plonerestapi.readthedocs.io

is full of example including HTTP request headers and everything you need. What should be missing here?

-aj

1 Like

Sorry if its already documented, I'm new here!
What I was looking for is how to run the API locally?

What

What do you mean with running locally?

when plone.restapi is installed then the REST API is available from the configured HTTP address + port used by Plone which is by default localhost:8080.

-aj

Oh what I meant was in the github repo, there's the Live Demo given at http://plonedemo.kitconcept.com
I've been using this right now.

But there doesn't seem to be anything given on installing and running locally.

Add plone.restapi to your buildout and your LOCAL Plone configuration and use it locally. What is the problem here?

-aj

Okay thanks! Will check it out!

It's specified in the plone.restapi github repo that the latest api is live on http://plonedemo.kitconcept.com
I've been reading the docs and also testing out the api using postman. Seems like there are some issues with some of the requests.

What's given in the documentation:

Result in Postman:
image
image

Expected results: (when link: /frontpage)

Is this because the live demo uses different API endpoints or cause documentation hasn't been updated with the API?

plone.restapi exposes few endpoints: those starting with @ like '@navigation', '@search', ... All other "endpoints" are the contents of the site. If you have a page with the URL "http://plonedemo.kitconcept.com/en/front-page", you can make an API query there to get the information, but if that page does not exist in Plone, you will get a 404 error. And that's what happens in your case

plone.restapi is, as explained in the README, "a hypermedia API just provides an entry point to the API that contains hyperlinks the clients can follow", that means that you make a query to http://plonedemo.kitconcept.com/en and in the result you get all the contents that are on that page. Each content provides in the @id attribute its own URL which you should query to get more information.

In this case the API returns these contents:

     ...
     "items": [
         {
             "@id": "http://plonedemo.kitconcept.com/en/media",
             "@type": "LIF",
             "description": "",
             "review_state": "published",
             "title": "Media"
         },
         {
             "@id": "http://plonedemo.kitconcept.com/en/frontpage",
             "@type": "Document",
             "description": "The ultimate Open Source Enterprise CMS",
             "review_state": "published",
             "title": "Welcome to Plone 5"
         },
         {
             "@id": "http://plonedemo.kitconcept.com/en/demo",
             "@type": "Folder",
             "description": "Vestibulum dignissim erat id eros mollis vitae tempus leo ultricies. Cras dapibus suscipit consectetur. Integer tincidunt feugiat tristique. Sed et arcu risus. Nam venenatis, tortor ac tincidunt amet.",
             "review_state": "published",
             "title": "Demo"
         }
     ],
     ...

And you can query http://plonedemo.kitconcept.com/en/frontpage or http://plonedemo.kitconcept.com/en/demo to get more information.

I have been using http://plonedemo.kitconcept for api, locally i tried quering http://localhost:8080/Plone/@@search in postman and got this error on viewing it in json :
Unexpected '<'
Also It returns the HTML of the page as default for some reason...
I have set the Headers according to the documentation i.e. application/json . The Preview shows this page :

Also on running http://localhost:8080/Plone/@search results in Not Found.

Thats the @@search browserview. You want the @search REST endpoint (note the @@ vs @).
Also see https://plonerestapi.readthedocs.io/en/latest/searching.html#search

on using the endpoint @search i get the json : { "error_type": "NotFound" } :confused:

If you are running this locally, make sure you use the url http://localhost:8080/Plone/@search. Note the capital P in the Plone bit.
And please make sure you installed the addon using the control panel, or nothing will work :slight_smile:

1 Like

@jaroel Thanks for the reply! i added the addon and its working :smile:

I think we have to put some love into the plone.restapi docs to make it more approachable. We have some inconsistencies (e.g. localhost:55001/plone vs localhost:8080/Plone) in our docs and no straightforward step by step guide for newbies.

I think the docs are fine for Plone devs with some background knowledge of how REST APIs work. For JavaScript developers and newbies without in-depth REST knowledge there is certainly room for improvement.

I'd be more than happy to help if someone wants to work on improving the situation.

1 Like

Yeah, I can work on removing inconsistencies


There's one open issue too.