Download the PHP package awtyklo/carve-api without Composer

Carve API

Consistent and reusable way of composing REST API endpoints for Symfony.

IMPORTANT! Work in progress.

Offers consistent and reusable way of composing REST API endpoints Allows single-minded endpoint customization Automaticly generates OpenAPI documentation Introduces deny functionality to allow easier access control that includes feedback messages Adds layer of constraints that have REST API friendly messages

Build with:

• FOSRestBundle
• Symfony serializer
• OpenAPI

Branches

You can use following branches:

1. main (default) - branch for current version 3.x (Symfony 7.1)
2. v2.x - branch for version 2.x (Symfony 6.4)
3. v1.x - branch for version 1.x (Symfony 5.4)

Release

Add new release on GitHub. It should be automatically synchronized by packagist. Remember to add tag when adding new release (i.e. 3.0.1) as well.

Configuration

Add in config/packages/doctrine.yaml. It will enable storing Types::DATETIME_MUTABLE always in UTC timezone.

Add in config/services.yaml. It will override default FormErrorNormalizer to additionally pass parameters from error messages.

Add in config/services.yaml. It will override default ViewResponseListener to additionally handle exporting views.

Add in config/packages/framework.yaml. It will add default circular reference handling.

Modify src/Kernel.php to override FormModelDescriber class.

Request execution error reporting

Designed to provide additional information in the response when action in a controller could be executed only partially. Throwing RequestExecutionException will result in 409 HTTP code.

Below you can find more information about default HTTP codes and how RequestExecutionException with 409 fits in it.

• 200 - Request has been executed successfully. Additional data can be included in the response (i.e. updated object).
• 204 - Request has been executed successfully. No additional is included in the response.
• 400 - Request could not be executed due to invalid payload (widely used with forms). Form errors are serialized by Carve\ApiBundle\Serializer\Normalizer\FormErrorNormalizer.
• 409 - Request has been executed only partially (payload is correct). Additional information is included in the response.
• 500 - Unexpected error.

Response structure

Example structure as follows (TypeScript).

First level severity will take the value of the highest severity from the messages.

Severity interpretation

error means that at some point in action execution there was an error that prevented executing remaining steps. Good example would be not be able to connect to third party system (i.e. Google services).

warning means that at some point in action execution there was an issue that should not happen, but it has been managed and remaining steps has been executed. Good example would be not be removing action of a resource from third party system which resulted in lack of such resource (our application expects that resource exists and tries to remove it, but the resource does not exist in third party system).

Usage examples

TODO Fix this (right now it has old examples - some of the are correct. Extend with mergeAsX function example)

error.requestExecutionFailed - is default message value - it can be changed by setting 3rd parameter in RequestExecutionException constructor. Constructor message (1st parameter) is added as first object in errors array, others can be added using addError method

Example below:

Another example:

Integration with forge

By default forge frontend ErrorDialog by using handleCatch and ErrorContext will show response in dialog. message (translated) will be used as dialog title, errors array will be shown as multiple Alerts with error serverity. Text will be translated using message as key and parameters as translation parameters. ErrorDialog needs to be added to application layout

Batch processing

Batch processing is designed to process results that are possible to query via list endpoint.

You can customize returned by returning custom BatchResult in $process function. When nothing is returned a BatchResult with SUCCESS status will be returned (controller by getDefaultBatchProcessEmptyResult function).

You can also use denyKey to skip any results that should not be processed (BatchResult with SKIPPED and message based on denyKey will be returned).

You can use following pattern to define additional field in BatchQueryType form (which has only sorting and ids fields).

Define form that includes any needed fields and extends BatchQueryType. Fields should not be mapped or you will need to update the data model of form (which is also a good solution).

Prepare a custom logic in Controller.

Notable comment for handleBatchForm function.

Export (CSV and Excel)

When using Carve\ApiBundle\EventListener\ViewResponseListener and returning Carve\ApiBundle\View\ExportCsvView or Carve\ApiBundle\View\ExportExcelView from controller, the results will be automatically serialized and returned to as a csv or xlsx file.

Example usage:

Enums translation

By default every enum in export will be translated. The structure of translation string looks like this: enum.entityName.fieldName.enumValue. You can override the prefix by adding an Carve\ApiBundle\Attribute\Export\ExportEnumPrefix attribute.

In example below, translated string would be enum.common.sourceType.enumValue.

Export customization

You can customize common export cases by using similar pattern as Carve\ApiBundle\Serializer\ExportEnumNormalizer.

Local development

Add to composer.json in your project following lines:

Change "/var/www/carve-api" to your local path to the package. It should point to the root directory of carve-api (this means composer.json of carve-api is located in /var/www/carve-api/composer.json).

Afterwads execute:

It should link local package instead of one from remote.

Note! It will change composer.json. Please remember that while committing changes.

TODO: How to revert this

REST API Documentation

Note! Only one method for each endpoint is supported. Multiple methods for endpoint might yield unexpected results (i.e. having both GET and POST on /api/config).

Subject parameters

Some of mentioned attributes support subject parameters which means that a string (i.e. summary, description) can include parameters which will be replaced by Describer\ApiDescriber.

Subject parameters are prepared based on subject in Api\Resource attribute.

Supported subject parameters as follows. Example for subject = "User".

• subjectLower i.e. "user"
• subjectTitle i.e. "User"
• subjectPluralLower i.e. "users"
• subjectPluralTitle i.e. "Users"

Attributes

• #[Api\Summary] - Attaches summary to the operation. Summary supports subject parameters.
• #[Api\Parameter] - Parameter with description that supports subject parameters.
• #[Api\ParameterPathId] - Preconfigured path ID parameter with description that supports subject parameters.
• #[Api\RequestBody] - Request body with description that supports subject parameters.
• #[Api\RequestBodyBatch] - Request body with description that supports subject parameters. When there is no content (Nelmio\ApiDocBundle\Annotation\Model is expected) it set as Api\Resource->batchFormClass. It also attaches 'sorting_field_choices' to content options.
• #[Api\RequestBodyCreate] - Request body with content set as Api\Resource->createFormClass and description that supports subject parameters.
• #[Api\RequestBodyEdit] - Request body with content set as Api\Resource->editFormClass and description that supports subject parameters.
• #[Api\RequestBodyList] - Request body with content set as Api\Resource->listFormClass (with 'sorting_field_choices' and 'filter_filterBy_choices' options) and description that supports subject parameters.
• #[Api\RequestBodyExportCsv] - Request body with content set as Api\Resource->exportCsvFormClass (with 'sorting_field_choices', 'filter_filterBy_choices' and 'fields_field_choices' options) and description that supports subject parameters.
• #[Api\RequestBodyExportExcel] - Request body with content set as Api\Resource->exportExcelFormClass (with 'sorting_field_choices', 'filter_filterBy_choices' and 'fields_field_choices' options) and description that supports subject parameters.
• #[Api\Response200] - Preconfigured response with code 200 and description that supports subject parameters.
• #[Api\Response200ArraySubjectGroups] - Preconfigured response with code 200 and default description that supports subject parameters and sets content as array of Nelmio\ApiDocBundle\Annotation\Model with given class and serialization groups..
• #[Api\Response200BatchResults] - Preconfigured list response with code 200 and description that supports subject parameters and sets content as array of Carve\ApiBundle\Model\BatchResult.
• #[Api\Response200Groups] - Preconfigured response with code 200 and description that supports subject parameters and attaches serialization groups to content (Nelmio\ApiDocBundle\Annotation\Model is expected as content).
• #[Api\Response200SubjectGroups] - Preconfigured response with code 200 and description that supports subject parameters and sets content as Nelmio\ApiDocBundle\Annotation\Model with subject class and serialization groups.
• #[Api\Response200List] - Preconfigured list response with code 200 and description that supports subject parameters and sets content as object with rowsCount and results that include items with subject class and serialization groups.
• #[Api\Response204] - Preconfigured response with code 204 and description that supports subject parameters.
• #[Api\Response204Delete] - Preconfigured response with code 204 and default description ({{ subjectTitle }} successfully deleted) that supports subject parameters.
• #[Api\Response400] - Preconfigured response with code 400 and default description (Unable to process request due to invalid data) that supports subject parameters.
• #[Api\Response404] - Preconfigured response with code 404 and description that supports subject parameters.
• #[Api\Response404Id] - Preconfigured response with code 404 and default description ({{ subjectTitle }} with specified ID was not found) that supports subject parameters.

Usage examples

Common use cases

Development

Running tests

Use composer to download packages (including PHPUnit).

Verify PHPUnit installation. Following command should return version of PHPUnit.

Run tests.