$30 off During Our Annual Pro Sale. View Details »

API Platform

API Platform

Develop APIs - The easy way


November 23, 2017

More Decks by move:elevator

Other Decks in Programming


  1. API Platform API Driven Development - The easy way

  2. Frank Jogeleit Software developer at move:elevator

  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
  4. Agenda • Advanced Features • Extensions • Serialization Context •

    Custom Operations • Access Control • Authentication with JsonWebToken Second Part
  5. Introduction Why I am talking about APIs

  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
  7. Introduction What am I talking about?

  8. „API Platform is a next- generation web framework designed to

    easily create API-first projects without compromising extensibility and flexibility.“
  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
  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
  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
  12. Example Application Learning by doing

  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
  14. Basic Features Swagger UI, CRUD Operations, Filters, Validation

  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
  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
  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
  18. Basic Features • Filters for collection operations could be declared

    as Symfony services and have to be configured in the resource configuration Filter Configuration
  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
  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
  21. Basic Features • Set name and description as required for

    categories Validation Example
  22. Advanced Features Extensions, Serialization Context, 
 Custom Operations, Access Control

  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
  24. Advanced Features • Filter by all soft deleted products •

    Filter in collection- and item operations Extension Example
  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
  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
  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
  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
  29. Advanced Features • Custom operation to get informations about the

    authenticated user Custom Operation Example
  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
  31. Advanced Features • Restrict the Warehouse API to Admins

 • Restrict the Current User API for authenticated requests Access Control Example
  32. Authentication with JsonWebToken

  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
  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
  35. Symfony Implementation • Install via Composer
 • Create certificates

 • Configure routing LexikJWTAuthenticationBundle
  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
  37. Questions?

  38. 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