plone.jsonapi.core 0.7.0

Latest Build Status

Abstract

An extensible Plone JSON API Framework

Introduction

This Package allows Users to expose content information via JSON.

Motivation

This project was born in 2012, out of the need for a data source to build a network based iOS application. Or more precise, I wanted to learn iOS programming and wanted to knit my own JSON API:)

I know, it is a little bit awkward to provide an own routing mechanism for Plone which dipatches the request after the ZPublisher did its job, but it worked and thus, I did it.

Limitations

Since the API comes after the ZPublisher, it can only make use of HTTP GET and HTTP POST methods. The other methods will never reach the API View.

Be aware that the API View comes with the permission zope2.View, so you need to programmatically check for the correct permissions on your custom routes.

See: http://developer.plone.org/security/permission_lists.html

Compatibility

The plone.jsonapi.core should work with Plone 3, 4 and 5 on Python 3.

Example:

[buildout]
...
versions = versions

[versions]
...
simplejson = 2.0.9
werkzeug = 0.7.2

Installation

There official release is on pypi, so you have to simply include plone.jsonapi.core to your buildout config.

Example:

[buildout]
...

[instance]
...
eggs =
    ...
    plone.jsonapi.core

API URL

After installation, the API View is available as a Browser View on your Plone site with the name @@API, for example http://localhost:8080/Plone/@@API.

API Framework

The main work is done in the plone.jsonapi.core.browser.api module. This module dispatches the incoming request and dispatches it to an endpoint function.

The API Router

The Router is responsible to manage and maintain API routes to endpoints.

Routes get defined by so called “Route Providers”.

A route provider is either a named Utility class, which implements the IRouteProvider interface, or simply a function, which is registered via the add_route decorator.

from plone.jsonapi.core import router

@router.add_route("/hello/<string:name>", "hello", methods=["GET"])
def hello(context, request, name="world"):
    return {"hello": name}

from zope import interface
from plone.jsonapi.core.interfaces import IRouteProvider

class ExampleRoutes(object):
    interface.implements(IRouteProvider)


    def initialize(self, context, request):
        """ called by the json api framework"""
        pass

    @property
    def routes(self):
        return (
            ("/hello/<string:name>", "hello", self.json_hello, dict(methods=['GET'])),
        )

    def json_hello(self, context, request, name="world"):
        return {"hello": name}

<!-- Extension point for custom routes -->
<utility
    name="my_routes"
    provides="plone.jsonapi.core.interfaces.IRouteProvider"
    factory=".routes.ExampleRoutes" />

from five import grok

...

grok.global_utility(ExampleRoutes, name="my_routes", direct=False)

{
    _runtime: 0.00025200843811035156,
    hello: "JSON Plone API"
}

API URLs

If you design your custom RESTful JSON API, you probably want to insert URLs to your specified resources, e.g:

http://localhost:8080/Plone/@@API/news/news_items_1

The plone.jsonapi.core.router module comes with a url_for method.

So when you want to insert the URL for the defined hello endpoint, you simply add it like this:

from plone.jsonapi.core import router

@router.add_route("/hello/<string:name>", "hello", methods=["GET"])
def hello(context, request, name="world"):
    return {
        "url": router.url_for("hello", values={"name": name}, force_external=True),
        "hello": name,
    }

It builds the URLs using the build method of the MapAdapter of Werkzeug. For details, see http://werkzeug.pocoo.org/docs/routing/#werkzeug.routing.MapAdapter.build

The resulting JSON will look like this:

http://localhost:8080/Plone/@@API/hello/world

Result:

{
    url: "http://localhost:8080/Plone/@@API/hello/world",
    runtime: 0.002997875213623047,
    hello: "world"
}

Permissions

You have to handle the permissions for your routes manually. so if you would like to restrict the permission of the hello route, you have to do something like this:

from AccessControl import getSecurityManager
from AccessControl import Unauthorized

from plone.jsonapi.core import router

@router.add_route("/hello/<string:name>", "hello", methods=["GET"])
def hello(context, request, name="world"):

    if not getSecurityManager().checkPermission("ViewHelloAPI", context):
        raise Unauthorized("You don't have the 'ViewHelloAPI' permission")

    return {
        "url": router.url_for("hello", values={"name": name}, force_external=True),
        "hello": name,
    }

Output:

{
    runtime: 0.0021250247955322266,
    success: false,
    error: "You don't have the 'ViewHelloAPI' permission"
}

0.7.0 - 2020-03-29

• https://github.com/collective/plone.jsonapi.core/pull/23 Add Python3 compatibility

0.6 - 2017-01-10

• Supports XML response. Use the request parameter asxml=1 or set the request Accept header to application/xml

• https://github.com/collective/plone.jsonapi.core/issues/21 Support file streams. Use the request parameter asbinary=1 or set the request Accept header to application/zip

• https://github.com/collective/plone.jsonapi.core/issues/22 Do not store the request on the router upon initialization

• https://github.com/collective/plone.jsonapi.core/issues/18 Handle None values

• https://github.com/collective/plone.jsonapi.core/issues/17 Print out Traceback’s to the console and not back to the client

0.5 - 2015-07-09

• https://github.com/collective/plone.jsonapi.core/pull/14 use urlsplit(request.get("ACTUAL_URL", "")).netloc to get the hostname

• added more tests

• changed info to debug logging to reduce verbosity

• smoe minor code cleanup

0.4 - 2014-03-04

• https://github.com/ramonski/plone.jsonapi.core/issues/10 add the traceback to the response when an error occurs

• https://github.com/ramonski/plone.jsonapi.core/issues/7 started with doctests

0.3 - 2014-01-23

• renamed package to plone.jsonapi.core due to namespace conflicts with plone.jsonapi.routes

• removed default plone route configuration.

• added version route

• changed the url_for method of the router to provide correct urls for virtual hosting.

0.2 - 2013-08-11

• Router implementation updated to support decorated functions as route providers.

• url_for functionality implemented

• documentation changed

0.1 - unreleased

• initial start of development