area17 / twill-api
Requires
- php: ^8.0
- area17/twill: ^3.0|3.x-dev
- illuminate/support: ^10.13
- laravel-json-api/laravel: ^3.0
- spatie/laravel-package-tools: ^1.11
Requires (Dev)
- fakerphp/faker: ^1.15
- friendsofphp/php-cs-fixer: ^3.0
- laravel-json-api/testing: ^2.1
- mockery/mockery: ^1.4
- nunomaduro/collision: ^7.5
- orchestra/testbench: ^8.5
- phpunit/phpunit: ^10.2
- symfony/yaml: ^6.0
This package is auto-updated.
Last update: 2024-10-08 00:03:37 UTC
README
Provide a read-only API to Twill models and entities along with base structure to create your own JSON:API compliant REST API. This package is based on and requires the excellent Laravel JSON:API package.
Installation
This package needs a Laravel project with Twill already set up.
Install Laravel JSON:API
Follow the steps outlined in the Laravel JSON:API documentation.
Update config/jsonapi.php
with the namespace you would like to use.
- 'namespace' => 'JsonApi', + 'namespace' => 'TwillApi',
Install Twill API
composer require area17/twill-api
Publish config file config/twill-api.php
and migrations. Apply migrations.
php artisan vendor:publish --tag=twill-api-config php artisan vendor:publish --tag=twill-api-migrations php artisan migrate
Create you base Server.php
class
php artisan twill-api:server
Update config/jsonapi.php
servers
key with your newly created Server
class.
'servers' => [ - // 'v1' => \App\JsonApi\V1\Server::class, + 'v1' => \App\TwillApi\V1\Server::class, ],
If you want to make you API public (which is convenient early in development), you can update the authorisable
method in your Server
class.
function authorizable(): bool { - return true; + return false; }
Add API middlewares you the api
group in app/Http/Kernel.php
. See below for a list of the available middlewares.
Middlewares
Middleware to set locale
To query the API by adding the locale query string to the url. For example https://example.com/api/v1/books?locale=fr
will give you the results available in the French (fr) locale.
protected $middlewareGroups = [ // ... 'api' => [ \A17\Twill\API\Http\Middleware\SetLocale::class, // ...
Middleware to remove unpublished content
from browser fileds and features.
protected $middlewareGroups = [ // ... 'api' => [ \A17\Twill\API\Http\Middleware\EnableFeaturePublishedScope::class, \A17\Twill\API\Http\Middleware\EnableRelatedItemPublishedScope::class, // ...
Traits
Whenever your models has media or files attached to them, you must add the traits provided in this package in order to expose a relationship to the pivot models for each (by default it is the mediables
and fileables
tables).
If your model also have children blocks (saved through repeater inside a block), you must add the HasChildBlocks
for the API to respect the parent/child relation in the API response.
use A17\Twill\API\Models\Traits\HasChildBlocks; use A17\Twill\API\Models\Traits\HasFileables; use A17\Twill\API\Models\Traits\HasMediables; class Page { use HasChildBlocks, HasFileables, HasMediables; // ... }
Create a resource schema and API route
To create a basic schema for a new resource (model), use the artisan command twill-api:schema
. Pass the name of the Twill module as the argument.
php artisan twill-api:schema snippets
This command will create app/TwillApi/V1/Snippets/SnippetSchema.php
. The command will display a few instructions to register the new schema with the API server and how to declare the endpoint in you routes/api.php
.
For what is available from there, consult the Laravel JSON:API documentaiton under the Schemas section.
Your new endpoint should now be available at http://localhost/api/v1/snippets
.
Resources
Endpoints
This package provides these endpoints along with their schema:
/api/v1
/api/v1/blocks
/api/v1/blocks/{id}
/api/v1/features
/api/v1/features/{id}
/api/v1/files
/api/v1/files/{id}
/api/v1/media
/api/v1/media/{id}
/api/v1/related-items
/api/v1/related-items/{id}
/api/v1/tags
/api/v1/tags/{id}
/api/v1/settings
/api/v1/settings/{id}
/api/v1/users
/api/v1/users/{id}
Blocks
(to do)
php artisan twill-api:block-content text php artisan twill-api:block-content my-block-name
Browser fields (related items)
(to do)
Features
(to do)
Use API tokens to show unpublished content
(to do)