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

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


  1. Устанавливаем проект при помощи Composer
    composer create-project api-platform/api-platform blog-api
    

  2. Убираем дефолтную демку
    1. Очищаем файлы app/config/schema.yml и app/config/services.yml
    2. удаляем все файлы в src/AppBundle/Entity

  3. Создание модели данных
    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: {} 
      


  4. Генерируем классы, получаем бесплатно:

    • документация полей берется с schema.org и переводится в PHPDoc
    • аннотации Doctrine ORM
    • аннотации валидации Symfony
    • аннотации Iri необходимы для выявления семантической (смысловой) структуры данных
    • совместимость с PSR-2 coding style


    bin/schema generate-types src/ app/config/schema.yml
    


  5. Создаем базу данных
    app/console doctrine:database:create
    

  6. И схему наших моделей
    app/console doctrine:schema:create
    

    Генерация моделей из схем поддерживается не только фреймворком Api-platform, но и простым PHP, потому что можно использовать schema bundle самостоятельно.
  7. Создаем 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" } ]
    
    


    Voila! Наше Api готово к использованию
  8. Проверка

    app/console server:start
    

    localhost:8000/doc
    image

    Для удобной работы с 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:

Комментарии (3)


  1. kix
    27.10.2015 17:43

    Как-то можно избавиться от ограничений schema.org и реализовать свою собственную, не знаете? Когда сразу после релиза попробовал пользоваться ApiBundle, понял, что как-то не хочется тратить время на поиск схем, которые к тому же потом придется дотачивать до своих нужд в любом случае.


    1. Strate
      28.10.2015 10:23
      +2

      Описываете сущности доктрины и всё. Завязка на schem.org — это по сути генерация тех же сущностей в автоматическом режиме.

      Sometimes we will have to make a data model with very specific business types, not available in Schema.org. Sometimes we will find Schema.org types that partially matches what we want but needs to be adapted.

      Keep in mind that you can always create your very own data model from scratch. It’s perfectly OK and you can still use API Platform without PHP Schema.

      Anyway, PHP Schema is a tool intended to bootstrap the data model. You can and you will edit manually generated PHP entities. When you start to edit manually the generated files, be careful to not run the generator again, it will overwrite your changes (this behavior will be enhanced in future versions). When you do such things, the best to do is to remove dunglas/php-schema from your composer.json file.


    1. StormGuard
      30.10.2015 08:40

      1. Strate приводит хорошую выдержку из доков, от себя добавлю, что в сущностях schema.org очень строгих ограничений нет и в конфигурационном файле при описании необходимых полей, можно заменять тип поля
      2. Если Вы говорите про собственные схемы сущностей, то это вполне возможно. Главное чтобы разметка была как в schema.org. В документации есть пара слов Custom schemas, но нет пошагового объяснения и придется ближе познакомиться с RDFa и механизмами расширения schema.org.