Building a Versioned REST API with Authentication in Yii2 Advanced

Vikas Kamboj — Tue, 09 Jun 2026 05:51:03 +0000

Yii2 Advanced comes with separate applications for frontend, backend, console, and shared code in common. It does not include an api application by default, but Yii2 Advanced is designed in a way that makes adding one straightforward.

In this post, we’ll create a separate API application, configure REST routes, add versioned URLs like /v1/users and /v2/users, and prepare the structure for authentication.

Yii2 Advanced Project Structure

A default Yii2 Advanced project usually looks like this:

backend/
common/
console/
frontend/
vendor/
composer.json

To build an API, create a new application folder at the same level as frontend and backend:

api/

After adding it, your structure becomes:

api/
backend/
common/
console/
frontend/
vendor/
composer.json

Creating the API Application

Inside the api folder, create this structure:

api/
  config/
    main.php
    main-local.php
    params.php
  controllers/
  modules/
  runtime/
  web/
    index.php

The api/web folder is the public document root for the API application.

Creating `api/web/index.php`

Create the entry file:

<?php

defined('YII_DEBUG') or define('YII_DEBUG', true);
defined('YII_ENV') or define('YII_ENV', 'dev');

require __DIR__ . '/../../vendor/autoload.php';
require __DIR__ . '/../../vendor/yiisoft/yii2/Yii.php';
require __DIR__ . '/../../common/config/bootstrap.php';

$config = yii\helpers\ArrayHelper::merge(
    require __DIR__ . '/../../common/config/main.php',
    require __DIR__ . '/../../common/config/main-local.php',
    require __DIR__ . '/../config/main.php',
    require __DIR__ . '/../config/main-local.php'
);

(new yii\web\Application($config))->run();

This bootstraps Yii and loads the shared common config plus API-specific configuration.

Creating `api/config/main.php`

Create the main API config file:

<?php

return [
    'id' => 'app-api',
    'basePath' => dirname(__DIR__),
    'controllerNamespace' => 'api\controllers',

    'components' => [
        'request' => [
            'csrfParam' => '_csrf-api',
            'parsers' => [
                'application/json' => yii\web\JsonParser::class,
            ],
        ],

        'response' => [
            'format' => yii\web\Response::FORMAT_JSON,
        ],

        'urlManager' => [
            'enablePrettyUrl' => true,
            'showScriptName' => false,
            'rules' => [
                'GET /' => 'site/index',
            ],
        ],
    ],
];

The important parts are:

'parsers' => [
    'application/json' => yii\web\JsonParser::class,
],

This allows Yii2 to read JSON request bodies.

And:

'response' => [
    'format' => yii\web\Response::FORMAT_JSON,
],

This makes API responses return JSON by default.

Creating `api/config/main-local.php`

Create a local config file:

<?php

return [
    'components' => [
        'request' => [
            'cookieValidationKey' => 'generate-a-random-secret-key-here',
        ],
    ],
];

Use a real random string for cookieValidationKey.

Creating `api/config/params.php`

Create an empty params file:

<?php

return [];

Adding Autoloading

If your project does not already autoload the api namespace, add it to composer.json:

"autoload": {
  "psr-4": {
    "api\\": "api/"
  }
}

Then run:

composer dump-autoload

Creating a Test Controller

Create a simple controller to confirm the API app works.

<?php

namespace api\controllers;

use yii\rest\Controller;

class SiteController extends Controller
{
    public function actionIndex()
    {
        return [
            'status' => 'ok',
            'app' => 'api',
        ];
    }
}

With this URL rule:

'rules' => [
    'GET /' => 'site/index',
],

You should be able to open:

https://api.yourdomain.com/

or locally:

http://localhost:8080/

and see:

{
  "status": "ok",
  "app": "api"
}

Where Do URL Rules Go?

URL rules are added inside the urlManager component in api/config/main.php:

'components' => [
    'urlManager' => [
        'enablePrettyUrl' => true,
        'showScriptName' => false,
        'rules' => [
            'GET /' => 'site/index',
        ],
    ],
],

The rules array belongs inside:

components.urlManager

not at the top level of the config.

Do You Need to Add Every API Endpoint Manually?

No. Yii2 REST URL rules can generate standard REST endpoints automatically.

For example:

[
    'class' => yii\rest\UrlRule::class,
    'controller' => 'user',
]

generates standard REST routes like:

GET    /users
GET    /users/123
POST   /users
PUT    /users/123
PATCH  /users/123
DELETE /users/123

Yii2 pluralizes REST controller names by default:

user -> /users
product -> /products
order -> /orders

For multiple controllers, you can group them:

[
    'class' => yii\rest\UrlRule::class,
    'controller' => [
        'user',
        'product',
        'order',
        'payment',
        'notification',
    ],
],

This gives each controller its standard REST URLs.

Adding Custom API Actions

For non-standard endpoints, use extraPatterns.

Example:

[
    'class' => yii\rest\UrlRule::class,
    'controller' => 'auth',
    'extraPatterns' => [
        'POST login' => 'login',
        'POST logout' => 'logout',
        'POST refresh-token' => 'refresh-token',
    ],
],

This creates:

POST /auth/login
POST /auth/logout
POST /auth/refresh-token

So even with many endpoints, you usually do not list all of them manually. You define REST controllers and add only custom routes where needed.

Complete URLs

The complete URL depends on your API base URL.

If your API is hosted at:

https://api.yourdomain.com

then the routes become:

GET    https://api.yourdomain.com/users
GET    https://api.yourdomain.com/users/123
POST   https://api.yourdomain.com/users
PUT    https://api.yourdomain.com/users/123
PATCH  https://api.yourdomain.com/users/123
DELETE https://api.yourdomain.com/users/123

For custom auth routes:

POST https://api.yourdomain.com/auth/login
POST https://api.yourdomain.com/auth/logout
POST https://api.yourdomain.com/auth/refresh-token

If running locally:

http://localhost:8080/users
http://localhost:8080/auth/login

If pretty URLs are not configured correctly, URLs may include index.php:

http://localhost:8080/index.php/users
http://localhost:8080/index.php/auth/login

Adding API Versioning

For versioned API URLs like:

https://api.yourdomain.com/v1/users
https://api.yourdomain.com/v2/users

the recommended Yii2 approach is to use modules.

Create this structure:

api/
  modules/
    v1/
      Module.php
      controllers/
        UserController.php
    v2/
      Module.php
      controllers/
        UserController.php

Creating the V1 Module

Create api/modules/v1/Module.php:

<?php

namespace api\modules\v1;

class Module extends \yii\base\Module
{
    public $controllerNamespace = 'api\modules\v1\controllers';
}

Creating the V2 Module

Create api/modules/v2/Module.php:

<?php

namespace api\modules\v2;

class Module extends \yii\base\Module
{
    public $controllerNamespace = 'api\modules\v2\controllers';
}

Registering API Modules

'modules' => [
    'v1' => [
        'class' => api\modules\v1\Module::class,
    ],
    'v2' => [
        'class' => api\modules\v2\Module::class,
    ],
],

Your config now includes the versioned modules.

Adding Versioned URL Rules

Inside components.urlManager.rules, add versioned REST rules:

'rules' => [
    [
        'class' => yii\rest\UrlRule::class,
        'controller' => [
            'v1/user',
            'v1/product',
            'v1/order',
        ],
    ],
    [
        'class' => yii\rest\UrlRule::class,
        'controller' => [
            'v2/user',
            'v2/product',
            'v2/order',
        ],
    ],
],

Now Yii2 maps these controllers:

api/modules/v1/controllers/UserController.php
api/modules/v2/controllers/UserController.php

to these URLs:

/v1/users
/v2/users

Creating a Versioned Controller

Create api/modules/v1/controllers/UserController.php:

<?php

namespace api\modules\v1\controllers;

use yii\rest\ActiveController;

class UserController extends ActiveController
{
    public $modelClass = 'common\models\User';
}

Now the following endpoints are available:

GET    /v1/users
GET    /v1/users/123
POST   /v1/users
PUT    /v1/users/123
PATCH  /v1/users/123
DELETE /v1/users/123

For v2, create:

<?php

namespace api\modules\v2\controllers;

use yii\rest\ActiveController;

class UserController extends ActiveController
{
    public $modelClass = 'common\models\User';
}

Now v2 endpoints are available:

GET    /v2/users
GET    /v2/users/123
POST   /v2/users
PUT    /v2/users/123
PATCH  /v2/users/123
DELETE /v2/users/123

Adding Versioned Auth Endpoints

For an auth controller inside v1:

[
    'class' => yii\rest\UrlRule::class,
    'controller' => 'v1/auth',
    'extraPatterns' => [
        'POST login' => 'login',
        'POST logout' => 'logout',
        'POST refresh-token' => 'refresh-token',
    ],
],

This creates:

POST /v1/auth/login
POST /v1/auth/logout
POST /v1/auth/refresh-token

Your controller would live at:

api/modules/v1/controllers/AuthController.php

Adding Bearer Token Authentication

Yii2 supports bearer token authentication with yii\filters\auth\HttpBearerAuth.

In a REST controller, add:

use yii\filters\auth\HttpBearerAuth;

public function behaviors()
{
    $behaviors = parent::behaviors();

    $behaviors['authenticator'] = [
        'class' => HttpBearerAuth::class,
    ];

    return $behaviors;
}

Example:

<?php

namespace api\modules\v1\controllers;

use yii\rest\ActiveController;
use yii\filters\auth\HttpBearerAuth;

class UserController extends ActiveController
{
    public $modelClass = 'common\models\User';

    public function behaviors()
    {
        $behaviors = parent::behaviors();

        $behaviors['authenticator'] = [
            'class' => HttpBearerAuth::class,
        ];

        return $behaviors;
    }
}

Requests must include an Authorization header:

Authorization: Bearer your-token-here

Finding Users by Access Token

Your common\models\User model should implement:

public static function findIdentityByAccessToken($token, $type = null)
{
    return static::findOne(['access_token' => $token]);
}

For this to work, your user table needs an access_token column, or you need a separate token table.

For production APIs, avoid storing permanent plain tokens. A better approach is usually:

short-lived access tokens
refresh tokens
hashed token storage
JWT
OAuth2

The simple access_token example is useful for learning, but production authentication should be designed more carefully.

Recommended Final Structure

A versioned API app may look like this:

api/
  config/
    main.php
    main-local.php
    params.php
  modules/
    v1/
      Module.php
      controllers/
        AuthController.php
        UserController.php
        ProductController.php
    v2/
      Module.php
      controllers/
        AuthController.php
        UserController.php
        ProductController.php
  runtime/
  web/
    index.php
backend/
common/
console/
frontend/

Final Notes

In Yii2 Advanced, an API is simply another application beside frontend and backend. You create the api folder manually, give it its own config and web entry point, then use REST URL rules and modules to keep the code organized.

The most common pattern is:

api/modules/v1/controllers/UserController.php -> /v1/users
api/modules/v2/controllers/UserController.php -> /v2/users

This keeps your API versions cleanly separated in both the URL and the codebase.

DEV Community: Vikas Kamboj