StormGuard Oct 27 2015 at 11:32

Api-platform

3 min

24K

Tutorial

С приближением Web 3.0 все активнее начинают использоваться подходы API first и Linked Data (или что-то вроде Sematic Web). В связи с этим читателям предлагается познакомиться с фреймворком для удобного создания API на базе схем собранных на schema.org с генерацией ответов в виде JSON-LD,

Это укороченная версия туториала Api-platform

Устанавливаем проект при помощи Composer
```
composer create-project api-platform/api-platform blog-api
```
Убираем дефолтную демку
1. Очищаем файлы app/config/schema.yml и app/config/services.yml
2. удаляем все файлы в src/AppBundle/Entity
Создание модели данных
1. Api-platform содержит генератор моделей из словаря schema.org
2. Идем на сайт и находим схему, которая описывает то, что нам нужно. В данном случае schema.org/BlogPosting
3. Теперь надо создать конфигурационный файл app/config/schema.yml. В нем укажем в каком неймспейсе создавать типы, какие типы создавать и какие поля нам нужны (потому что на сайте Schema.org (http://schema.org/) представлены наиболее полные схемы сущностей и обычно нам необходимо только некоторое подмножество описанных полей). Кроме того есть возможность описания связей между сущностями.
```
# app/config/schema.yml
 
annotationGenerators:
    - ApiPlatform\SchemaGenerator\AnnotationGenerator\PhpDocAnnotationGenerator
    - ApiPlatform\SchemaGenerator\AnnotationGenerator\DoctrineOrmAnnotationGenerator
    - ApiPlatform\SchemaGenerator\AnnotationGenerator\ConstraintAnnotationGenerator
    - ApiPlatform\SchemaGenerator\AnnotationGenerator\DunglasApiAnnotationGenerator
namespaces:
  entity: AppBundle\Entity 
types:
  SocialMediaPosting: ~
  BlogPosting: ~ 
  Article: 
    properties: 
      articleBody: ~
      articleSection: ~
  CreativeWork:
    properties:
      author:
        range: Person
        cardinality: (*..0)
      headline: ~
      isFamilyFriendly: ~
      datePublished: ~
  Thing:
    properties:
      name: ~
  Person:
    properties: {} 
```
Генерируем классы, получаем бесплатно:
- документация полей берется с schema.org и переводится в PHPDoc
- аннотации Doctrine ORM
- аннотации валидации Symfony
- аннотации Iri необходимы для выявления семантической (смысловой) структуры данных
- совместимость с PSR-2 coding style
```
bin/schema generate-types src/ app/config/schema.yml
```
Создаем базу данных
```
app/console doctrine:database:create
```
И схему наших моделей
```
app/console doctrine:schema:create
```
Генерация моделей из схем поддерживается не только фреймворком Api-platform, но и простым PHP, потому что можно использовать schema bundle самостоятельно.
Создаем API
Этим занимается непосредственно ApiBundle. Достаточно лишь указать, что мы хотим выставить в качестве API в виде сервисов Symfony
В данном руководстве это будут классы BlogPosting и Person
```
# app/config/services.yml
 
services:
    resource.blog_posting:
        parent:    "api.resource"
        arguments: [ "AppBundle\\Entity\\BlogPosting" ]
        tags:      [ { name: "api.resource" } ]
 
    resource.person:
        parent:    "api.resource"
        arguments: [ "AppBundle\\Entity\\Person" ]
        tags:      [ { name: "api.resource" } ]
```
Voilà! Наше Api готово к использованию

Проверка

app/console server:start

localhost:8000/doc

Для удобной работы с API можно использовать Postman (его расширение для Google Chrome) www.getpostman.com

Запрашиваем список авторов

Добавляем автора

Добавляем статью:

Запрашиваем список:

Проверяем валидацию. Поле isFamilyFriendly должно быть Boolean.

{
    "name": "API Platform is great",
    "headline": "You'll love that framework!",
    "articleBody": "The body of my article.",
    "articleSection": "technology",
    "author": "/people/1",
    "isFamilyFriendly": "maybe",
    "datePublished": "2015-05-11"
}

И об этом нам сообщается таким образом:

{
    "@context": "/contexts/ConstraintViolationList",
    "@type": "ConstraintViolationList",
    "hydra:title": "An error occurred",
    "hydra:description": "isFamilyFriendly: This value should be of type boolean.\n",
    "violations": [
        {
            "propertyPath": "isFamilyFriendly",
            "message": "This value should be of type boolean."
        }
    ]
}

Исправляем:

{
    "name": "API Platform is great",
    "headline": "You'll love that framework!",
    "articleBody": "The body of my article.",
    "articleSection": "technology",
    "author": "/people/1",
    "isFamilyFriendly": true,  
    "datePublished": "2015-05-11"
}

И статья должна успешно добавиться.

Вот еще список различных возможностей главного компонента API-platform — ApiBundle:

Tags:

Hubs: