Download the PHP package requestum/symfony-api-edition without Composer

Docs

/api/doc

Authentication

Api uses OAuth2 authentication. To authenticate your request add "Authorization" header with value "Bearer access_token"

Fixtures

User 1\ username: [email protected]\ password: 123

User 2\ username: [email protected]\ password: 123

Access Tokens: Access_Token_For_Artur, Access_Token_For_Kirill

Basic concepts

This bundle provides ready to use action classes for standard REST API operations such as create, update, delete, list and transit. It uses class per action approach, so each action type has it's own class. Also this bundle utilizes concept of having many services (i.e. class instances) per one action class.

Imagine we have 3 endpoints that provide a list of resources. ` Each of these endpoints has same business logic and can be covered by the same code. We have to query database, apply some filters, pagination and sorting. Then we have to prepare result data, serialize it and send back to the client. The only difference here is that we have different resource entity repository for each endpoint. Also these almost same endpoints can have different values for some parameters such as available filters, default page size, etc. So the idea is to have unified parametrized list action class, and instantiate it three times with different arguments. For more flexibility in parametrization we use Symfony OptionResolver component. So each action class has a set of options to configure concrete endpoint.

Under the hood

This bundle consist of next components:

1. Resource metadata factory
2. Serializer extension with next features
   • expand of entity relations on demand
   • access control per field during serialization
3. Event listeners that handle frequent use cases in api development
   • json decoder that populates HttpFoundation request object's request parameter bag with passed data
   • exception listener that formats errors
4. Error factory
5. Base class for voters that vote on concrete resource entity
6. Action classes

Action classes

• List
• Fetch
• Create
• Update

• Delete

  Create operation

List action

Get list of items. \ Object type: collection \ HTTP method: GET

Configuration

1 Add service. Example:

Where: \ arguments: ... - required arguments to the Requestum\ApiBundle\Action\ListAction class constructor \ - MyProject\MyBundle\Entity\Сountry - entity class (required) \ ['setOptions', ...] - array of options

2 Add service to routing. Example:

Available Options

Filters

Query filter\ Available text search in some fields (). Supports wildcards (, , ) \ To add fields you need to edit the method in the entity repository. \ Add a filter using option. \ Example:

Sample query with filter:

You can specify particular fields you want to search in (from list you passed to SearchHandler).

Sorting \ One may add the property name and sort order to the request (pattern: 'field|order') to sort. Example:

Filter by properties \ Such filtering by entity is available:

• exact matching (Example: );
• using comparison operators (`` etc.) and , ,
  (Example: )

To change the filtering logic by association entities or existing filters, one may to make changes to the method in the entity repository. Example:

Custom filter \ To create custom filters one need: \ 1 Add new Handler. Example:

2 Add handler to item repository. Example:

3 Add custom filter to service. Example:

Additional functionality

Pagination

Pagerfanta is used for pagination and works with DoctrineORM query objects only. \ ApiBundle pagination configured with default options and (This setting can be changed in options). \ One use pagination add and to the request.\ Example:

Count only

To get the count of query results only one may add to the request attributes. Add to routing configuration as an example:

Expand

One can use the related entity references instead of full value in the response (can be expanded on demand) by adding annotation to entity property, for example:

Add to the request for expand reference. For multiple references expansion according fields should be separated be commas(NB: no spaces needs here!). One use the point for expand the field in associated entity. \ Example:

Request example

Response example

Fetch action

Get single item by identifier. \ Object type: item \ HTTP method: GET

Configuration

1 Add service. Example:

Where: \ arguments: ... - required arguments to the Requestum\ApiBundle\Action\FetchAction class constructor \ - MyProject\MyBundle\Entity\Сountry - entity class (required) \ ['setOptions', ...] - array of options

2 Add service to routing. Example:

Available Options

Access attribute

Symfony Voters are used for check the user's access permissions. AccessDecisionManager will receive value of access_attribute as $attribute and entity as subject. \ Bundle provides the base class AbstractEntityVoter, which checks the user in the session depending on the received parameter $userRequired (optional, true by default). It easy to use with the following settings for access_decision_manager:

Also the bundle has a OwnerVoter class that working with [update, delete] attributes. It uses the Symfony PropertyAccess Component for check the current user's relationship (is the owner) to the subject entity. The relationships checked by $propertyPath which is passed to the constructor for OwnerVoter class. \ One can create custom voters based on the AbstractEntityVoter class. Example:

1 Add new voter:

2 Add new voter to services:

Where: \ arguments: ... - arguments to the custom voter class constructor \ [fetch, create, update, delete] - array of access attributes (required) \ YourBundle\Entity\Country - entity class (required) \ true - required user flag (optional, true by default)

3 Add 'access_attribute' to service config for set attributes to check user permissions (as needed). \ 'access_attribute' : 'fetch' by default.

Additional functionality

Expand

One can use the related entity references instead of full value in the response. See Expand in ListAction

Request example

Response example

Abstract Form Action Class

This is an abstract class that is the parent for the Update Actions. Can be used to inherit and to create another custom actions.

Available Options

Create Action

Action to create a new object. This is a subclass that inherits from AbstractFormAction class.

There are two required parameters: Entity class and FormType Class. Example:

Available Options

Event listeners

By default Create and Update actions throws such events: 'action.before_save', 'action.after_save'. You can dispatch this events, or throw another events using such options as: before_save_events and after_save_events.

You can create listeners that will respond to event occuring before and after submit the request. You need to configure it in services.yml file:

Then you need to specify this listeners in create action configuration:

Update Action

Action to update an existing object. This is a subclass that inherits from AbstractFormAction class.

There are two required parameters: Entity class and FormType Class. Example:

Available Options

Update action has the same available features and options as a create action. (see "Create Action")

Delete Action

Action to delete an existing object

There is one required parameter: Entity class. Example:

Available Options

Event listeners

By default Delete action throws a such event: 'action.before_delete'. You can dispatch this event, or throw another events using such an option: before_delete_events.

You can create listeners that will respond to event occuring before delete the entity. You need to configure it in services.yml file:

Then you need to specify this listeners in delete action configuration: