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
moveelevator
hpgrahsl
akitotsukahara
beberlei
pyama86
kdubois
syumai
danilop
cer
utgwkk
yuzuy
ledsun
ivargrimstad
samlambert
kevinliebholz
reverentgeek
chriscoyier
samanthasiow
jcasabona
holman
akmur
paulrobertlloyd
shpigford
lauravandoore
3n