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
.
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.
Overriding the base
setting allows you to customize where the API is
accessible from. This defaults to /json
.
base: '/json'
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
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
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.
This extension implements the JSON API specification, as follows:
URL | Description |
---|---|
/{ct} |
Returns a list of records of the specified contenttype . |
/{ct}/{id} |
Returns a single record of the specified contenttype . |
/{ct}/{id}/{relatedtype} |
Returns a list of records that is related to the specified record with specified id . |
where {ct}
means {contenttype}
, the name of the specified contenttype.
The list call accepts some extra parameters (in the form of query string parameters appended to the URL):
Option | Description |
---|---|
sort |
Order the list by the specified field. Prefix the fieldname with a minus/hyphen to set the orderering to descending. Example sort=id or sort=-id . Note: Bolt currently does not support sorting on multiple fields. |
page[size] |
Specify the number of items to return. Example: page[size]=10 |
page[number] |
To be combined with page[size] : get the n-th page. This is 1-based, so 1 designates the first page. Example: page[number]=1&page[size]=10 . |
include |
Fetches all the related records of the specified contenttype(s) of the record(s) in the included field of the JSON response. Separate multiple contenttypes with a comma. Example: include=pages . |
fields[] |
Set the fields that are shown in the response per specified contenttype. Separate multiple fields with commas. Multiple fields[] parameters are possible. Example: fields[entries]=slug,teaser . |
filter[] |
Filter records where a certain field must be equal to the specified {value} . Multiple filter[] parameters are possible. Example: filter[id]=1,2 . |
contains[] |
Filter records where a certain field must contain the specified {value} . Multiple contains[] parameters are possible. Example: contains[id]=1,2 . |
Besides the basic JSON API features, below are some additional Bolt specific queries that you may find useful:
URL | Description |
---|---|
/{ct}/search?q={query} |
Searches for {query} in a specific contenttype . |
/search?q={query} |
Searches for {query} in all contenttypes. |
/menu |
Returns a list of all menus defined in menu.yml . |
/menu?q={name} |
Returns the menu with the specified name. |
/taxonomy |
Returns a list of all taxonomies defined in taxonomy.yml . |
/taxonomy?q={name} |
Returns the taxonomy with the specified name. |
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
.
- 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.