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
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
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
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
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
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
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
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
Basic Features • Filters for collection operations could be declared as Symfony services and have to be configured in the resource configuration Filter Configuration
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
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
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
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
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
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
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
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
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
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