Upgrade to Pro — share decks privately, control downloads, hide ads and more …

API Platform

API Platform

Develop APIs - The easy way

move:elevator

November 23, 2017
Tweet

More Decks by move:elevator

Other Decks in Programming

Transcript

  1. API Platform
    API Driven Development - The easy way

    View full-size slide

  2. Frank Jogeleit
    Software developer at move:elevator

    View full-size slide

  3. Agenda
    • Introduction
    • Why I am talking about APIs
    • What am I talking about?
    • Example Application
    • Basic Features
    • Swagger UI
    • CRUD Operations
    • Filters
    • Validation
    First Part

    View full-size slide

  4. Agenda
    • Advanced Features
    • Extensions
    • Serialization Context
    • Custom Operations
    • Access Control
    • Authentication with JsonWebToken
    Second Part

    View full-size slide

  5. Introduction
    Why I am talking about APIs

    View full-size slide

  6. Why I am talking about APIs
    The Web is growing and changing every day
    • More and more web-based applications are 

    single page applications
    • Big applications are splitting into micro services
    • Applications have to communicate with other external
    applications
    The need of API driven (PHP) Projects is

    growing every day

    View full-size slide

  7. Introduction
    What am I talking about?

    View full-size slide

  8. „API Platform is a next-
    generation web framework
    designed to easily create API-first
    projects without compromising
    extensibility and flexibility.“

    View full-size slide

  9. API Platform
    • API driven Project on top of Symfony
    • Requires Doctrine ORM for database interactions
    • Define your API endpoints with minimal configuration
    • Supports different API Formats like 

    GraphQL, JSON-LD, JSON, XML and many more
    • Auto generated API documentation with Swagger UI
    • Supports testing with an API testing tool on top of Behat
    • Detailed documentation: https://api-platform.com
    Description

    View full-size slide

  10. API Platform
    The default way of creating a new API Platform using Composer:
    • You get an preconfigured Symfony installation with the API
    Platform dependencies and configurations to get started
    The alternative way is using the symfony-flex recipe in a new or
    existing Symfony Flex project (more about symfony flex in the
    upcoming PHPDD UG talk)
    • You get all needed dependencies and configurations to get started
    Installation

    View full-size slide

  11. API Platform
    • API Platform models have to be configured as a
    resource
    • API Platform supports YAML-, XML- and Annotation
    based configuration
    • The minimal configuration is:



    • it creates the basic CRUD Operations
    • adds the model in the Swagger UI
    Basic Configuration

    View full-size slide

  12. Example Application
    Learning by doing

    View full-size slide

  13. Learning by Doing
    • YAML based configuration
    • Configuration examples of: API Platform, Validation,
    Serialization, Doctrine Entities
    • Includes Authorization, Custom Operations, Extensions,
    Relation-Handling and subresources
    https://github.com/fjogeleit/api-platform-example

    View full-size slide

  14. Basic Features
    Swagger UI, CRUD Operations, Filters, Validation

    View full-size slide

  15. Basic Features
    • Auto generated API documentation including operation
    description, expected request (structure), configured
    response at success or error
    • Sandbox functionality to execute and test your API
    endpoints
    • Overview of defined models and serialization groups
    Swagger UI

    View full-size slide

  16. Basic Features
    • Default Endpoints per Model
    • GET: [/models] paginated list, 30 items per page
    • POST: [/models] create new model
    • return the new entry
    • GET: [/models/{id}] single model representation
    • PUT: [/models/{id}] replace/update model
    • return the updated model
    • DELETE: [/models/{id}] delete the model
    CRUD Operations

    View full-size slide

  17. Basic Features
    • If you explicitly configure the operations of your model,
    all operations you don’t configure are disabled
    • If your model has relations, you can configure them as
    sub-resources to generate endpoints for these relations
    CRUD Operations

    View full-size slide

  18. Basic Features
    • Filters for collection operations could be declared as
    Symfony services and have to be configured in the
    resource configuration
    Filter Configuration

    View full-size slide

  19. Basic Features
    • Different types of filters:
    • SearchFilter - Searching for exact or partial
    accordance (conforms with MySQL LIKE Operation)
    • DateFilter - Searching values in Date(Time) Intervals
    • BooleanFilter - Searching by bool values
    • NumericFilter - Searching by numeric values
    • RangeFilter - Search Numeric values in Numeric
    ranges like greater than, lower than or between
    • OrderFilter - Allow Sorting
    Available Filter

    View full-size slide

  20. Basic Features
    • API Validation uses the Symfony Validation Component
    • configuration same as default Symfony projects
    • available Formats are YAML, XML, Annotations
    • Validation has to be activated 

    in the framework configuration
    • Required fields are marked in the Swagger UI
    Validation

    View full-size slide

  21. Basic Features
    • Set name and description as required for categories
    Validation Example

    View full-size slide

  22. Advanced Features
    Extensions, Serialization Context, 

    Custom Operations, Access Control

    View full-size slide

  23. Advanced Features
    • Extensions are simple PHP classes using different
    interfaces for extending collection or item based
    operations. Extensions are configured as Symfony
    services
    • It allows you to add global filters or dynamic filters
    depending on user roles or something like that
    • A single extension is globally defined, 

    for every model. The query context is

    part of the executed method arguments
    Extensions

    View full-size slide

  24. Advanced Features
    • Filter by all soft deleted products
    • Filter in collection- and item operations
    Extension Example

    View full-size slide

  25. Advanced Features
    • By default all fields of your model are serialized and in
    the response of your GET requests
    • By default it is also possible to set or overwrite every
    field of model in POST or PUT requests
    • With serialization groups you can change this.
    • You can create and configure serializer groups for
    normalization (GET requests) and denormalization
    (PUT-, POST-, PATCH requests)
    • The configuration can be set per model or restricted
    for a single operation
    Serializer Context

    View full-size slide

  26. Advanced Features
    • serialization groups allow you to create relations in the
    same post request of your main model, it also allows
    API Platform to return embedded relation fields in GET
    requests
    • To create serialization groups, use the 

    Symfony Serializer Component
    • You have to enable this feature and can use YAML, XML
    or Annotations for configuration
    Serializer Context

    View full-size slide

  27. Advanced Features
    • Return different fields in collection and item GET request.
    • remove unused fields in both operations
    • remove unused fields from the list operation
    Serializer Context Example

    View full-size slide

  28. Advanced Features
    • You can create your own operations (actions) and add them to
    your API model
    • You can create custom collection operations. These operations
    have no single model (pre selected by ID) as context. The path
    of this operation has no ID parameter.

    (Like POST: /categories)
    • You can also create custom item operations. These operations
    have a single model as argument, selected by the required ID
    parameter. (LIKE PUT /categories/{id})
    • The Response of these operations can be an array, a single
    model, a collection of models or a Response object
    Custom Operations

    View full-size slide

  29. Advanced Features
    • Custom operation to get informations about the authenticated user
    Custom Operation Example

    View full-size slide

  30. Advanced Features
    • Restrict the access of routes or route patterns with the
    Symfony Security Component and the access control list
    • Alternatively you can restrict the access of single operations by
    using the access_control configuration from API Platform
    • It allows restriction by user roles with is_granted(ROLE)
    • Dynamic string based expressions using the Symfony
    ExpressionLanguage Component
    Access Control

    View full-size slide

  31. Advanced Features
    • Restrict the Warehouse API to Admins



    • Restrict the Current User API for authenticated requests
    Access Control Example

    View full-size slide

  32. Authentication
    with JsonWebToken

    View full-size slide

  33. JsonWebToken
    • JsonWebToken (JWT) is an API based authentication
    like OAuth
    • Your API provides a login endpoint to generate your
    token
    • This endpoint requires valid user credentials (username
    and password)
    • If the login is successful you get a valid json response
    with your auth-token
    • To send authenticated requests send this token with the
    Bearer Prefix as Authorization header in your request
    • Finish
    How it works

    View full-size slide

  34. Symfony Implementation
    • Symfony Implementation for JWT
    • Well supported by API Platform
    • Provide a Community Recipe for Symfony Flex
    • Easy to configure and use
    • Requires a configured User Provider
    • self configured with the EntityProvider (recommended)
    • using Bundles like the FOSUserBundle
    LexikJWTAuthenticationBundle

    View full-size slide

  35. Symfony Implementation
    • Install via Composer


    • Create certificates



    • Configure routing
    LexikJWTAuthenticationBundle

    View full-size slide

  36. Symfony Implementation
    • Configure the Firewall











    That’s it. The full example, including User Entity and
    Provider can be found in the example application
    LexikJWTAuthenticationBundle

    View full-size slide

  37. Resources
    • API Platform Documentation: 

    https://api-platform.com/
    • Github: LexikJWTAuthenticationBundle:

    https://github.com/lexik/LexikJWTAuthenticationBundle
    • Symfony Entity Provider:

    https://symfony.com/doc/current/security/entity_provider.html
    • API Platform Example:

    https://github.com/fjogeleit/api-platform-example
    Content Resources

    View full-size slide