Программирование с помощью Yii2: создание RESTful API

Russian (Pусский) translation by Anna k.Ivanova (you can also view the original English article)

Final product image — What You'll Be Creating

В этой серии Программирование с помощью Yii2 я направляю читателей через использование фреймворка Yii2 для PHP. Вас также может заинтересовать мое введение в Yii Framework, в котором рассматриваются преимущества Yii и которое так же включает обзор нового в Yii 2.x.

В сегодняшнем учебнике я рассмотрю, как создать REST API в Yii, чтобы подключить ваше приложение к облаку, мобильным приложениям и другим службам. Я проведу вас через руководство по быстрому старту REST API Yii и предоставлю контекст и примеры обычных запросов.

Начало работы с REST API Yii

Построение REST API в Yii на самом деле довольно просто. Вы можете использовать существующий фреймворк MVC, но вы создаете отдельную точку доступа, к которой вы собираетесь обращаться различными службами (а не посетителями веб-сайта).

Преимущества Yii REST Framework

Yii Framework предоставляет широкую поддержку и подробную документацию для создания API-интерфейсов. Вот некоторые из встроенных возможностей при создании API:

Быстрое прототипирование с поддержкой общих API для Active Record. Это позволяет быстро и легко выявлять функциональность CRUD модели данных с помощью API.
Согласование формата ответа (поддержка JSON и XML по умолчанию). Существует встроенная поддержка для возврата данных в общие форматы вывода.
Настраиваемая сериализация объектов с поддержкой выбираемых полей вывода. Можно легко изменить, какие данные будут возвращены.
Правильное форматирование собранных данных и ошибок проверки.
Поддержка Hypermedia As The Engine Of Application State (HATEOAS)
Эффективная маршрутизация с правильной проверкой HTTP-глаголов.
Встроенная поддержка глаголов OPTIONS и HEAD.
Аутентификация и авторизация.
Кэширование данных и кеширование HTTP.
Ограничение рейтов.

У меня не будет возможности коснуться всего этого сегодня.

Мой интерес к REST API

В этом эпизоде я создам API, чтобы мы могли манипулировать таблицей Item, созданной в службе Twixxr, из этого учебника API Twitter. Но я также планирую создать API для нашей серии статей, посвященной Планировщику собраний. Для создания приложения iOS потребуется безопасный API. API будет поддерживать связь между мобильным приложением и облачным сервисом.

Создание REST контроллера

С помощью REST-фреймворка Yii мы создадим конечную точку для нашего API и организуем контроллеры для каждого типа ресурсов.

Ресурсы - это, по сути, модели данных нашего приложения. Они наследуются от yii\base\Model.

Класс yii\rest\UrlRule предоставляет готовую маршрутизацию, сопоставляющую нашу модель данных с конечными точками API CRUD:

Programming Yii2 REST API UrlRule Documentation of CRUD API endpoints

Создание дерева в качестве конечной точки API

В шаблоне Yii2 Advanced есть интерфейсное и back-end дерево, и это расширяемо. Чтобы отделить функции API, мы создадим третье дерево.

Разработчик Yii Алекс Макаров дает это полезное руководство по созданию дополнительных деревьев, которое я выполнил для создания моего третьего дерева:

$ cp -R backend api
$ cp -R environments/dev/backend/ environments/dev/api
$ cp -R environments/prod/backend/ environments/prod/api

Затем я использовал редактор Atom, чтобы выполнить глобальный поиск и заменить «backend» на «api» в новом дереве api.

И я добавил псевдоним api в /common/config/bootstrap.php:

<?php
Yii::setAlias('@common', dirname(__DIR__));
Yii::setAlias('@frontend', dirname(dirname(__DIR__)) . '/frontend');
Yii::setAlias('@backend', dirname(dirname(__DIR__)) . '/backend');
Yii::setAlias('@api', dirname(dirname(__DIR__)) . '/api');
Yii::setAlias('@console', dirname(dirname(__DIR__)) . '/console');
Yii::setAlias('@twixxr', dirname(dirname(__DIR__)) . '/twixxr');

Настройка маршрутизации URL для входящих запросов

В /api/config/main.php нам нужно добавить request[] для синтаксического анализа JSON и UrlRule для связывания методов для моделей и их конечных точек:

return [
    'id' => 'app-api',
    'basePath' => dirname(__DIR__),
    'controllerNamespace' => 'api\controllers',
    'bootstrap' => ['log'],
    'modules' => [],
    'components' => [
      'request' => [
        'parsers' => [
          'application/json' => 'yii\web\JsonParser',
        ],
      ],
      'urlManager' => [
        'enablePrettyUrl' => true,
        'enableStrictParsing' => true,
        'showScriptName' => false,
        'rules' => [
          ['class' => 'yii\rest\UrlRule', 'controller' => 'item'],
          ['class' => 'yii\rest\UrlRule', 'controller' => 'user'],
        ],
      ],

Это в основном все, что требуется, чтобы включить некоторые богатые API-функции для этих моделей.

Примеры С cURL

Давайте начнем делать запросы.

Запрос OPTIONS

Покажите мне доступные методы API:

curl -i -H "Accept: application/json" 
    -X OPTIONS "http://localhost:8888/api/items"

Вот ответ (GET, POST, HEAD, OPTIONS):

HTTP/1.1 200 OK
Date: Tue, 25 Oct 2016 20:23:10 GMT
Server: Apache/2.2.31 (Unix) mod_wsgi/3.5 Python/2.7.12 PHP/7.0.10 mod_ssl/2.2.31 OpenSSL/1.0.2h DAV/2 mod_fastcgi/2.4.6 mod_perl/2.0.9 Perl/v5.24.0
X-Powered-By: PHP/7.0.10
Allow: GET, POST, HEAD, OPTIONS
Content-Length: 0
Content-Type: application/json; charset=UTF-8

Запросы GET

Запрос: сколько есть данных?

curl -i --head  "http://localhost:8888/api/items"

Ответ: 576 записей на 29 страницах ...

HTTP/1.1 200 OK
Date: Tue, 25 Oct 2016 23:17:37 GMT
Server: Apache/2.2.31 (Unix) mod_wsgi/3.5 Python/2.7.12 PHP/7.0.10 mod_ssl/2.2.31 OpenSSL/1.0.2h DAV/2 mod_fastcgi/2.4.6 mod_perl/2.0.9 Perl/v5.24.0
X-Powered-By: PHP/7.0.10
X-Pagination-Total-Count: 576
X-Pagination-Page-Count: 29
X-Pagination-Current-Page: 1
X-Pagination-Per-Page: 20
Link: <http://localhost:8888/api/items?page=1>; rel=self, <http://localhost:8888/api/items?page=2>; rel=next, <http://localhost:8888/api/items?page=29>; rel=last
Content-Type: application/json; charset=UTF-8

Запрос: Покажите мне запись 15:

curl -i  "http://localhost:8888/api/items/15"

Ответ:

HTTP/1.1 200 OK
Date: Tue, 25 Oct 2016 23:19:27 GMT
Server: Apache/2.2.31 (Unix) mod_wsgi/3.5 Python/2.7.12 PHP/7.0.10 mod_ssl/2.2.31 OpenSSL/1.0.2h DAV/2 mod_fastcgi/2.4.6 mod_perl/2.0.9 Perl/v5.24.0
X-Powered-By: PHP/7.0.10
Content-Length: 203
Content-Type: application/json; charset=UTF-8

{"id":15,"title":"Jeff Reifman","path":"jeffreifman",
"detail":"","status":0,"posted_by":1,"image_url":"",
"favorites":0,"stat_1":0,"stat_2":0,"stat_3":0,"created_at":1477277956,"updated_at":1477277956}

Запрос: Покажите мне все данные на странице 3:

curl -i -H "Accept:application/json"
    "http://localhost:8888/api/items?page=3"

Ответ:

HTTP/1.1 200 OK
Date: Tue, 25 Oct 2016 23:30:21 GMT
Server: Apache/2.2.31 (Unix) mod_wsgi/3.5 Python/2.7.12 PHP/7.0.10 mod_ssl/2.2.31 OpenSSL/1.0.2h DAV/2 mod_fastcgi/2.4.6 mod_perl/2.0.9 Perl/v5.24.0
X-Powered-By: PHP/7.0.10
X-Pagination-Total-Count: 575
X-Pagination-Page-Count: 29
X-Pagination-Current-Page: 3
X-Pagination-Per-Page: 20
Link: <http://localhost:8888/api/items?page=3>; rel=self, <http://localhost:8888/api/items?page=1>; rel=first, <http://localhost:8888/api/items?page=2>; rel=prev, <http://localhost:8888/api/items?page=4>; rel=next, <http://localhost:8888/api/items?page=29>; rel=last
Content-Length: 3999
Content-Type: application/json; charset=UTF-8

[{"id":43,"title":"_jannalynn","path":"_jannalynn",
"detail":"","status":0,"posted_by":1,"image_url":"",
"favorites":0,"stat_1":0,"stat_2":0,"stat_3":0,
...
...
...
{"id":99,"title":"alibrown","path":"alibrown","detail":"",
"status":0,"posted_by":1,"image_url":"","favorites":0,
"stat_1":0,"stat_2":0,"stat_3":0,"created_at":1477277956,
"updated_at":1477277956}]

Запросы DELETE

Ниже приведен пример запроса GET, за которым следует запрос DELETE, а затем последующая неудачная попытка GET:

$ curl -i -H "Accept: application/json" "http://localhost:8888/api/items/8"
HTTP/1.1 200 OK
Date: Tue, 25 Oct 2016 23:32:17 GMT
Server: Apache/2.2.31 (Unix) mod_wsgi/3.5 Python/2.7.12 PHP/7.0.10 mod_ssl/2.2.31 OpenSSL/1.0.2h DAV/2 mod_fastcgi/2.4.6 mod_perl/2.0.9 Perl/v5.24.0
X-Powered-By: PHP/7.0.10
Content-Length: 186
Content-Type: application/json; charset=UTF-8

{"id":8,"title":"aaker","path":"aaker","detail":"","status":0,"posted_by":1,"image_url":"","favorites":0,"stat_1":0,"stat_2":0,"stat_3":0,"created_at":1477277956,"updated_at":1477277956}

$ curl -i -H "Accept: application/json" -X DELETE "http://localhost:8888/api/items/8"
HTTP/1.1 204 No Content
Date: Tue, 25 Oct 2016 23:32:26 GMT
Server: Apache/2.2.31 (Unix) mod_wsgi/3.5 Python/2.7.12 PHP/7.0.10 mod_ssl/2.2.31 OpenSSL/1.0.2h DAV/2 mod_fastcgi/2.4.6 mod_perl/2.0.9 Perl/v5.24.0
X-Powered-By: PHP/7.0.10
Content-Length: 0
Content-Type: application/json; charset=UTF-8

$ curl -i -H "Accept: application/json" "http://localhost:8888/api/items/8"
HTTP/1.1 404 Not Found
Date: Tue, 25 Oct 2016 23:32:28 GMT
Server: Apache/2.2.31 (Unix) mod_wsgi/3.5 Python/2.7.12 PHP/7.0.10 mod_ssl/2.2.31 OpenSSL/1.0.2h DAV/2 mod_fastcgi/2.4.6 mod_perl/2.0.9 Perl/v5.24.0
X-Powered-By: PHP/7.0.10
Content-Length: 115
Content-Type: application/json; charset=UTF-8

{"name":"Not Found","message":"Object not found: 8","code":0,"status":404,"type":"yii\\web\\NotFoundHttpException"}

Запросы на удаленную запись возвращают ошибку 404.

Запросы POST

Для моих запросов на почту я переключился на приложение Chrome Postman:

Programming With Yii2 Chrome Directory Postman Extension Landing Page

Войти в Postman было легко:

И тогда я смог отправить запросы на свой localhost API в более удобном графическом интерфейсе:

Programming With Yii2 POST Request Shown in Postman UX

Затем я получил данные через curl, record 577:

$ curl -i -H "Accept: application/json" "http://localhost:8888/api/items/577"
HTTP/1.1 200 OK
Date: Tue, 25 Oct 2016 23:40:44 GMT
Server: Apache/2.2.31 (Unix) mod_wsgi/3.5 Python/2.7.12 PHP/7.0.10 mod_ssl/2.2.31 OpenSSL/1.0.2h DAV/2 mod_fastcgi/2.4.6 mod_perl/2.0.9 Perl/v5.24.0
X-Powered-By: PHP/7.0.10
Content-Length: 219
Content-Type: application/json; charset=UTF-8

{"id":577,"title":"Jeff Reifman","path":"reifman",
"detail":"A programmer on earth.","status":0,
"posted_by":1,"image_url":"","favorites":0,
"stat_1":0,"stat_2":0,"stat_3":0,"created_at":1477436477,
"updated_at":1477436477}

Postman доказал свою важность для закругления моего тестирования, поскольку зависание командной строки было непросто настроить для отправки POST.

Заглядывая вперед

В дополнение к обзору быстрого старта с REST в документации Yii 2.0 содержится подробная информация о множестве других аспектов создания API:

Я надеюсь, что у вас будет возможность изучить их в будущих эпизодах. Но, конечно, одним из следующих шагов является создание API для планировщика собраний в серии про стартап.

В заключение, создание базового REST API с фреймворком Yii довольно просто. Команда Yii сделала отличную работу по стандартизации функциональности для очень важного требования, REST API. Надеюсь, вам понравилось узнавать об этом.

Если у вас есть какие-либо вопросы или предложения, разместите их в комментариях ниже. Если вы хотите быть в курсе моих будущих учебных пособий Envato Tuts + и других сериалов, посетите мою страницу инструктора или подпишитесь на @reifman. Определенно проверьте мою серию про стартап и Планировщика встреч.

Ссылки по теме

Yii2 Developer Exchange, мой ресурсный сайт Yii2
Быстрый старт - веб-службы RESTful - полное руководство по Yii 2.0
Хранилище Google Chrome: приложение Postman