Metadata API

The Metadata API exposes the structure of every entity: its fields, serialization groups, operations, filters and properties. It is the source the CRUD generator and the frontends rely on to build listing, show, add and edit pages.

GET {{BASE_URL}}/{{API_VERSION}}/metadata/entities

PHPReaction\Entity\AccountingBundle\Account

GET {{BASE_URL}}/{{API_VERSION}}/metadata/entity/PHPReaction\Entity\AccountingBundle\Account

Metadata Entity Keys

success
class_object_data
availableSerializationGroups
parentRole
resourceName
operations
required_properties
displayable_properties
writable_properties
updatable_properties
unfiltered_fields
virtual_properties
writable_required_properties
properties_initialized_with_value_on_null
shortname
entity
constraints
apiFilters
fields
database_required_properties
hidden_from_serialization_properties
hidden_oneToMany_relations_properties

Class Objects

class_object_data has many keys, but for now we will only discuss the fields that are being used in the CRUD generator.

• implemented_interfaces — implemented by the Symfony API Platform, it returns all the implementations used by that entity. For more about the implemented interfaces, refer to the detailed doc: Implements 

• tableName — used by the frontend for the custom properties:

  /${apiVersion}/custom_properties?tableName=${tableName}

• role_prefix — not used directly by the generator, but we use roles in the same format as the one defined here (e.g., ROLE_MOD_ACCOUNTING_ACCOUNT_)

• defaultDataSkeletonUri — used by the add and edit forms on the frontend to display the default skeleton values when there is no query string or KVS stored value.

Serialization Groups

The field availableSerializationGroups is used to get the fields from the metadata entity API according to the group.

To generate the fields for the show page, we use these groups: standardShow, accountingAccountShow, show.

To use serialization groups, pass them through the query string:

GET {{BASE_URL}}/{{API_VERSION}}/metadata/entity/PHPReaction\Entity\AccountingBundle\Account?groups[]=standardShow&groups[]=accountingAccountShow&groups[]=show

Resource Name

resourceName is the main source of truth for the CRUD generator and the frontends. We store the config files on the frontend as crud_configs/${resourceName} (for example src/crud_configs/accounts).

We call all the CRUD APIs with the resource name:

{{BASE_URL}}/{{API_VERSION}}/{{resourceName}}

Operations

operations is an object with a few nested fields, and it is the main deciding factor for the generator and the frontend to display any page. If an entity does not have any operation, we do not display it, and for the pages we show the 404 page.

• read — GET operation
• add — POST operation
• update — PUT/PATCH operation

There are a few objects in this which we used previously. With the recent changes for simpler information we are not using them anymore, but they are documented here:

"0": {
  "method": "GET",
  "url": "…",
  "groups": { "normalization": ["dropdown"], "denormalization": [] }
}

Required Properties

required_properties refers to the fields which are required and can’t be passed as null in the POST/PUT/PATCH endpoints.

Displayable Properties

displayable_properties refers to the fields that need to be displayed within that serialization group / interface on the frontend.

Writable Properties

writable_properties is the major deciding factor for the POST/PUT/PATCH endpoints, which require only those fields that can be written.

This matters because we have a few fields in the virtual_properties which are just for reading or identification purposes and do not have a real use case in the DB.

Updatable Properties

updatable_properties refers to the properties that can be edited through the PUT/PATCH endpoints.

Unfiltered Fields

unfiltered_fields is a recent enhancement. It was added because we wanted all the fields that have a direct or indirect relation with other entities. But we somehow ended up getting all the fields, which are both relational and non-relational fields.

This is mainly used to generate the sideboxes of an entity, by deciding through the type of each field (MANY_TO_MANY, ONE_TO_MANY).

Virtual Properties

virtual_properties, as said above, are the properties which do not have a real use case; however, they are important to display on the frontend.

There is a virtual property toString which is considered an identification field and is equally as important on the frontend as the others. For example, on the show page it is displayed in the header as an identifier of a record.

Writable Required Properties

writable_required_properties has all the properties that are required and writable. It is a combination of required_properties and writable_properties.

API Filters

apiFilters has all the filters supported by the entity.

We will not deep dive into what all these filters do, but just to mention here that these filters are used on the listing pages of the frontend. As well, the sorting filter is used by the listing table to manage the order of the fields, asc and desc.

Here is the list of the nested objects, or you can say the filter identifiers:

ApiPlatform\Doctrine\Orm\Filter\SearchFilter
PHPReaction\Api\Filter\TranslationSearchFilter
ApiPlatform\Doctrine\Orm\Filter\NumericFilter
ApiPlatform\Doctrine\Orm\Filter\RangeFilter
ApiPlatform\Doctrine\Orm\Filter\BooleanFilter
ApiPlatform\Doctrine\Orm\Filter\DateFilter
ApiPlatform\Doctrine\Orm\Filter\ExistsFilter
ApiPlatform\Serializer\Filter\PropertyFilter
PHPReaction\Filter\APIv3\EnabledFilter
PHPReaction\Filter\APIv3\SearchTermsFilter
PHPReaction\Core\ApiV3Bundle\Bridge\Doctrine\Orm\Filter\TagAPIFilter
PHPReaction\Api\Filter\OrderFilter

Fields

fields is used to generate the fields metadata in the generator.

We generate the list of writable/updatable fields; however, fields gives their detailed metadata, like which field has what type, can be unique, length, nullable, etc.