Element API for Craft CMS
This plugin makes it easy to create a JSON API for your entries (and other element types) in Craft CMS., (*1)
Itās powered by Phil Sturgeonās excellent Fractal package., (*2)
Requirements
This plugin requires Craft CMS 4.3.0+ or 5.0.0+., (*3)
Installation
You can install this plugin from the Plugin Store or with Composer., (*4)
From the Plugin Store
Go to the Plugin Store in your projectās Control Panel and search for āElement APIā. Then click on the āInstallā button in its modal window., (*5)
With Composer
Open your terminal and run the following commands:, (*6)
# go to the project directory
cd /path/to/my-project.test
# tell Composer to load the plugin
composer require craftcms/element-api
# tell Craft to install the plugin
./craft plugin/install element-api
Setup
To define your API endpoints, create a new element-api.php file within your config/ folder. This file should return an array with an endpoints key, which defines your siteās API endpoints., (*7)
Within the endpoints array, keys are URL patterns, and values are functions that define the endpoint configurations., (*8)
<?php
use craft\elements\Entry;
use craft\helpers\UrlHelper;
return [
'endpoints' => [
'news.json' => function() {
return [
'elementType' => Entry::class,
'criteria' => ['section' => 'news'],
'transformer' => function(Entry $entry) {
return [
'id' => $entry->id,
'title' => $entry->title,
'url' => $entry->url,
'jsonUrl' => UrlHelper::url("news/$entry->id.json"),
'summary' => $entry->summary,
];
},
];
},
'news/<entryId:\d+>.json' => function($entryId) {
return [
'elementType' => Entry::class,
'criteria' => ['id' => $entryId],
'one' => true,
'transformer' => function(Entry $entry) {
return [
'title' => $entry->title,
'url' => $entry->url,
'summary' => $entry->summary,
'body' => $entry->body,
];
},
];
},
]
];
Endpoint Configuration Settings
Endpoint configuration arrays can contain the following settings:, (*9)
class
The class name of the Fractal resource that should be used to serve the request. If this isnāt set, it will default to craft\elementapi\resources\ElementResource. (All of the following configuration settings are specific to that default class.), (*10)
elementType (Required)
The class name of the element type that the API should be associated with. Craftās built-in element type classes are:, (*11)
craft\elements\Assetcraft\elements\Categorycraft\elements\Entrycraft\elements\GlobalSetcraft\elements\MatrixBlockcraft\elements\Tagcraft\elements\User
'elementType' => craft\elements\Entry::class,
````
#### `criteria`
An array of parameters that should be set on the [Element Query](https://docs.craftcms.com/v3/element-queries.html) that will be fetching the elements.
```php
'criteria' => [
'section' => 'news',
'type' => 'article',
],
contentType
The content type the endpoint responses should have., (*12)
'contentType' => 'application/foo+json',
By default, the content type will be:, (*13)
-
application/javascript for endpoints that define a JSONP callback
-
application/feed+json for endpoints where the serializer is set to jsonFeed
-
application/json for everything else
The transformer that should be used to define the data that should be returned for each element. If you donāt set this, the default transformer will be used, which includes all of the elementās direct attribute values, but no custom field values., (*14)
// Can be set to a function
'transformer' => function(craft\elements\Entry $entry) {
return [
'title' => $entry->title,
'id' => $entry->id,
'url' => $entry->url,
];
},
// Or a string/array that defines a Transformer class configuration
'transformer' => 'MyTransformerClassName',
// Or a Transformer class instance
'transformer' => new MyTransformerClassName(),
Your custom transformer class would look something like this:, (*15)
<?php
use craft\elements\Entry;
use League\Fractal\TransformerAbstract;
class MyTransformerClassName extends TransformerAbstract
{
public function transform(Entry $entry)
{
return [
// ...
];
}
}
one
Whether only the first matching element should be returned. This is set to false by default, meaning that all matching elements will be returned., (*16)
'one' => true,
paginate
Whether the results should be paginated. This is set to true by default, meaning that only a subset of the matched elements will be included in each response, accompanied by additional metadata that describes pagination information., (*17)
'paginate' => false,
elementsPerPage
The max number of elements that should be included in each page, if pagination is enabled. By default this is set to 100., (*18)
'elementsPerPage' => 10,
pageParam
The query string param name that should be used to identify which page is being requested. By default this is set to 'page'., (*19)
'pageParam' => 'pg',
Note that it cannot be set to 'p' because thatās the parameter Craft uses to check the requested path., (*20)
resourceKey
The key that the elements should be nested under in the response data. By default this will be 'data'., (*21)
'resourceKey' => 'entries',
Any custom meta values that should be included in the response data., (*22)
'meta' => [
'description' => 'Recent news from Happy Lager',
],
serializer
The serializer that should be used to format the returned data., (*23)
Possible values are:, (*24)
includes
The include names that should be included for the current request, if any., (*25)
'includes' => (array)Craft::$app->request->getQueryParam('include'),
Note that this setting requires a custom transformer class thatās prepped to handle includes:, (*26)
class MyTransformerClassName extends TransformerAbstract
{
protected $availableIncludes = ['author'];
public function includeAuthor(Entry $entry)
{
return $this->item($entry->author, function(User $author) {
return [
'id' => $author->id,
'name' => $author->name,
];
});
}
// ...
}
excludes
The include names that should be excluded for the current request, which would otherwise have been included (e.g. if they were listed as a default include), if any., (*27)
'excludes' => 'author',
Like includes, this setting requires a custom transformer class., (*28)
callback
If this is set, a JSONP response will be returned with an application/javascript content type, using this setting value as the callback function., (*29)
For example, if you set this to:, (*30)
'callback' => 'foo',
Then the response will look like:, (*31)
foo({ /* ... */ });
Note that if you set this, the jsonOptions and pretty settings will be ignored., (*32)
jsonOptions
The value of the $options argument that will be passed to json_encode() when preparing the response. By default JSON_UNESCAPED_SLASHES | JSON_UNESCAPED_UNICODE will be passed., (*33)
'jsonOptions' => JSON_UNESCAPED_UNICODE,
pretty
Shortcut for adding JSON_PRETTY_PRINT to jsonOptions., (*34)
'pretty' => true,
cache
Whether the output should be cached, and for how long., (*35)
Possible values are:, (*36)
-
true (default) ā results are cached for the duration specified by the cacheDuration Craft config setting, or until a relevant element is saved or deleted.
-
false ā results are never cached.
- an integer ā results are cached for the given number of seconds.
- a interval spec string ā results are cached for the duration specified.
Note that the onBeforeSendData event does not get triggered when the cache is warm., (*37)
'cache' => 'PT1M', // one minute
cacheKey
The key that responses should be cached with, if something custom is needed., (*38)
Dynamic URL Patterns
URL patterns can contain dynamic subpatterns in the format of <subpatternName:regex>, where subpatternName is the name of the subpattern, and regex is a valid regular expression. For example, the URL pattern ānews/<entryId:\d+>.jsonā will match URLs like news/100.json. You can also use the tokens {handle} and {slug} within your regular expression, which will be replaced with the appropriate regex patterns for matching handles and element slugs., (*39)
Any subpattern matches in the URL pattern will be mapped to the endpoint config functionās arguments. For example, if a URL pattern contains an entryId subpattern, then you can add an $entryId argument to your endpoint config function, and whatever matches the URL subpattern will be passed to $entryId., (*40)
'news/<entryId:\d+>.json' => function($entryId) {
return [
'elementType' => craft\elements\Entry::class,
'criteria' => ['id' => $entryId],
'one' => true,
];
},
Setting Default Configuration Settings
You can specify default values for your endpoint configuration settings by adding a defaults key alongside your endpoints key (not within it)., (*41)
use craft\elements\Entry;
return [
'defaults' => [
'elementType' => Entry::class,
'elementsPerPage' => 10,
'pageParam' => 'pg',
'transformer' => function(Entry $entry) {
return [
'title' => $entry->title,
'id' => $entry->id,
'url' => $entry->url,
];
},
],
'endpoints' => [
'news.json' => function() {
return [
'criteria' => ['section' => 'news'],
]
},
'news/<entryId:\d+>.json' => function($entryId) {
return [
'criteria' => ['id' => $entryId],
'one' => true,
];
},
]
];
Examples
Here are a few endpoint examples, and what their response would look like., (*42)
Paginated Entry Index Endpoint
'ingredients.json' => function() {
return [
'criteria' => ['section' => 'ingredients'],
'elementsPerPage' => 10,
'transformer' => function(craft\elements\Entry $entry) {
return [
'title' => $entry->title,
'url' => $entry->url,
'jsonUrl' => UrlHelper::url("ingredients/$entry->slug.json"),
];
},
'pretty' => true,
];
},
{
"data": [
{
"title": "Gin",
"url": "/ingredients/gin",
"jsonUrl": "/ingredients/gin.json"
},
{
"title": "Tonic Water",
"url": "/ingredients/tonic-water",
"jsonUrl": "/ingredients/tonic-water.json"
},
// ...
],
"meta": {
"pagination": {
"total": 66,
"count": 10,
"per_page": 10,
"current_page": 1,
"total_pages": 7,
"links": {
"next": "/ingredients.json?p=2"
}
}
}
}
Single Entry Endpoint
'ingredients/<slug:{slug}>.json' => function($slug) {
return [
'criteria' => [
'section' => 'ingredients',
'slug' => $slug
],
'one' => true,
'transformer' => function(craft\elements\Entry $entry) {
// Create an array of all the photo URLs
$photos = [];
foreach ($entry->photos->all() as $photo) {
$photos[] = $photo->url;
}
return [
'title' => $entry->title,
'url' => $entry->url,
'description' => (string)$entry->description,
'photos' => $photos
];
},
'pretty' => true,
];
},
{
"title": "Gin",
"url": "/ingredients/gin",
"description": "<p>Gin is a spirit which derives its predominant flavour from juniper berries.</p>",
"photos": [
"/images/drinks/GinAndTonic1.jpg"
]
}
JSON Feed
Hereās how to set up a JSON Feed (Version 1.1) for your site with Element API., (*43)
Note that photos, body, summary, and tags are imaginary custom fields., (*44)
'feed.json' => function() {
return [
'serializer' => 'jsonFeed',
'elementType' => craft\elements\Entry::class,
'criteria' => ['section' => 'news'],
'transformer' => function(craft\elements\Entry $entry) {
$image = $entry->photos->one();
return [
'id' => (string)$entry->id,
'url' => $entry->url,
'title' => $entry->title,
'content_html' => (string)$entry->body,
'summary' => $entry->summary,
'image' => $image ? $image->url : null,
'date_published' => $entry->postDate->format(\DateTime::ATOM),
'date_modified' => $entry->dateUpdated->format(\DateTime::ATOM),
'authors' => [
['name' => $entry->author->name],
],
'language' => $entry->getSite()->language,
'tags' => array_map('strval', $entry->tags->all()),
];
},
'meta' => [
'description' => 'Recent news from Happy Lager',
],
'pretty' => true,
];
},
{
"version": "https://jsonfeed.org/version/1",
"title": "Happy Lager",
"home_page_url": "http://domain.com/",
"feed_url": "http://domain.com/feed.json",
"description": "Craft demo site",
"items": [
{
"id": "24",
"url": "http://domain.com/news/the-future-of-augmented-reality",
"title": "The Future of Augmented Reality",
"content_html": "<p>Nam libero tempore, cum soluta nobis est eligendi ...</p>",
"date_published": "2016-05-07T00:00:00+00:00",
"date_modified": "2016-06-03T17:43:36+00:00",
"author": {
"name": "Liz Murphy"
},
"tags": [
"augmented reality",
"futurism"
]
},
{
"id": "4",
"url": "http://domain.com/news/barrel-aged-digital-natives",
"title": "Barrel Aged Digital Natives",
"content_html": "<p>Nam libero tempore, cum soluta nobis est eligendi ...</p>",,
"date_published": "2016-05-06T00:00:00+00:00",
"date_modified": "2017-05-18T13:20:27+00:00",
"author": {
"name": "Liz Murphy"
},
"tags": [
"barrel-aged"
]
},
// ...
]
}
Wallogit.com
