Создание и использование RESTful API в Laravel

Что такое API?

API – это Application Programming Interface, это описание способов которыми одна компьютерная программа может взаимодействовать с другой программой.

Оригинал статьи

Что такое REST?

REST – это аббревиатура от REpresentational State Transfer. Этот термин был придуман Роем Филдингом в 2000 году. Это стиль архитектуры для проектирования слабо связанных приложений по протоколу HTTP, который часто используется при разработке веб-сервисов.

REST определяет 6 архитектурных ограничений, которые делают любой веб-сервис истинным RESTful API.

1. Client-server – отделяя пользовательский интерфейс от хранилища данных, мы улучшаем переносимость пользовательского интерфейса на несколько платформ и улучшаем масштабируемость за счет упрощения серверных компонентов.
2. Stateless – каждый запрос от клиента к серверу должен содержать всю информацию, необходимую для понимания запроса, и не может использовать преимущества любого сохраненного контекста на сервере. Таким образом, состояние сеанса полностью сохраняется на клиенте.
3. Cacheable – ограничения кэша требуют, чтобы данные в ответе на запрос были неявно или явно помечены как cacheable или non-cacheable. Если ответ кэшируется, то клиентскому кэшу предоставляется право повторно использовать эти данные ответа для последующих эквивалентных запросов.
4. Uniform interface – применяя принцип общности к компонентному интерфейсу, упрощается общая архитектура системы и улучшается видимость взаимодействий.
5. Layered system – стиль слоистой системы позволяет архитектуре состоять из иерархических слоев, ограничивая поведение компонентов таким образом, что каждый компонент не может “видеть” за пределами непосредственного слоя, с которым они взаимодействуют.
6. Code on demand (необязательно) – REST позволяет расширить функциональность клиента, загрузив и выполнив код в виде апплетов или скриптов. Это упрощает работу с клиентами за счет сокращения количества функций, необходимых для предварительной реализации.

Теперь давайте перейдем к созданию и использованию RESTful API в Laravel.

Потребители нашего API смогут выполнять несколько ограниченных задач. Там будут следующие конечные точки:

Конечные точки API для неаутентифицированного маршрута

Связанные с категорией:

• Получить все категории GET /categories
• Получить все сообщения категории GET /categories/{id}/posts

Связанные с сообщениями:

• Получить все сообщения GET /posts
• Получить сообщение по ID GET /posts/{id}
• Получить все комментарии к сообщению GET /posts/{id}/comments

Связанные с автором:

• Получить подробную информацию об авторе GET /authors/{id}
• Получить все сообщения от автора GET /authors/posts
• Получить все комментарии автора GET /authors/{id}/comments

Связано с тегом:

• Получить все сообщения тега GET /tags/{id}/posts

Конечная точка API для аутентифицированного маршрута

Связанные с комментарием:

• Комментарий пользователя магазина POST /comments/posts/{id}

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

Шаг 1: Давайте сначала создадим ресурсы API. Для этого выполните следующие действия:

При построении API вам может понадобиться слой преобразования, который находится между вашими Eloquent моделями и ответами JSON, которые фактически возвращаются пользователям вашего приложения. Классы ресурсов Laravel позволяют вам выразительно и легко преобразовывать ваши модели и коллекции моделей в JSON.

Выполните команду 

php artisan make:resource CategoryResource. 

Она создаст CategoryResource в app\Http\Resources каталоге.

Откройте этот файл и верните нужные данные, например. category_id на месте id. Вы можете сделать гораздо больше, чем просто маскировать имена полей или количество полей, которые должны быть возвращены, например – мы можем возвращать дополнительную информацию с помощью API и т. д.

public function toArray($request)
{
 return [
  'category_id' => $this->id,
  'category_title' => $this->title,
  'category_color' => $this->color,
 ];
}
// (Optional) Additional code is attached to the response
public function with($request){
 return [
  'version' => "1.0.0",
  'author_url' => "https://maxyc.ru"
 ];
}

Таким же образом вы должны создать и другие необходимые ресурсы—CommentResource, PostResource, TagResource, UserResource, ImageResource и VideoResource.

Шаг 2: Следующее действие заключается в создании необходимых контроллеров. Для этого выполните следующие действия:

Выполните команду 

php artisan make:controller Api\\CategoryApiController. 

Она создаст CategoryApiController в app\Http\Controllers\Api каталоге. Откройте этот файл и запишите методы для выполнения действий.

public function index()
{
 $categories = Category::all();
 return CategoryResource::collection($categories);
}

public function posts($id)
{
 $posts = Post::where('category_id', $id)->orderBy('id', 'desc')->paginate();
 return PostResource::collection($posts);
}

Здесь вы создали два метода index и posts внутри CategoryApiController.

index Метод вернет все категории, завернутые внутрь CategoryResource.

posts Метод вернет все записи, принадлежащие к определенной категории, завернутые внутрь PostResource.

Таким же образом создайте нужные методы в CommentApiController, PostApiController, TagApiController и UserApiController.

Шаг 3: Последний шаг-создание маршрутов для API. Перейдите в routes каталог, откройте api.php файл и создайте конечные точки API, которые будут ссылаться на методы, созданные в CategoryApiController, CommentApiController, PostApiController, TagApiController и UserApiController

<?php
use App\Http\Controllers\Api\CategoryApiController;
use App\Http\Controllers\Api\CommentApiController;
use App\Http\Controllers\Api\PostApiController;
use App\Http\Controllers\Api\UserApiController;
use Illuminate\Support\Facades\Route;
Route::get('authors/{id}', [UserApiController::class, 'show']);
Route::get('authors/{id}/posts', [UserApiController::class, 'posts']);
Route::get('authors/{id}/comments', [UserApiController::class, 'comments']);
Route::get('categories', [CategoryApiController::class, 'index']);
Route::get('categories/{id}/posts', [CategoryApiController::class, 'posts']);
Route::get('posts', [PostApiController::class, 'index']);
Route::get('posts/{id}', [PostApiController::class, 'show']);
Route::get('posts/{id}/comments', [PostApiController::class, 'comments']);
Route::get('tags/{id}/posts', [TagApiController::class, 'posts']);
Route::middleware('auth:sanctum')->group(function () {
Route::post('comments/posts', [CommentApiController::class, 'store']);
});

Тестирование конечных точек API

Запустите базу данных и выполните php artisan serve. Сервер разработки Laravel запустится на http://127.0.0.1:8000

Откройте Postman и протестируйте все маршруты, определенные в api.php, но обязательно добавьте свой маршрут в неймспейс /api/

Чтобы получить все категории вы должны отправить GET запрос по адресу http://127.0.0.1:8000/api/categories

Теперь давайте тоже проверим authenticated route. Существует только один аутентифицированный маршрут для хранения вошедшего пользователя.

Мы используем Laravel Sanctum для аутентификации и авторизации. Мы выпустим токен API и используем его в Postman для аутентификации запроса.

Laravel Sanctum предоставляет легкую систему аутентификации для SPAs (одностраничных приложений), мобильных приложений и простых API на основе токенов. Sanctum позволяет каждому пользователю вашего приложения генерировать несколько токенов API для своей учетной записи. Этим токенам могут быть предоставлены способности / области действия, которые определяют, какие действия токены могут выполнять.

Чтобы использовать токен API, мы запустим команду tinker

php artisan tinker

Теперь он позволит нам взаимодействовать с приложением Laravel из командной строки. Здесь вам нужно создать токен API для пользователя, используя метод createToken().

Копируем plainTextToken, предназначенная для использования в Postman.

Теперь откройте Postman и сделайте следующее:

• Новый POST запрос к http://127.0.0.1:8000/api/comments/posts
• На Authorization вкладке выберите Type как Bearer Token и вставьте plainTextToken в текстовое поле.
• Затем во вкладке Headers укажите Accept в значении application/json.
• Затем на вкладке Body выберите form-data и укажите данные для отправки: id 159, comment "Testing some comment on post 159“
• Теперь нажмите кнопку send и вы получите обратно только что созданный комментарий.

В этой статье мы смогли построить и использовать (потребитель был Postman) RESTful API с помощью Laravel. Мы рассмотрели создание ресурсов API, создание контроллера API и протестировали аутентифицированные и Неаутентифицированные маршруты API.

• Исходный код доступен на Github.
• Твиттер: котагин
• GitHub: mdutt247
• Электронная почта: m.dutt@mditech.net