Using plone.restapi without Volto#

In this chapter, we will use REST API, to iteract with the backend without using Volto.

It provides a hypermedia API to access Plone content using REST (Representational State Transfer).

We will use plone.restapi to develop a small standalone 'single page app' targeted at mobile devices. We will present our users with a simple list of conference talks.

We add lightning talks as a new type of talk. Users will be able to submit lightning talks e.g. using their mobile phone.

We have the following tasks:

  • create a talk list view

  • create a login screen and use JWT for authentication/authorization of requests

  • let authenticated users submit lightning talks

Installing plone.restapi#

We install plone.restapi like any other add-on package by adding it to buildout.cfg and then activating it in the Add-ons panel. This will automatically add and configure a new PAS plugin named jwt_auth used for JSON web token authentication.

Explore the API#

Make sure you add some talks to the talks folder and then start exploring the API. We recommend using Postman or a similar tool, but you can also use requests in a Python virtual env.

plone.restapi uses 'content negotiation' to determine whether a client wants a REST API response - if you set the Accept HTTP header to application/json, Plone will provide responses in JSON format. Some requests you could try:

GET /Plone/talks HTTP/1.1
Accept: application/json

POST /@login HTTP/1.1
Accept: application/json
Content-Type: application/json

{
    "login": "admin",
    "password": "admin"
}

Exercise#

REST APIs use HTTP verbs for manipulating content. PATCH is used to update an existing resource.

Add a new talk in Plone and then update it's title to match 'Foo 42' using the REST API (from Postman or requests).

Solution

We need to login to change content. Using JWT, we do so by POSTing credentials to the @login resource to obtain a JSON web token that we can subsequently use to authorize requests.

POST /@login HTTP/1.1
Accept: application/json
Content-Type: application/json

{
    "login": "admin",
    "password": "admin"
}

The response will look like this:

{
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJmdWxsbmFtZSI6bnVsbCwic3ViIjoiYWRtaW4iLCJleHAiOjE0NzQ5MTU4Mzh9.s27se99V7leTVTo26N_pbYskebR28W5NS87Fb7zowNk"
}

Using the requests library from Python, you would do:

>>> import requests
>>> response = requests.post('http://localhost:8080/Plone/@login',
...                   headers={'Accept': 'application/json', 'Content-Type': 'application/json'},
...                   data='{"login": "admin", "password": "admin"}')
>>> response.status_code
200
>>> response.json()
{'token': 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJmdWxsbmFtZSI6bnVsbCwic3ViIjoiYWRtaW4iLCJleHAiOjE0NzQ5MTYyNzR9.zx8XJb6SCWB2taxyibLZ2461ibDloqU3QbWDkDzT8PY'}
>>>

Now we can change the talk title:

PATCH /Plone/talks/example-talk HTTP/1.1
Accept: application/json
Content-Type: application/json
Authentication: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJmdWxsbmFtZSI6bnVsbCwic3ViIjoiYWRtaW4iLCJleHAiOjE0NzQ5MTYyNzR9.zx8XJb6SCWB2taxyibLZ2461ibDloqU3QbWDkDzT8PY

{
    "@id": "http://localhost:8080/Plone/talks/example-talk",
    "title": "Foo 42"
}

Using requests again:

>>> requests.patch('http://localhost:8080/Plone/talks/example-talk',
...                headers={'Accept': 'application/json', 'Content-Type': 'application/json', 'Authorization': 'Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJmdWxsbmFtZSI6bnVsbCwic3ViIjoiYWRtaW4iLCJleHAiOjE0NzQ5MTYyNzR9.zx8XJb6SCWB2taxyibLZ2461ibDloqU3QbWDkDzT8PY'},
...                data='{"@id":"http://localhost:8080/Plone/talks/example-talk", "title":"Foo 42"}')
<Response [204]>

Implementing the talklist#

We will use Vue.js to develop our app. This is a relatively lightweight JavaScript framework for developing hybrid web apps. A big advantage of Vue.js over other frameworks for our purpose is that it doesn't require NodeJS..

Our focus is Plone and interacting with plone.restapi, and Vue.js perfectly suits our needs because it simply lets us use Plone as our development webserver.

To get started, we create a new subdirectory of browser named talklist.

Assuming the current working directory is the buildout directory:

mkdir src/ploneconf.site/src/ploneconf/site/browser/talklist

Then we add a new resource directory to browser/configure.zcml:

<browser:resourceDirectory
    name="talklist"
    directory="talklist"
    />

In the browser/talklist directory, we add an HTML page called index.html:

<!DOCTYPE html>
<html
  xmlns:v-on="https://vuejs.org/"
  xmlns:="https://vuejs.org/">
  <head>
    <meta charset="utf-8" />
    <base href="/Plone/++resource++talklist/" />
    <title>List Of Talks</title>
    <meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1" />
    <meta name="apple-mobile-web-app-capable" content="yes" />
    <meta name="viewport" content="user-scalable=no, initial-scale=1.0, maximum-scale=1.0, minimal-ui" />
    <meta name="apple-mobile-web-app-status-bar-style" content="yes" />
    <link rel="shortcut icon" href="/favicon.png" type="image/x-icon" />
    <!-- Load required Bootstrap and BootstrapVue CSS -->
    <link type="text/css" rel="stylesheet" href="//unpkg.com/bootstrap/dist/css/bootstrap.min.css" />
    <link type="text/css" rel="stylesheet" href="//unpkg.com/bootstrap-vue@latest/dist/bootstrap-vue.min.css" />
  </head>

  <body>

    <h1>List of talks</h1>

    <div id="talklist">

      <div role="tablist">
        <b-card no-body class="mb-1" v-for="(item, index) in items">
          <b-card-header header-tag="header" class="p-1" role="tab">
            <b-button block href="#" v-b-toggle="'accordion-' + index" variant="info">{{ item.type }}: {{ item.title }} by {{ item.speaker }}</b-button>
          </b-card-header>
          <b-collapse :id="'accordion-' + index" accordion="talklist-accordion" role="tabpanel">
            <b-card-body>
              <b-card-text>{{item.details}}</b-card-text>
            </b-card-body>
          </b-collapse>
        </b-card>
      </div>

    </div>
    <!-- Load polyfills to support older browsers -->
    <script src="//polyfill.io/v3/polyfill.min.js?features=es2015%2CMutationObserver" crossorigin="anonymous"></script>

    <!-- Load Vue followed by BootstrapVue -->
    <script src="//unpkg.com/vue@latest/dist/vue.min.js"></script>
    <script src="//unpkg.com/bootstrap-vue@latest/dist/bootstrap-vue.min.js"></script>
    <script src="https://cdn.jsdelivr.net/npm/vue-resource@1.5.1"></script>
    <script src="talklist.js"></script>
  </body>
</html>

Now you can point your browser to http://localhost:8080/Plone/++resource++talklist/index.html to see the result.

The page will display a list of published talks.

We also need some JavaScript that we put into a file named talklist.js in the same folder:

"use strict";

var app = new Vue({
  el: "#talklist",
  data: {
    items: [],
    userid: "",
    passwd: "",
    subject: "",
    summary: "",
  },

  methods: {
    load_talks: function () {
      this.$http
        .get("/Plone/talks", { headers: { Accept: "application/json" } })
        .then(
          function (response) {
            this.items = [];
            // get the paths of the talks
            var paths = [];
            for (var i = 0; i < response.data.items_total; i++) {
              paths.push(response.data.items[i]["@id"]);
            }
            // next get details for each talk
            for (var i = 0; i < paths.length; i++) {
              this.$http
                .get(paths[i], { headers: { Accept: "application/json" } })
                .then(
                  function (resp) {
                    var talkdata = resp.data;
                    var path = talkdata["@id"];
                    var talk = {
                      pos: paths.indexOf(path),
                      path: path,
                      title: talkdata.title,
                      type: talkdata.type_of_talk,
                      speaker:
                        talkdata.speaker != null
                          ? talkdata.speaker
                          : talkdata.creators[0],
                      start: talkdata.start,
                      subjects: talkdata.subjects,
                      details:
                        talkdata.details != null
                          ? talkdata.details.data
                          : talkdata.description,
                    };
                    this.items.push(talk);
                  },
                  function (error) {}
                );
            }
          },
          function (error) {
            this.items = [];
          }
        );
    },
  },

  mounted: function () {
    // initialize
    this.load_talks();
  },
});

Submit lightning talks#

We add a new type of talk: lightning talk. A lightning talk is a short presentation of up to 5 minutes duration that can cover just about any topic.

The information we need to provide for lightning talks is far less than for the more formal types of talk.

Often the information provided for lightning talks is restricted to the talk subject or title and the speaker name, but we allow for a short summary.

Before they can submit a lightning talk, potential speakers will need to login and we will use their previously registered login name as the speaker's name to display in the talk list.

Before we can start to submit lightning talks using REST calls from our single page app, we have to adapt the talk schema:

 1 <?xml version="1.0" encoding="UTF-8"?>
 2 <model xmlns="http://namespaces.plone.org/supermodel/schema"
 3    xmlns:form="http://namespaces.plone.org/supermodel/form"
 4    xmlns:i18n="http://xml.zope.org/namespaces/i18n"
 5    xmlns:lingua="http://namespaces.plone.org/supermodel/lingua"
 6    xmlns:marshal="http://namespaces.plone.org/supermodel/marshal"
 7    xmlns:security="http://namespaces.plone.org/supermodel/security"
 8    xmlns:users="http://namespaces.plone.org/supermodel/users">
 9   <schema>
10     <field name="type_of_talk" type="zope.schema.Choice"
11       form:widget="z3c.form.browser.radio.RadioFieldWidget">
12       <description />
13       <title>Type of talk</title>
14       <values>
15         <element>Talk</element>
16         <element>Training</element>
17         <element>Keynote</element>
18         <element>Lightning Talk</element>
19       </values>
20     </field>
21     <field name="details" type="plone.app.textfield.RichText">
22       <description>Add a short description of the talk (max. 2000 characters)</description>
23       <max_length>2000</max_length>
24       <title>Details</title>
25       <required>False</required>
26     </field>
27     <field name="audience"
28       type="zope.schema.Set"
29       form:widget="z3c.form.browser.checkbox.CheckBoxFieldWidget">
30       <description />
31       <title>Audience</title>
32       <value_type type="zope.schema.Choice">
33         <values>
34           <element>Beginner</element>
35           <element>Advanced</element>
36           <element>Professional</element>
37         </values>
38       </value_type>
39     </field>
40     <field name="room"
41       type="zope.schema.Choice"
42       form:widget="z3c.form.browser.radio.RadioFieldWidget"
43       security:write-permission="cmf.ReviewPortalContent">
44       <description></description>
45       <required>False</required>
46       <title>Room</title>
47       <vocabulary>ploneconf.site.vocabularies.Rooms</vocabulary>
48     </field>
49     <field name="speaker" type="zope.schema.TextLine">
50       <description>Name (or names) of the speaker</description>
51       <title>Speaker</title>
52       <required>False</required>
53     </field>
54     <field name="email" type="plone.schema.email.Email">
55       <description>Adress of the speaker</description>
56       <title>Email</title>
57       <required>False</required>
58     </field>
59     <field name="image" type="plone.namedfile.field.NamedBlobImage">
60       <description />
61       <required>False</required>
62       <title>Image</title>
63     </field>
64     <field name="speaker_biography" type="plone.app.textfield.RichText">
65       <description />
66       <max_length>1000</max_length>
67       <required>False</required>
68       <title>Speaker Biography</title>
69     </field>
70   </schema>
71 </model>

Next, in our JavaScript code, we provide a method for logging in a user and another one to check whether the user has a valid JSON web token. We use the localStorage facility of the browser to store the token on the client.

 ...
   methods: {
     login: function(userid, passwd) {
       this.userid = '';
       this.passwd = '';
       this.$http.post('/Plone/@login',
                 {'login': userid,
                  'password': passwd},
                 {headers:
                  {'Content-type':'application/json',
                   'Accept':'application/json'}}).
         then(function(data, status, headers, config){
           localStorage.setItem('jwtoken', data.token);
         }, function(error){
           alert('Could not log you in');
         });
     },
     is_logged_in: function() {
       // we assume the user is logged in when he has a JWT token (that is naive)
       return localStorage.getItem('jwtoken') != null;
     },
 ...

We continue with changes to index.html so that it uses the new methods. We provide a login form if the user doesn't have a valid JSON web token.

Only authenticated users can see the rest of the page.

     <div id="talklist">

       <div v-if="! is_logged_in()">
         <form role="form">
           <fieldset>
             <legend>Login</legend>
               <label for="userid">Login</label>
               <input type="text" id="userid" v-model="userid" placeholder="Enter login">
               <label for="passwd">Password</label>
               <input type="password" id="passwd" v-model="passwd" placeholder="Password">
           </fieldset>
           <button v-on:click="login(userid,passwd)">
             Login
           </button>
         </form>
       </div>

       <div v-if="is_logged_in()">
         <div role="tablist">

Last we have to add some code that allows authenticated users to submit a lightning talk. We add another JavaScript method first:

...
    submit_talk: function(subject, summary) {
      this.$http.post('/Plone/talks',
                 {'@type':'talk',
                  'type_of_talk':'Lightning Talk',
                  'audience':['Beginner','Advanced','Professional'],
                  'title':subject,
                  'description':summary},
                 {headers:
                  {'Content-type':'application/json',
                   'Authorization': 'Bearer ' + localStorage.getItem('jwtoken'),
                   'Accept':'application/json'}}).
        then(function(response){
          if(response.status === 201) { // created
            this.load_talks();
          }
        }, function(error){
          // according to docs, status can be 400 or 500
          // we check wether the token has expired - in this case,
          // we remove it from localStorage and disply the login page.
          // In all other cases, we display the message received
          // from Plone
          if ( (error.status == 400) && (error.data.type == 'ExpiredSignatureError') ) {
            localStorage.removeItem('jwtoken');
            location.reload();
          } else {
            // reason/error msg is contained in response body
            alert(error.message);
          }
        });
    },
...

Exercise#

Rewrite the load_talks() JavaScript method that it uses the portal search instead of /Plone/talks. Sort the list by date.

Solution
...
$scope.load_talks = function() {
  this.$http.get('/Plone/@search?portal_type=talk&sort_on=Date',
            {headers:{'Accept':'application/json'}}).
    then(function(response) {
...
  });