API Platform

Develop APIs - The easy way

Transcript

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