API Platform

API Platform

Develop APIs - The easy way



November 23, 2017


  1. 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
  2. 4.

    Agenda • Advanced Features • Extensions • Serialization Context •

    Custom Operations • Access Control • Authentication with JsonWebToken Second Part
  3. 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
  4. 8.

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

    easily create API-first projects without compromising extensibility and flexibility.“
  5. 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
  6. 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
  7. 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
  8. 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
  9. 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
  10. 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
  11. 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
  12. 18.

    Basic Features • Filters for collection operations could be declared

    as Symfony services and have to be configured in the resource configuration Filter Configuration
  13. 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
  14. 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
  15. 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
  16. 24.

    Advanced Features • Filter by all soft deleted products •

    Filter in collection- and item operations Extension Example
  17. 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
  18. 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
  19. 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
  20. 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
  21. 29.

    Advanced Features • Custom operation to get informations about the

    authenticated user Custom Operation Example
  22. 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
  23. 31.

    Advanced Features • Restrict the Warehouse API to Admins

 • Restrict the Current User API for authenticated requests Access Control Example
  24. 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
  25. 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
  26. 35.

    Symfony Implementation • Install via Composer
 • Create certificates

 • Configure routing LexikJWTAuthenticationBundle
  27. 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
  28. 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