Go headless

Since Roadiz v1.6, you can create a 100% headless project using:

# Create a new Roadiz project
composer create-project roadiz/headless-edition myheadless_project

No more theme, just business logic

Headless edition get rid of themes logic in favor of a simple src/ folder to add custom business logic. All API features are handled by AbstractApiTheme which is registered as a composer dependency and in your src/AppKernel.php file.

# src/AppKernel.php
public function register(Container $container): void
{
    parent::register($container);
    // Headless edition: do not remove API services
    $container->register(new \Themes\AbstractApiTheme\Services\AbstractApiServiceProvider());
    $container->register(new \App\AppServiceProvider());

    /*
     * Add your own service providers.
     */
}

Headless structure

  • bin/: Contains the Roadiz CLI executable

  • docker/: Tools for creating development and production Docker image for your project

  • app/: Contains every runtime resources from configuration to app cache and nodes-sources entities

    • cache/: Every cache file for Twig templates and Intervention Request images (this folder must be writable for PHP)
    • conf/: Your setup configuration file(s) (this folder must be writable for PHP)
    • gen-src/: Generated PHP code for Doctrine and your Node-types entities (this folder must be writable for PHP)
    • logs/: Monolog logs folder

  • files/: Private documents and font files root (this folder must be writable for PHP)

  • samples/: This folder contains useful configuration and example files for Apache or Nginx webservers

  • web/: Your website root, it contains your application entry-points and your public assets

    • files/: Public documents (this folder must be writable for PHP)
    • themes/: public assets mirror for each theme, this folder contains symlinks to your themes/YourTheme/static folder

  • src/: Contains all your website logic

  • vendor/: Dependencies folder managed by Composer

Configure CORS

# src/AppServiceProvider.php
/**
 * @return array
 */
$container['api.cors_options'] = [
    'allow_credentials' => true,
    // Allow all origin or defines some regex domains
    'allow_origin' => ['*'],
    'allow_headers' => true,
    'origin_regex' => false,
    'allow_methods' => ['GET'],
    // Expose Link header for NuxtJS to resolve other translations
    'expose_headers' => ['Link'],
    'max_age' => 60*60*24
];

API usage and authentication

API endpoints are described in detail in AbstractApiTheme repository README. You’ll get automatic:

  • Collection listing for all nodes-sources
  • Collection listing per node-type
  • Single item endpoint
  • User endpoint
  • …

All with query-string parameters for searching and filtering JSON output.

API can be accessed using:

  • Simple X-Api-Key access per application for non-user related content
  • Or OAuth2 applications with client_credentials or authorization_code grant types.