craftcms/element-api craftcms/element-api

  • Stars
    star
    498
  • Rank 88,494 (Top 2 %)
  • Language
    PHP
  • License
    MIT License
  • Created about 9 years ago
  • Updated 5 months ago
Twitter logo Share LinkedIn logo Share Facebook logo Share
craftcms/element-api
github

craftcms

Reviews

There are no reviews yet. Be the first to send feedback to the community and the maintainers!

Repository Details

Create a JSON API/Feed for your elements in Craft.

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.

It’s powered by Phil Sturgeon’s excellent Fractal package.

Requirements

This plugin requires Craft CMS 4.0 or later.

Installation

You can install this plugin from the Plugin Store or with Composer.

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.

With Composer

Open your terminal and run the following commands:

# 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.

Within the endpoints array, keys are URL patterns, and values are functions that define the endpoint configurations.

<?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 [
                        '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:

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.)

elementType (Required)

The class name of the element type that the API should be associated with. Craft’s built-in element type classes are:

  • craft\elements\Asset
  • craft\elements\Category
  • craft\elements\Entry
  • craft\elements\GlobalSet
  • craft\elements\MatrixBlock
  • craft\elements\Tag
  • craft\elements\User
'elementType' => craft\elements\Entry::class,

criteria

An array of parameters that should be set on the Element Query that will be fetching the elements.

'criteria' => [
    'section' => 'news',
    'type' => 'article',
],

contentType

The content type the endpoint responses should have.

'contentType' => 'application/foo+json',

By default, the content type will be:

  • 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

transformer

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.

// 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:

<?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.

'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.

'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.

'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'.

'pageParam' => 'pg',

Note that it cannot be set to 'p' because that’s the parameter Craft uses to check the requested path.

resourceKey

The key that the elements should be nested under in the response data. By default this will be 'data'.

'resourceKey' => 'entries',

meta

Any custom meta values that should be included in the response data.

'meta' => [
    'description' => 'Recent news from Happy Lager',
],

serializer

The serializer that should be used to format the returned data.

Possible values are:

includes

The include names that should be included for the current request, if any.

'includes' => (array)Craft::$app->request->getQueryParam('include'),

Note that this setting requires a custom transformer class that’s prepped to handle includes:

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.

'excludes' => 'author',

Like includes, this setting requires a custom transformer class.

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.

For example, if you set this to:

'callback' => 'foo',

Then the response will look like:

foo({ /* ... */ });

Note that if you set this, the jsonOptions and pretty settings will be ignored.

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.

'jsonOptions' => JSON_UNESCAPED_UNICODE,

pretty

Shortcut for adding JSON_PRETTY_PRINT to jsonOptions.

'pretty' => true,

cache

Whether the output should be cached, and for how long.

Possible values are:

  • 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.

'cache' => 'PT1M', // one minute

cacheKey

The key that responses should be cached with, if something custom is needed.

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.

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.

'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).

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.

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.

Note that photos, body, summary, and tags are imaginary custom fields.

'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"
            ]
        },
        // ...
    ]
}

More Repositories

1

cms

Build bespoke content experiences with Craft.
PHP
3,213
star
2

happy-lager

Craft CMS demo site.
PLpgSQL
735
star
3

awesome

A collection of awesome Craft CMS plugins, articles, resources and shiny things.
526
star
4

contact-form

Add a simple contact form to your Craft CMS site.
PHP
293
star
5

feed-me

Craft CMS plugin for importing entry data from XML, RSS or ATOM feeds—routine task or on-demand.
PHP
287
star
6

commerce

Fully integrated ecommerce for Craft CMS.
PHP
215
star
7

craft

Composer starter project for Craft CMS.
Twig
183
star
8

nitro

Speedy local dev environment for @craftcms.
Go
178
star
9

plugins

The master list of Craft 3-compatible plugins
107
star
10

guest-entries

Accept anonymous entry submissions with Craft.
PHP
106
star
11

docker

Craft CMS Docker images.
Dockerfile
102
star
12

redactor

Edit rich text content in Craft CMS using Redactor by Imperavi.
JavaScript
101
star
13

webhooks

Plugin for integrating Craft with Zapier and IFTTT.
PHP
84
star
14

generator

Scaffold new Craft CMS plugins, modules, and system components from the CLI
PHP
83
star
15

starter-blog

Blog starter site learning resource.
JavaScript
79
star
16

server-check

Craft CMS server requirements checker.
Hack
68
star
17

store-hours

Manage business hours with Craft CMS.
PHP
62
star
18

aws-s3

Amazon S3 volume type for Craft CMS.
PHP
60
star
19

gatsby-source-craft

Gatsby source plugin for Craft CMS.
TypeScript
54
star
20

spoke-and-chain

Craft CMS + Craft Commerce demo site.
Twig
54
star
21

phpstorm-settings

PhpStorm settings used for Craft CMS development.
50
star
22

anchors

Add anchor links to headings in your Craft CMS website content.
PHP
48
star
23

europa-museum

Craft CMS demo site.
SCSS
47
star
24

ckeditor

Edit rich text content in Craft CMS using CKEditor.
PHP
46
star
25

shopify

Synchronize and extend product data from your Shopify storefront.
PHP
45
star
26

apple-news

Publish your Craft CMS content with Apple News Format.
PHP
41
star
27

docs

Documentation for Craft CMS, Craft Commerce, and other official products.
JavaScript
38
star
28

commerce-stripe

Stripe payment gateway for Craft Commerce
PHP
30
star
29

plugin-installer

Composer installer for Craft CMS plugins.
PHP
28
star
30

mailgun

Mailgun mailer adapter for Craft CMS.
PHP
28
star
31

redactor-clips

Adds Redactor’s “Clips” plugin to Rich Text fields in Craft
PHP
27
star
32

simple-text

Simple textarea field type for Craft CMS.
JavaScript
27
star
33

contact-form-honeypot

Add a honeypot captcha to your Craft CMS contact form.
PHP
26
star
34

vue-asset

⛔️ DEPRECATED | Vue.js asset bundle for Craft 3 Beta
JavaScript
24
star
35

postmark

A Postmark mail adapter for Craft CMS.
PHP
20
star
36

rector

Rector rules for updating plugins and modules to Craft CMS 4.
PHP
19
star
37

digital-products

Sell digital products with Craft Commerce.
PHP
18
star
38

legacy-docs

The source documentation for Craft CMS
JavaScript
16
star
39

ecs

Easy Coding Standard configurations for Craft CMS projects.
PHP
16
star
40

oauth2-craftid

Craft ID Provider for OAuth 2.0 Client.
PHP
15
star
41

query

Run SQL queries as an admin from the Craft CMS control panel.
PHP
15
star
42

gatsby-helper

Craft CMS helper plugin for Gatsby.
PHP
15
star
43

fix-fks

Utility that restores any missing foreign key constraints
PHP
12
star
44

mandrill

Mandrill mailer adapter for Craft CMS.
PHP
12
star
45

phpstan

PHPStan configuration for Craft CMS projects.
12
star
46

google-cloud

Google Cloud Storage volume type for Craft CMS.
PHP
11
star
47

tutorial-project

Tutorial demo project source.
Twig
9
star
48

image

Container images that are used as the base for Craft CMS container applications
Dockerfile
8
star
49

sass

Sass mixins for the Craft CMS control panel.
SCSS
8
star
50

commerce-paypal

PayPal payment gateway for Craft Commerce.
PHP
6
star
51

commerce-omnipay

Omnipay gateway bridge for Craft Commerce
PHP
5
star
52

license

The Craft License
5
star
53

hexdec

Adds a ‘hexdec’ filter to Craft CMS.
PHP
5
star
54

commerce-paypal-checkout

PayPal Checkout gateway for Craft Commerce.
PHP
5
star
55

commerce-mollie

Mollie payment gateway for Craft Commerce.
PHP
5
star
56

.github

GitHub community files for Craft CMS.
5
star
57

ontherocks

JavaScript
5
star
58

stripe

Sync and extend Stripe products and subscriptions.
PHP
5
star
59

azure-blob

Azure Blob Storage for Craft CMS.
PHP
4
star
60

commerce-sagepay

SagePay payment gateway for Craft Commerce.
PHP
4
star
61

yii2-dynamodb

Yii2 implementation of a queue and cache driver for DynamoDB
PHP
4
star
62

automation-workshop

PLpgSQL
4
star
63

html-field

Base class for Craft CMS field types with HTML values.
PHP
4
star
64

cloud

Public repo for discussions, feature requests, and ehancements Craft Cloud. For support, please email [email protected]
4
star
65

legacy-commerce-docs

Commerce Documentation
JavaScript
4
star
66

flysystem

Flysystem integration package for Craft CMS 4
PHP
3
star
67

locales

Craft CMS localization data for all the locales.
PHP
3
star
68

commerce-eway

eWay payment gateway for Craft Commerce.
PHP
3
star
69

commerce-multisafepay

MultiSafepay payment gateway for Craft Commerce.
PHP
3
star
70

rackspace

Rackspace Cloud Files volume type for Craft CMS
PHP
2
star
71

commerce-paystack

Paystack payment gateway for Craft Commerce.
PHP
2
star
72

commerce-worldpay

Worldpay payment gateway for Craft Commerce.
PHP
2
star
73

plugin-port-helper

Plugin port helper for porting plugins from Craft 2 to Craft 3.
PHP
2
star
74

homebrew-nitro

Brew repository for Craft Nitro.
Ruby
2
star
75

commerce-taxjar

TaxJar integration for Craft Commerce.
PHP
2
star
76

docs-translations

Translated content moved out of `docs` and maintained separately.
JavaScript
1
star
77

textlint-rule-linkable-params

Custom textlint rule for allowing lowercase variations of terms when linked.
JavaScript
1
star
78

craftcms-imgproxy

PHP
1
star
79

console

Public repo for bug reports, discussions, feature requests, and ehancements Craft Console and the Plugin Store
1
star
80

ddev-craft-cloud

Shell
1
star