# Configuring the API

Each API project configuration is contained within a dedicated file in the /config directory. Additionally, this process adds a boilerplate system schema into the project's database.

# Project Config Files

Each API instance can manage multiple projects. Each project has its own config, database, and file storage. Any extensions installed in the API will be available for all projects it manages.

The first project you create must be the default. Default projects are defined by their config file name: config/api.php and use the _ API URL project scope, eg: https://api.example.com/_/collections

Subsequent projects can be added with new config files, using this naming convention: config/api.[project-name].php. Each project's config should point to a dedicated database and unique storage paths. Once configured, the API URL will be scoped to the project, eg: https://api.example.com/project-name/collections

# Configure Manually

# Create Config File

Create a copy of config/api_sample.php and change the name to config/api.php (for default project).

# Database Details

Next, update the database values with your own:

'database' => [
    'type' => 'mysql',
    'host' => 'localhost',
    'port' => 3306,
    'name' => 'directus_test',
    'username' => 'root',
    'password' => 'root',
    'engine' => 'InnoDB',
    'charset' => 'utf8mb4'
]

# Auth Keys

These keys can be anything, but we recommend a “strong” and unique value. They are unique identifiers that ensure your auth tokens are only able to be used within this project.

'auth' => [
  'secret_key' => '<secret-authentication-key>',
  'public_key' => '<public-authentication-key>',
  'social_providers' => [ ... ]

# Boilerplate System Database

Finally, we must import the Directus system tables and data primer into the database by importing this SQL file: /src/schema.sql. With this method, your initial Admin user credentials will be:

• User: admin@example.com
• Password: password

# Configure with Script

# Create Config File

$ bin/directus install:config -n <database-name> -u <mysql-user> -p <mysql-password>

# Options

# Boilerplate System Database

$ bin/directus install:database

# Create Admin User

$ bin/directus install:install -e <admin-email> -p <admin-password> -t <project-title>

# Options

# Testing

Test that everything is working by making a request to the users endpoint using the access_token.

GET http://localhost/_/users?access_token=admin_token

# Configure with App

@TODO

# Config File Options

# app

The API application settings

# settings

The settings for Slim, the micro-framework used by Directus

# database

Settings for the database connection

# cache

Enables caching to speed-up API responses

# APC

It uses PHP Alternative PHP Cache (APC) extension to store the cache data.

# APCU

It uses PHP APC User Cache (APCu) extension to store the cache data. APCu is the same extension as APC, the only different is that doesn't have OPCache. Directus only needs the data store feature.

# Filesystem

It stores cache data in the server's filesystem.

# Memcached

It uses Memcached caching system and PHP Memcached extension to store cache data.

Note: Memcached and PHP Memcached extension must be installed.

# Ubuntu example
sudo apt-get install memcached
sudo apt-get install php-memcached

# Redis

It uses Redis and PHP Redis extension to store cache data.

Note: Redis Server and PHP Redis extension must be installed.

# Ubuntu example
sudo apt-get install redis-server
sudo apt-get install php-redis

# storage

Choose where files can be uploaded. Currently we support local and Amazon-S3

# mail

A list of key-value-pairs (array) mail configurations. Currently only the default key is supported. Each value must have at least the following information:

When the transport is set to one of the transports mentioned below, any of those options can be used.

# smtp

# sendmail

# cors

Cross-Origin Resource Sharing (CORS) is a mechanism that allows you to restricted access of Directus API from other domains

# rate_limit

# actions

Actions hooks allow you to execute custom code when a Directus Event happens. You can register functions or classes to a hook name and when the event happens it will execute that code. For example:

'hooks' => [
    'actions' => [
        'item.create.articles' => function ($data) {
            $content = 'New article was created with the title: ' . $data['title'];
            // pesudo function
            notify('admin@example.com', 'New Article', $content);
        }
    ]
]

The example above will execute the notify function after an item has been inserted into the articles table.

A class that implements the __invoke method or inherits from \Directus\Hook\HookInterface can also be used, and instead of passing a function you must pass the fully qualified class name resolution. For example: \MyApplication\Events\NotifyNewArticles::class.

# filters

Filters work the same as hooks except that you can manipulate the data being passed. This is a nice way to add, remove, or manipulate the data before it is sent to the database. Filters always pass a \Directus\Hook\Payload object as the first parameter and it must return a payload object. An example would be generating a new UUID every time an article is created:

'hooks' => [
    'filters' => [
        'item.create.articles:before' => function (\Directus\Hook\Payload $payload) {
            $payload->set('uuid', \Directus\generate_uuid4());

            return $payload;
        }
    ]
]

# feedback

It doesn't do anything on version 2.0, but it was created to ping our server to understand approximately how many instances of Directus exists.

# tableBlacklist

It doesn't do anything, but it was meant to blacklist tables from being used by Directus.

# auth

Out-of-the-box Directus supports Okta, GitHub, Facebook, Twitter and Google Single-Sign-On (SSO), but also allows you to create your own providers.

# Okta

Okta offers both SSO as well as external user management through SCIM. Learn more about configuring Okta auth.

# GitHub

# Google

# Twitter

# Facebook