rest-quick-start.md 9.26 KB
Newer Older
githubjeka committed
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20
Быстрый старт
===========

Yii включает полноценный набор средств для упрощённой реализации [RESTful API](https://ru.wikipedia.org/wiki/REST).
В частности это следующие возможности:

* Быстрое создание прототипов с поддержкой распространенных API к [Active Record](db-active-record.md);
* Настройка формата ответа (JSON и XML реализованы по-умолчанию);
* Получение сериализованных объектов с нужной вам выборкой полей;
* Надлежащее форматирование данных и ошибок при их валидации;
* Поддержка [HATEOAS](http://en.wikipedia.org/wiki/HATEOAS);
* Эффективная маршрутизация с надлежащей проверкой HTTP методов;
* Встроенная поддержка методов `OPTIONS` и `HEAD`;
* Аутентификация и авторизация;
* HTTP кэширование и кэширование данных;
* Настройка ограничения для частоты запросов (Rate limiting);


Рассмотрим пример, как можно настроить Yii под RESTful API, приложив при этом минимум усилий.

21 22
Предположим, вы захотели RESTful API для данных по пользователям. Эти данные хранятся в базе данных и для работы с ними
вами была ранее создана модель [[yii\db\ActiveRecord|ActiveRecord]]  (класс `app\models\User`).
githubjeka committed
23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39


## Создание контроллера <a name="creating-controller"></a>

Во-первых, создадим класс контроллера `app\controllers\UserController`:

```php
namespace app\controllers;

use yii\rest\ActiveController;

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

40 41 42
Класс контроллера наследуется от [[yii\rest\ActiveController]]. Мы задали [[yii\rest\ActiveController::modelClass|modelClass]]
как `app\models\User`, тем самым указав контроллеру, к какой модели ему необходимо обращаться для редактирования или
выборки данных.
githubjeka committed
43 44


45
## Настройка правил URL <a name="configuring-url-rules"></a>
githubjeka committed
46

47
Далее изменим настройки компонента `urlManager` в конфигурации приложения:
githubjeka committed
48 49 50 51 52 53 54 55 56 57 58 59

```php
'urlManager' => [
    'enablePrettyUrl' => true,
    'enableStrictParsing' => true,
    'showScriptName' => false,
    'rules' => [
        ['class' => 'yii\rest\UrlRule', 'controller' => 'user'],
    ],
]
```

60 61 62
Настройки выше добавляет правило для контроллера `user`, которое предоставляет доступ к данным пользователя через красивые
URL и логичные глаголы HTTP.

githubjeka committed
63 64
## Пробуем <a name="trying-it-out"></a>

65
Вот так просто мы и создали RESTful API для доступа к данным пользователя. Api нашего сервиса, сейчас включает в себя:
githubjeka committed
66 67 68 69 70 71 72 73 74 75 76

* `GET /users`: получение постранично списка всех пользователей;
* `HEAD /users`: получение метаданных листинга пользователей;
* `POST /users`: создание нового пользователя;
* `GET /users/123`: получение информации по конкретному пользователю с id равным 123;
* `HEAD /users/123`: получение метаданных по конкретному пользователю с id равным 123;
* `PATCH /users/123` и `PUT /users/123`: изменение информации по пользователю с id равным 123;
* `DELETE /users/123`: удаление пользователя с id равным 123;
* `OPTIONS /users`: получение поддерживаемых методов, по которым можно обратится к `/users`;
* `OPTIONS /users/123`: получение поддерживаемых методов, по которым можно обратится к `/users/123`.

77
> Информация: Yii автоматически использует множественное число от имени контроллера в URL.
githubjeka committed
78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144

Пробуем получить ответы по API используя `curl`: 

```
$ curl -i -H "Accept:application/json" "http://localhost/users"

HTTP/1.1 200 OK
Date: Sun, 02 Mar 2014 05:31:43 GMT
Server: Apache/2.2.26 (Unix) DAV/2 PHP/5.4.20 mod_ssl/2.2.26 OpenSSL/0.9.8y
X-Powered-By: PHP/5.4.20
X-Pagination-Total-Count: 1000
X-Pagination-Page-Count: 50
X-Pagination-Current-Page: 1
X-Pagination-Per-Page: 20
Link: <http://localhost/users?page=1>; rel=self, 
      <http://localhost/users?page=2>; rel=next, 
      <http://localhost/users?page=50>; rel=last
Transfer-Encoding: chunked
Content-Type: application/json; charset=UTF-8

[
    {
        "id": 1,
        ...
    },
    {
        "id": 2,
        ...
    },
    ...
]
```

Попробуйте изменить заголовок допустимого формата ресурса на `application/xml`
и в ответ вы получите результат в формате XML:

```
$ curl -i -H "Accept:application/xml" "http://localhost/users"

HTTP/1.1 200 OK
Date: Sun, 02 Mar 2014 05:31:43 GMT
Server: Apache/2.2.26 (Unix) DAV/2 PHP/5.4.20 mod_ssl/2.2.26 OpenSSL/0.9.8y
X-Powered-By: PHP/5.4.20
X-Pagination-Total-Count: 1000
X-Pagination-Page-Count: 50
X-Pagination-Current-Page: 1
X-Pagination-Per-Page: 20
Link: <http://localhost/users?page=1>; rel=self, 
      <http://localhost/users?page=2>; rel=next, 
      <http://localhost/users?page=50>; rel=last
Transfer-Encoding: chunked
Content-Type: application/xml

<?xml version="1.0" encoding="UTF-8"?>
<response>
    <item>
        <id>1</id>
        ...
    </item>
    <item>
        <id>2</id>
        ...
    </item>
    ...
</response>
```

145 146
> Подсказка: Вы можете получить доступ к API через веб-браузер, введя адрес `http://localhost/users`. Но в этом случае,
  для передачи определённых заголовков вам, скорее всего, потребуются дополнительные плагины для браузера.
githubjeka committed
147

148 149 150
Если внимательно посмотреть результат ответа, то можно обнаружить, что в заголовках есть информация об общем числе записей,
количестве страниц и т.д. Тут так же можно обнаружить ссылки на другие страницы, как, например,
`http://localhost/users?page=2`. Перейдя по ней можно получить вторую страницу данных пользователей.
githubjeka committed
151

152 153 154
Используя параметры `fields` и `expand` в URL, можно указать, какие поля должны быть включены в результат. Например,
по адресу `http://localhost/users?fields=id,email` мы получим информацию по пользователям, которая будет содержать
только `id` и `email`.
githubjeka committed
155 156


157 158 159
> Информация: Вы наверное заметили, что при обращении к `http://localhost/users` мы получаем информацию с полями,
> которые нежелательно показывать, такими как `password_hash` и `auth_key`. Вы можете и должны отфильтровать их как
> описано в разделе «[Форматирование ответа](rest-response-formatting.md)».
githubjeka committed
160 161 162 163


## Резюме <a name="summary"></a>

164 165
Используя Yii в качестве RESTful API фреймворка, мы используем реализуем точки входа API как действия контроллеров.
Контроллер используется для организации действий, которые относятся к определённому типу ресурса.
githubjeka committed
166 167

Ресурсы представлены в виде моделей данных, которые наследуются от класса [[yii\base\Model]].
168 169
Если необходима работа с базами данных (как с реляционными, так и с NoSQL), рекомендуется использовать для представления
ресурсов [[yii\db\ActiveRecord|ActiveRecord]].
githubjeka committed
170

171
Вы можете использовать [[yii\rest\UrlRule]] для упрощения маршрутизации точек входа API.
githubjeka committed
172

173 174
Хоть это не обязательно, рекомендуется отделять RESTful APIs приложение от основного веб-приложения. Такое разделение
легче обслуживается.