Entity resource layer

Provides plugins that can operate above the default core REST resource plugins specifically for entities. By this allows you to easily serve and create your entities the way that you want. But this is not all, read on!

This module is provided solely for developers and has no use for end users as is. The documentation below assumes you have a basic knowledge and experience with the core REST API.

Features

Through the plugin are provided most features:

• ability to target the functionality for entities per bundle and more
• alteration of inbound requests or outbound responses
• pre and post reacting per REST methods
• automatic and manual field name mapping (alias <-> machine name)
• exclusion / inclusion of fields, protection of sensitive data
• data focusing: return one value of the entity without object format
• automatic embedding of defined referenced entities / reference fields
• custom access checking per REST method
• custom entity validations for POST and PATCH
• provision for custom additional paths for endpoints

But there are features also outside of the plugins like:

• improved validation error responses that contain more information
• multiple validation errors sent at once
• possibility for API versioning
• removed unnecessary nesting of response values, clean responses
• improved and possibly separated REST logging

Requirements

The only requirement, obviously, the core rest module.

Configuration

There are no extra configurations for REST. The entity endpoints are as usual enabled and configured from the Configuration > Web Services > Rest . Once any endpoint for one entity is open then all resource layer plugins for that entity will apply.

Getting started

Most of the information you need are found in the src/Annotation/EntityResourceLayer.php annotation. From here you should start and read carefully each value what represents and what it can contain.

Once you've done your research you can start implementing your
resource layer plugins under src/Plugins/Resource.

Usage with views

Note that these plugins also apply per serialization basis, which allows them to be used with views as-well. Make sure when rendering the entities from the view you select to display as entity and not fields.

Entity reference embedding

You can embed entities that are referenced through fields of the current entity. This embedded entity can also have it's resource layer plugin in turn and be formatted the way you want. This allows for infinite nesting and customization options.

Resource layer selection

You can have multiple layers for same entity/bundle. These in turn can have different priorities and in that order are applied. Note that resource plugin application can also be filtered upon path. This allows for custom representations of the same entity in different contexts.

Custom entity validations

Before using custom validations you should check the defined exceptions that this module provides. The basic idea is that validations errors are created with exceptions that are transformed to responses. These exceptions are based on constraints. You can also provide your constraint information for custom exception of this type.

The module provides an exception that is multiple (src/Exception/EntityResourceMultipleException.php). This allows for all validation errors to be returned to the consumer at once.

You can find an example plugin in the module README