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



В этой серии Программирование с помощью 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:



Создание дерева в качестве конечной точки 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:



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



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



Затем я получил данные через 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. Определенно проверьте мою серию про стартап и Планировщика встреч.