JSON API

Provides simple JSON access to Bolt's internal data structures. The specification of the JSON responses are based on JSON API.

Enabling this extension adds routes to the application that serves content as JSON rather than HTML. This route defaults to /json, so if, for example, you have a contenttype named entries, then the entry with ID 1 is available under /json/entries/1.

Configuration

In order to enable JSON serving for any contenttype, it has to be added to the extension's configuration file, located at app/config/extensions/jsonapi.bolt.yml.

Note in particular that contenttypes that you don't mention in the configuration file won't be served by the JSON API extension.

Base URL

Overriding the base setting allows you to customize where the API is accessible from. This defaults to /json.

base: '/json'

Contenttypes

Only contenttypes listed under contenttypes in the config will be served; for any other contenttype, the API will return 404 errors.

Besides errors, there are two types of responses you can receive, a list of items or single item. You can customize the fields shown in the responses with list-fields and item-fields respectively.

Both field names and taxonomy names are supported. If a field and a taxonomy share the same names, both will be included. Taxonomy values are always under the taxonomy property under attributes, whereas normal fields can be found directly under attributes.

To use the defaults for a contenttype, just leave its entry empty. This will include all user-defined fields (fields and taxonomies in contenttypes.yml), the ID and its contenttype in the listing, but not any of the base fields that Bolt adds to all contenttypes, such as datecreated.

With JSON API, you can also request which fields are to be returned with ?fields[<contenttype>]=<field1>,<field2>. To limit the options, you can set allowed-fields in order to filter these. At the moment, list-fields and item-fields ignore the allowed-fields setting.

The where-clause setting allows you to set additional conditions that are always set by default.

contenttypes:
    entries:
        item-fields: [ title, slug, teaser, image ]
        list-fields: [ title, slug, teaser, image ]
        allowed-fields: [ title, slug, teaser, image ]
        where-clause:
            status: 'published'
        order: title,-datepublish
    pages:
        # use 'default' settings

Images

For images, you'll get an absolute URL to that asset. By default, this extension adds an absolute URL to a 400x300 thumbnail in the response. By overriding the thumbnail setting, you can set a preferred width and height.

thumbnail:
    width: 400
    height: 300

Headers

To work correctly with other tools that read the JSON generated this extension, it might be necessary to set the correct headers with the response. By default, this extension sets the following:

headers:
    'Access-Control-Allow-Origin': '*'
    'Content-Type': 'application/vnd.api+json'

You can define additional headers as required, or tweak the existing ones.

Queries

This extension implements the JSON API specification, as follows:

where {ct} means {contenttype}, the name of the specified contenttype.

Query Parameters

The list call accepts some extra parameters (in the form of query string parameters appended to the URL):

Additional Queries

Besides the basic JSON API features, below are some additional Bolt specific queries that you may find useful:

Bolt Translate integration

In order to use this extension with bolt/translate. Set up the translate as usual. Then, for every query, add a _locale parameter, e.g. /pages?_locale=en.

Road Map

• Better handling of menus.
• Better handling of taxonomies.
• Better search.
• Handle specific fieldtypes:
  • Handle JSON fields.
  • Handle select-contenttype fields.
• Add hooks for handling specific fieldtypes.
• Add i18n for detail field in error messages.