Important
You are browsing documentation for version 5.1 of OroCommerce, supported until March 2026. Read the documentation for version 6.0 (the latest LTS version) to get up-to-date information.
See our Release Process documentation for more information on the currently supported and upcoming releases.
Configuration Reference
The configuration declares all aspects related to a specific entity. The configuration should be placed in Resources/config/oro/api.yml to be automatically loaded.
All entities, except custom entities, dictionaries, and enumerations, are inaccessible via the API. To make an entity available via the data, enable it directly. For example, to make the Acme\Bundle\DemoBundle\Product entity available via the API, use the following configuration:
api:
entities:
Acme\Bundle\DemoBundle\Product: ~
If an auto-generated alias for your entity does not look good enough for you, change it in Resources/config/oro/entity.yml. For more details, see the entity aliases documentation.
Important
Run the oro:api:cache:clear CLI command to make an entity accessible via the API immediately. If you use the API sandbox, run the oro:api:doc:cache:clear CLI command to apply the changes for it.
For additional information, see CLI commands.
Configuration Structure
To get the overall configuration structure, execute the following command:
php bin/console oro:api:config:dump-reference
By default, this command shows the configuration of nesting entities. To simplify the output, you can use the --max-nesting-level option, for example:
php bin/console oro:api:config:dump-reference --max-nesting-level=0
The default nesting level is 3. It is specified in the configuration of ApiBundle via the config_max_nesting_level parameter. If needed, change this value:
The first level sections of the configuration are:
entity_aliases - allows overriding entity aliases.
entities - describes the configuration of entities.
The top-level configuration example:
api:
entity_aliases:
Acme\Bundle\DemoBundle\Entity\SomeEntity:
# ...
entities:
Acme\Bundle\DemoBundle\Entity\SomeEntity:
exclude:
# ...
fields:
# ...
filters:
fields:
# ...
sorters:
fields:
# ...
actions:
# ...
subresources:
# ...
exclude Option
The exclude configuration option describes whether an entity or its fields should be excluded from the API.
Example:
api:
entities:
Acme\Bundle\DemoBundle\Entity\SomeEntity1:
exclude: true # exclude the entity from the API
Acme\Bundle\DemoBundle\Entity\SomeEntity2:
fields:
field1:
exclude: true # exclude the field from the API
Additionally, use the exclude option to indicate whether to disable filtering or sorting for specific fields. Please note that for fields excluded as described above, filtering and sorting are disabled automatically.
Example:
api:
entities:
Acme\Bundle\DemoBundle\Entity\SomeEntity1:
sorters:
fields:
field1:
exclude: true
filters:
fields:
field1:
exclude: true
Please note that the exclude option applies only to the API. To exclude an entity or its fields globally, use Resources/config/oro/entity.yml:
oro_entity:
exclusions:
# whole entity exclusion
- { entity: Acme\Bundle\DemoBundle\Entity\SomeEntity1 }
# exclude field1 of Acme\Bundle\DemoBundle\Entity\Entity2 entity
- { entity: Acme\Bundle\DemoBundle\Entity\SomeEntity2, field: field1 }
entity_aliases Configuration Section
You can use the entity_aliases section to:
Override the existing system-wide entity aliases
Add aliases for models to be used only in the API
Completely replace an ORM entity with a model
Use it when you need to provide entity aliases for the API, but sharing them system-wide is impossible; for example, because of the backward compatibility promise or when your models were created to be used only in the API.
Please see the Entity aliases documentation for more details about entity aliases.
Example:
api:
entity_aliases:
Acme\Bundle\DemoBundle\Entity\SomeEntity:
alias: acmeentity
plural_alias: acmeentities
To completely replace an ORM entity with a model in the API, use the override_class option. As a result, the model will be used in the primary API resource, sub-resources, and relationships instead of the overridden ORM entity. This is helpful when creating and using a model that can significantly simplify the API implementation, for example, when the schema of the API resource is different from the schema of the ORM entity.
Example:
api:
entity_aliases:
Acme\Bundle\DemoBundle\Api\Model\SomeModel:
alias: acmeentity
plural_alias: acmeentities
override_class: Acme\Bundle\DemoBundle\Entity\SomeEntity
Note
The model class must be a subclass of the overridden entity class.
Note
When the override_class option is used, some entity-specific configuration, like Extended Associations, is required for an overridden ORM entity, but not for a model.
Example of correct configuration:
api:
entities:
Acme\Bundle\DemoBundle\Api\Model\SomeModel: ~
Acme\Bundle\DemoBundle\Entity\SomeEntity:
fields:
target:
data_type: association:manyToOne
Example of incorrect configuration:
api:
entities:
Acme\Bundle\DemoBundle\Api\Model\SomeModel: ~
fields:
target:
data_type: association:manyToOne
entities Configuration Section
The entities section describes the configuration of entities.
documentation_resource string - Can contain the link to the markdown file with detailed documentation on a single or multiple API resources. For more details, see Documenting API Resources.
Please note that the same entity can be configured in different Resources/config/oro/api.yml files, e.g., when some bundle needs to add a field to an entity declared in another bundle. In this case, all configuration files for this entity can have the documentation_resource option, and all documentation files declared there are merged. If the same field is documented in several documentation files, they are merged, and only documentation from one file is used.
exclude boolean - Indicates whether the entity should be excluded from the API. By default, it is set to
false.inherit boolean - Indicates whether the configuration for a certain entity should be merged with the configuration of a parent entity. By default, it is set to
true. Set tofalseif a derived entity should have a completely different configuration than the parent entity and merging with the parent configuration is unnecessary.exclusion_policy string - Indicates the exclusion strategy to use for the entity. Possible values:
all,custom_fieldsornone. By default, it is set tonone.none- exclude fields marked with the exclude flag.all- exclude all fields that are not configured explicitly.custom_fields- exclude all custom fields (fields withis_extend = trueandowner = Customin the extend scope in the entity configuration) that are not configured explicitly.
max_results integer - The maximum number of entities in the result. Set
-1(unlimited), zero, or positive number to set the limit. Use to set the limit for both primary and related entities. Seemax_entitiesandmax_related_entitiesoptions in General Configuration for default limits. Please note that this option affects all actions including get_list action. Use themax_resultsoption in the actions configuration to change the maximum number of entities that can be deleted by one request or set own limit to each action, see How To.order_by array - The property can be used to configure the default ordering of the result. The item key is the name of a field. The value can be
ASCorDESC. By default, the result is ordered by an identifier field.disable_inclusion boolean - Indicates whether an inclusion of related entities is disabled. In JSON:API the include request parameter can be used to customize which related entities should be returned. By default
false.disable_fieldset boolean - Indicates whether one can request a restricted set of fields. In JSON:API, the fields request parameter is used to customize which fields to return. By default
false.disable_meta_properties string[] or boolean - The names of additional meta properties a requesting of that are disabled or the flag that indicates whether requesting additional meta properties is disabled at all. By default
false.disable_partial_load boolean - The flag indicates whether using of Doctrine partial objects is disabled. By default
false. When using partial objects, theHINT_FORCE_PARTIAL_LOADquery hint is used together with them to avoid loading unneeded foreign keys.hints array - The Doctrine query hints. Each item can be a string or an array with
nameandvaluekeys. The string value is a short form of[name: hint name].inner_join_associations string[] - A list of entity associations for which INNER JOIN should be used instead of LEFT JOIN. Use the
dotnotation to specify a path to a nested association, e.g.,user.organization. Each element in the path must be equal to the name of the existing property of an entity. This option can be used to optimize SQL query that is used to load data if some associations are mandatory and cannot be empty.identifier_field_names string[] - The names of identifier fields of the entity. Use this option to override names set in a configuration file (for the API resource not based on the ORM entity) or retrieve from entity metadata (for ORM entities). This option is helpful when you do not want to use the primary key as an entity identifier in the API.
identifier_description string - A human-readable description of the API resource identifier. Used in auto-generated documentation only.
upsert array - The configuration of the upsert operation. For details, see Configure Upsert Operation.
form_type string - The form type to use for the entity in the create and update actions. By default the
Symfony\Component\Form\Extension\Core\Type\FormTypeform type is used.form_options array - The form options to use for the entity in the create and update actions.
form_event_subscriber - The form event subscriber(s) to use for the entity in the create and update actions. When the form_type option is not specified,, this event subscriber is also used for the update_relationship, add_relationship and delete_relationship actions. For custom
form_typethis event subscriber is not used. It can be specified as a service name or an array of service names. An event subscriber service should implement theSymfony\Component\EventDispatcher\EventSubscriberInterfaceinterface.
By default, the following form options are set:
Option Name |
Option Value |
|---|---|
data_class |
The class name of the entity |
validation_groups |
Possible values: [‘Default’, ‘api’], and/or a custom group. |
extra_fields_message |
This form should not contain extra fields: {{ extra_fields }}. |
Example:
api:
entities:
Acme\Bundle\DemoBundle\Entity\SomeEntity:
documentation_resource: '@AcmeDemoBundle/Resources/doc/api/some_entity.md'
inherit: false
exclusion_policy: all
max_results: 25
order_by:
field1: DESC
field2: ASC
hints:
- HINT_TRANSLATABLE
- { name: HINT_FILTER_BY_CURRENT_USER }
- { name: HINT_FORCE_PARTIAL_LOAD, value: false }
- { name: HINT_CUSTOM_OUTPUT_WALKER, value: 'Acme\Bundle\DemoBundle\AST_Walker_Class'}
excluded: false
upsert:
add: [['field1']]
form_type: Acme\Bundle\DemoBundle\Api\Form\Type\SomeEntityType
form_options:
validation_groups: ['Default', 'api', 'my_group']
form_event_subscriber: acme.api.form_listener.test_entity
fields Configuration Section
This section describes the configuration of entity fields.
exclude boolean - Indicates whether the field should be excluded. This property is described above in the “exclude” option section.
description string - A human-readable description of the field. Used in auto-generated documentation only.
property_path string - The property path to reach the fields’ value. Can be used to rename the field or to access a field of the related entity. Use the
dotnotation to separate property names in the path, e.g.user.firstName. Each property name must be equal to the name of an existing property of an entity. The_value can be used if a field value is not mapped to any property of an entity, e.g., for computed fields.collapse boolean - Indicates whether to collapse the entity. It is applicable to associations only. When
true, the target entity is returned as a value instead of an array of entity field values.form_type string - The form type to use for the field in the create and update actions.
form_options array - The form options to use for the field in the create and update actions.
data_type string - The data type of the field value. It can be
boolean,integer,string, etc. If a field represents an association, the data type should be a type of an identity field of the target entity.meta_property boolean - A flag indicates whether the field represents meta information. For JSON:API, such fields are returned in the meta section. By default,
false.target_class string - The class name of a target entity if a field represents an association. If the API resource is based on the non-ORM entity, set the target class in a configuration file.
target_type string - The type of a target association. Can be to-one or to-many. Also, collection can be used as an alias for to-many. to-one can be omitted as it is used by default. If the API resource is based on the non ORM entity, set the target type in a configuration file.
depends_on string[] - A list of entity properties that the field depends on. Use the
dotnotation to specify a path to a nested property, e.g.,user.firstName. Each element in the path must be equal to the name of existing property of an entity. This option is helpful for computed fields: the specified fields will be loaded from the database even if they are excluded.post_processor string - The name of a post processor used to convert a field value to a format suitable for the API. The post-processor is used in the get, get_list and get_subresource actions.
post_processor_options array - The options for a post processor specified in the post_processor option.
Examples:
api:
entities:
Acme\Bundle\DemoBundle\Entity\SomeEntity:
fields:
# Exclude a field
field1:
exclude: true
# Rename the "firstName" field to the "name" field
name:
description: Some Field
property_path: firstName
# The "addressName" field will contain the value of the "name" field of the "address" related entity
addressName:
property_path: address.name
# A full syntax for the "collapse" property
field4:
collapse: true
exclusion_policy: all
fields:
targetField1: null
# A short syntax for the "collapse" property
field5:
fields: targetField1
# A form type and form options for a field
field6:
form_type: Symfony\Component\Form\Extension\Core\Type\TextType
form_options:
trim: false
constraints:
# add Symfony\Component\Validator\Constraints\NotBlank validation constraint
- NotBlank: ~
# A to-one association
field7:
data_type: integer # the data type of an identifier field of the target
target_class: Acme\Bundle\DemoBundle\Api\Model\SomeTargetEntity
# A to-many association
field8:
data_type: integer # the data type of an identifier field of the target
target_class: Acme\Bundle\DemoBundle\Api\Model\SomeTargetEntity
target_type: collection
# A computed field
field9:
data_type: string
property_path: _
depends_on: [property1, association1.property11]
# A field with a post processor
field10:
post_processor: twig
post_processor_options:
template: '@AcmeDemo/Api/Field/some_template.html.twig'
Special Data Types
The data_type attribute can be used to specify a data type of a field. However, it can also help configure special types of fields. The following table contains details of such types:
Data Type |
Description |
|---|---|
scalar |
Represents a field of a to-one association as a field of the parent entity. In JSON:API, it means that the association’s field should be in the |
object |
Represents to-one association as a field, an associative array or an object. In JSON:API, it means that the association should be in the |
array |
Represents a field contains an array data or a field of a to-many association as a field of the parent entity. In JSON:API, it means that the association should be in the |
objects |
Represents to-many association as a field. In JSON:API, it means that the association should be in the |
strings |
Represents a string field of a to-many association as a field. In JSON:API, it means that the association should be in the |
data-type[] |
Represents a field of a to-many association as a field. In JSON:API, it means that the association should be in the |
percent_100 |
Represents a percentage value multiplied by 100. It means that a value is multiplied by 100 before it is stored in the database. E.g., 50% is represented in API as 0.5, but stored in the database as 50. |
nestedObject |
Helps configure nested objects. For details see Configure a Nested Object. |
nestedAssociation |
Helps configure nested associations. For details see Configure a Nested Association. |
association:relationType[:associationKind] |
Helps configure multi-target associations. For details, see Configure an Extended Many-To-One Association, Configure an Extended Many-To-Many Association and Configure an Extended Multiple Many-To-One Association. |
unidirectionalAssociation:targetAssociationName |
Helps configure unidirectional associations. For details, see Configure an Unidirectional Association. |
localizedFallbackValue:fieldName |
Helps configure to-many associations to LocalizedFallbackValue for the Storefront API. |
Note
The scalar, object, array, objects, strings, and data-type[] data types are interchangeable in case they are used to represent an association as a field. They were introduced to increase the readability of configs and automatically generated documentation, e.g. for API Sandbox. The scalar is usually used if a field value contains a scalar value. The array, strings, and data-type[] are usually used if a field value contains a list of scalar values. The object is usually used if a field value contains several properties. The objects is usually used if a field value contains a list of items with several properties.
Note
To add a new particular type of a field that requires an additional configuration of a field or an entity, create a class that implements CustomDataTypeCompleterInterface and register this class in the dependency injection container with oro.api.custom_data_type_completer tag. The requestType tag attribute can be used to register a converter only for specific request types.
filters Configuration Section
This section describes fields by which the result data can be filtered. It contains two properties: exclusion_policy and fields.
exclusion_policy string.
Can be
allornone. By defaultnone. Indicates which exclusion strategy to use. Possible values:allornone.none- Exclude fields marked with the exclude flag.all- Exclude both marked and not marked fields.fields This section describes a configuration of each field that can be used to filter the result data. Each filter can have the following properties:
exclude boolean - Indicates whether filtering by this field should be disabled. By default
false.description string - A human-readable description of the filter. Used in auto-generated documentation only.
property_path string - The property path to reach the fields’ value. The same way as above in fields configuration section.
data_type string - The data type of the filter value. Can be
boolean,integer,string, etc.allow_array boolean - Indicates whether the filter can contains several values. By default,
falseforstring,boolean,datetime,date,timefields, andtruefor other fields.allow_range boolean - Indicates whether the filter can contains a pair of
fromandtovalues. By default,falseforstring,boolean,guid,currencyfields, andtruefor other fields.collection (boolean) - Indicates whether the filter represents a collection valued association. By default,
falsefor filters by fields and to-one associations, andtruefor filters by to-many associations.type string - The filter type. By default, the filter type is equal to the data_type property value.
options array - The filter options.
operators string[] - A list of operators supported by the filter. By default, the list of operators depends on the filter type. For example a string filter supports = and != operators, a number filter supports =, !=, <, <=, > and >= operators, etc. Use this parameter when you need to limit a list of supported operators.
Example:
api:
entities:
Acme\Bundle\DemoBundle\Entity\SomeEntity:
filters:
exclusion_policy: all
fields:
field1:
data_type: integer
exclude: true
field2:
data_type: string
property_path: firstName
description: 'My filter description'
field3:
data_type: date
allow_array: true
allow_range: true
field4:
data_type: string
type: myFilter
options:
my_option: value
field5:
operators: ['=']
Note
Please note that filters for fields that have a database index are enabled automatically. Filters by all other fields should be enabled explicitly, if necessary.
See Filters for more information on the existing filter types and instructions on creating custom filters.
sorters configuration section
This section describes fields by which you can sort the result data. It contains two properties: exclusion_policy and fields.
exclusion_policy string.
Can be
allornone. By defaultnone. Indicates the exclusion strategy that should be used.allmeans that all fields are not configured explicitly will be excluded.nonemeans that only fields marked with theexcludeflag are excluded.fields
This section describes a configuration of each field that can be used to sort the result data. Each sorter can have the following properties:
exclude boolean - Indicates whether sorting by this field should be disabled. By default
false.property_path string - The property path to reach the fields’ value. See the property description in the fields configuration section.
Example:
api:
entities:
Acme\Bundle\DemoBundle\Entity\SomeEntity:
sorters:
fields:
field1:
property_path: firstName
field2:
exclude: true
actions Configuration Section
The actions configuration section enables you to specify action-specific options. The options from this section will be added to the entity configuration. If an option exists in the configuration of both the entity and the action, the action option wins. The exception is the exclude option. This option is used to disable an action for a specific entity, and it is not copied to the entity configuration.
exclude boolean - Indicates whether the action is disabled for an entity. By default
false.description string - A short human-readable description of an API resource. Used in auto-generated documentation only.
documentation string - Detailed documentation of an API resource. Used in auto-generated documentation only.
acl_resource string - The name of an ACL resource used to protect an entity in scope of this action. Set to
nullto disable access checks.max_results integer - The maximum number of entities in the result. Set
-1(unlimited), zero, or positive number to set the limit. Can be used to set the limit for both root and related entities.order_by array - The property can be used to configure the default ordering of the result. The item key is the name of a field. The value can be
ASCorDESC. By default, the result is ordered by identifier field.page_size integer - The default page size. Set to
-1to disable pagination or a positive number. By default, 10, see thedefault_page_sizeoption in General Configuration.disable_sorting boolean - Indicates whether to disable the sorting. By default, false.
disable_inclusion boolean - The flag indicates whether the inclusion of related entities is disabled. In JSON:API, the include request parameter can be used to customize which related entities should be returned. By default
false.disable_fieldset boolean - The flag indicates whether requesting a restricted set of fields is disabled. In JSON:API, the fields request parameter can be used to customize which fields should be returned. By default
false.disable_meta_properties string[] or boolean - The names of additional meta properties a requesting of that are disabled or the flag that indicates whether requesting additional meta properties is disabled at all. By default
false.upsert array - The configuration of the upsert operation. For details, see Configure Upsert Operation.
form_type string - The form type that should be used for the entity.
form_options array - The form options to use for the entity. If
form_typeis not specified, the form options specified here are merged with form options defined at the entity level. Ifform_typeis specified in the action configuration, the action form options completely replace the form options defined at the entity level.form_event_subscriber - The form event subscribers to use for the entity. Can be specified as a service name or array of service names. An event subscriber service should implement the
Symfony\Component\EventDispatcher\EventSubscriberInterfaceinterface. Ifform_typeis not specified, the event subscribers specified here are merged with the event subscribers defined at the entity level. Ifform_typeis specified in the action configuration, the action event subscribers completely replace the event subscribers defined at the entity level.status_codes array - The possible response status codes for the action.
exclude boolean - Indicates whether the status code should be excluded for a particular action. This property is described above in “exclude” option section.
description string - A human-readable description of the status code. Used in auto-generated documentation only.
fields - This section describes entity fields’ configuration specific for a particular action.
exclude boolean - Indicates whether the field should be excluded for a particular action. This property is described above in “exclude” option section.
property_path string - The property path to reach the fields’ value. Can be used to rename the field or to access a field of the related entity. Use the
dotnotation to separate property names in the path, e.g.user.firstName. Each property name must be equal to the name of the existing property of an entity. The_value can be used if a field value is not mapped to any property of an entity, e.g., for computed fields.direction string - Indicates whether the field is input-only, output-only or bidirectional. The input-only means that the request data can contain this field, but the response data cannot. The output-only means that the response data can contain this field, but the request data cannot. The bidirectional is the default behavior and means that both the request data and the response data can contain this field.
form_type string - The form type that should be used for the field.
form_options array - The form options that should be used for the field.
By default, the following permissions are used to restrict access to an entity within a scope of a specific action:
Action |
Permission |
|---|---|
get |
VIEW |
get_list |
VIEW |
create |
CREATE and VIEW |
update |
EDIT and VIEW |
delete |
DELETE |
delete_list |
DELETE |
The following are examples of the actions section configuration.
Disable all action for an entity:
api:
entities:
Acme\Bundle\DemoBundle\Entity\SomeEntity:
# this entity does not have own API resource
actions: false
Disable the delete action for an entity:
api:
entities:
Acme\Bundle\DemoBundle\Entity\SomeEntity:
actions:
delete:
exclude: true
You can use a short syntax:
api:
entities:
Acme\Bundle\DemoBundle\Entity\SomeEntity:
actions:
delete: false
Set a custom ACL resource for the get_list action:
api:
entities:
Acme\Bundle\DemoBundle\Entity\SomeEntity:
actions:
get_list:
acl_resource: acme_view_resource
Turn off the access checks for the get action:
api:
entities:
Acme\Bundle\DemoBundle\Entity\SomeEntity:
actions:
get:
acl_resource: ~
Add an additional status code for the delete action:
api:
entities:
Acme\Bundle\DemoBundle\Entity\SomeEntity:
actions:
delete:
status_codes:
417: 'Returned when expectations failed'
or
api:
entities:
Acme\Bundle\DemoBundle\Entity\SomeEntity:
actions:
delete:
status_codes:
417:
description: 'Returned when expectations failed'
Remove the existing status code for the delete action:
api:
entities:
Acme\Bundle\DemoBundle\Entity\SomeEntity:
actions:
delete:
status_codes:
417: false
or
api:
entities:
Acme\Bundle\DemoBundle\Entity\SomeEntity:
actions:
delete:
status_codes:
417:
exclude: true
Exclude a field for the update action:
api:
entities:
Acme\Bundle\DemoBundle\Entity\SomeEntity:
actions:
update:
fields:
field1:
exclude: true
subresources Configuration Section
The subresources configuration section enables you to provide options for sub-resources.
exclude boolean - Indicates whether the sub-resource is disabled for entity. By default
false.target_class string - The class name of a target entity.
target_type string - The type of a target association. Can be to-one or to-many. collection can be used as an alias for to-many. to-one can be omitted as it is used by default.
actions array - The actions supported by the sub-resource. This section has the same options as actions configuration section. If an option exists in both the entity actions section and the sub-resource actions section, the sub-resource option wins.
filters - The filters supported by the sub-resource. This section has the same options as filters configuration section. If an option exists in both entity “filters” section and sub-resource filters section the sub-resource option wins.
sorters - The sorters supported by the sub-resource. This section has the same options as the entity sorters section. If an option exists in both the entity sorters section and the sub-resource sorters section, the sub-resource option wins.
Note
A subresource is accessible via API only if its target entity is also accessible via API. However, there are several exceptions to this rule:
if a target entity does not have an identifier
if a target entity is EntityIdentifier and at least one entity from a list of acceptable target classes is accessible via API
if a target entity is a base class for Doctrine’s inheritance mapping and at least one concrete entity for this mapping is accessible via API
Example:
api:
entities:
Oro\Bundle\EmailBundle\Entity\Email:
subresources:
suggestions:
target_class: Oro\Bundle\ApiBundle\Model\EntityIdentifier
target_type: collection
actions:
get_subresource:
description: Retrieve entities that might be associated with the email
get_relationship: false
update_relationship: false
add_relationship: false
delete_relationship: false
filters:
fields:
searchText:
data_type: string
operators: [ '=' ]
property_path: _