mixerapi / mixerapi

CakePHP API Plugin for REST + JSON API Development [READ-ONLY]

A CakePHP Plugin for RESTful API Development

Streamline development of modern RESTful APIs for your teams CakePHP project. Designed around a component-based architecture, MixerAPI enables developers to pick and choose the functionality they need for developing REST APIs.

Documentation | Demo Application | Demo Source Code

Features

• Rapid Prototyping: Scaffold your API in seconds with a custom Bake template geared towards modern REST architecture.
• OpenAPI: Automatically generates OpenAPI from your existing code into Swagger and Redoc. Attributes provided, but not required.
• Error Handling: Handles exception rendering in XML or JSON.
• Data Formats: Formats responses in JSON, XML, HAL+JSON, or JSON-LD.
• Integrations: Integrates well with other CakePHP 4 compatible plugins.
• Minimalist Configuration: Built for developing, not writing YAML configurations. Most components require zero configuration files.
• Non-opinionated: Develop your way.

This is a read-only repository. Please submit issues and PRs to mixerapi/mixerapi-dev

For install steps head over to https://mixerapi.com/install

MixerAPI Core Plugins

MixerAPI automatically installs the following plugins for your RESTful API project:

Plugin	Description
MixerApi/Bake	A custom bake template focused on creating RESTful CakePHP controllers in seconds
MixerApi/CollectionView	A Collection View for displaying configurable pagination meta-data in JSON or XML collection responses
MixerApi/ExceptionRender	Handles rendering entity validation errors and other exceptions for your API
MixerApi/HalView	A Hypertext Application Language (HAL+JSON) View for CakePHP
MixerApi/JsonLdView	A JSON-LD View for CakePHP
SwaggerBake	A delightfully tasty tool for generating Swagger documentation with OpenApi 3.0.0 schema

Recommended Plugins

Plugin	Description
MixerApi/Crud	A service provider for CRUD (Create/Read/Update/Delete) operations. Since this plugin uses the experimental CakePHP dependency injection it must be enabled separately.
MixerApi/JwtAuth	A JWT authentication library for CakePHP supporting both HMAC (HS256 or HS512) and RSA (RS256 or RS512) with JSON Web Keys.
Search	Search provides a simple interface to create paginate-able filters for your CakePHP application.

mixerapi's Issues

Investigate using splitish

Would move all Mixer code into a mono repo and then split out on release into read-only repo's.

https://github.com/splitsh/lite

error defining validator

If I define a validator adding mixerapi plugin, I got an error when I try to save something (not via Api)
Error saving resource Presenza

# MixerApi\ExceptionRender\ValidationException
# ROOT/vendor/mixerapi/exception-render/src/EntityValidationListener.php
        if (Configure::read('MixerApi.ExceptionRender.entity_validation') !== false) {
            EventManager::instance()->on(
                'Model.afterMarshal',
                function ($event, $entity, $options) {
                    $this->handler($event, $entity, $options);
                }
            );
        }
    }

in my PresenzeTable.php I've add this line:

   $validator->add('codfis', 'unique', ['rule' => 'validateUnique', 'provider' => 'table']);

how upgrade system with cakephp 5

This pluggin has many error with cakephp 5

Custom api other than crud ones HELP needed

I would need to create an API for managing Stripe webhooks.
( I am using cake 5.06 and last version of your plugins ) Mixerapi and SwaggerBake) , CakeDC Users plugin last cake 5 compatible version )
I created a plugin called Stripe where I have wrapped the Stripes classes to manage payments.
I have created a controller in the Controllers Api namespace. There is any model and any connection to the database in this api.
I have compiled the swagger_bake following the docs and generated the json with cli commmand line.
I have added a route for the webhooks controller.
The swagger works , I am able to see the api in the list

I tried to test the api with swagger and with postman but I always got a 200 with the html code of the swagger page as result.
The controller action is out of any authorization and could be served.

The code of the controller action

 /**
     * @return void
     */
    public function invoke(): void
    {
        //debug($this->getRequest()); die;
        $stripe_data = $this->getRequest()->getData();

        Log::info(json_encode($stripe_data),['scope' => 'stripe']);

        $this->set(compact('stripe_data'));
        $this->viewBuilder()->setOption('serialize', 'stripe_data');
    }

The code of the routes

$routes->scope('/api/stripe/v1', function (RouteBuilder $builder) {

            $builder->setExtensions(['xml', 'json']);

            $builder->connect('/', [
                'plugin' => 'Stripe', 'controller' => 'Swagger', 'action' => 'index'
            ]);

            $builder->connect('/contexts/*', [
                'plugin' => 'MixerApi/JsonLdView', 'controller' => 'JsonLd', 'action' => 'contexts'
            ]);
            $builder->connect('/vocab', [
                'plugin' => 'MixerApi/JsonLdView', 'controller' => 'JsonLd', 'action' => 'vocab'
            ]);
            

            $builder->post(
                '/web-hooks', [
                'prefix' => 'Api',
                'plugin' => 'Stripe',
                'controller' => 'Webhooks',
                'action' => 'invoke'
            ]);
        });

The code of the swaggerBake

'SwaggerBake' => [
        'prefix' => '/api/stripe/v1',
        'yml' => '/plugins/Stripe/config/swagger.yml',
        'json' => '/plugins/Stripe/webroot/swagger.json',
        'webPath' => '/stripe/swagger.json',
        'hotReload' => Configure::read('debug'),
        'jsonOptions' => Configure::read('debug') ? JSON_PRETTY_PRINT : JSON_UNESCAPED_UNICODE,
        'editActionMethods' => ['PATCH'],
        'requestAccepts' => [
            'application/json',
            'application/x-www-form-urlencoded',
            'application/xml',
        ],
        'responseContentTypes' => [
            'application/json',
            'application/xml',
            'application/hal+json',
            'application/json+ld'
        ],
        'docType' => 'swagger',
        'exceptionSchema' => 'Exception',
        'namespaces' => [
            'controllers' => ['\Stripe\\Api\\'],
            'entities' => ['\Stripe\\'],
            'tables' => ['\Stripe\\Model\\Table\\Api']
        ],
    ]

The code of the swagger.yml

openapi: "3.0.0"
info:
    version: 3.0.*
    title: ACME STRIPE api
    description: |
        For documentation please review the project [README](https://github.com/cnizzardini/cakephp-swagger-bake) and for
        other great API related packages checkout [MixerAPI](http://mixerapi.com). To change this text edit your
        `swagger.yaml` file.
    license:
        name: MIT License
servers:
    -   url: /
paths:

components:
    schemas:
        Exception:
            type: object
            properties:
                code:
                    type: integer
                    example: 500
                url:
                    type: string
                    example: /url/path
                message:
                    type: string
                    example: Internal Error
            xml:
                name: response
        OperationResult:
            type: object
            properties:
                result:
                    type: boolean
            xml:
                name: response
x-acme-stripe:
  components:
    schemas:
      Webhooks:
        type: object
x-swagger-bake:
    components:
        schemas:
            Generic-Collection:
                type: object
                x-data-element: data
                properties:
                    collection:
                        type: object
                        properties:
                            url:
                                type: string
                                format: url
                                example: /index
                            count:
                                type: integer
                                example: 20
                            total:
                                type: integer
                                example: 200
                            pages:
                                type: integer
                                example: 10
                            next:
                                type: string
                                format: url
                                example: /index?page=:number
                            prev:
                                type: string
                                format: url
                                example: /index?page=:number
                            first:
                                type: string
                                format: url
                                example: /index
                            last:
                                type: string
                                format: url
                                example: /index?page=:number

Is there the need to create a custom response using something like Dto or other ?
I am using your plugin for normal crud table related controllers without any problem.

Do you have some example to look at with custom api other than normal crud related to tables?

Thank you

Rudy

Clean install

I want to try this API in my project.
Over the learning I found some error in doc.

My step by step process 😄

Make clean cakephp install composer create-project --prefer-dist cakephp/app:4.* ./

The next steps from the mixerapi.com

composer require mixerapi/mixerapi
bin/cake plugin load MixerApi

Dependecies error..
I try with:

composer require mixerapi/mixerapi  --with-all-dependencies
bin/cake plugin load MixerApi

This ready install, I always use 'Y' option

bin/cake mixerapi install
MixerAPI Installation Complete!

The workflow:
I have usable mysql schema so I try bake model
Baking your initial scaffolding using [bake](https://book.cakephp.org/bake/2/en/index.html) in conjunction with the [MixerAPI/Bake](https://mixerapi.com/bake) theme.
The two links is not usable, the first go to cakephp2 the second is empty (404)
I navigate form the left menu Bake Controllers
I set in the app_local.php the default datasources (mysql)

Bake the model and .... "Your database does not have any tables" and put full html source to console

I try to set in the app_local

  'Datasources' => [
        'default' => [
            **'className' => Connection::class,
            'driver' => Mysql::class,**

but "Datasource class Connection could not be found. "
I must to change the app.php
back the original className and driver from sqlite to mysql

After this I can bake the models.
bake model Subscribers --theme MixerApi/Bake
Next bake the controllers
bin/cake bake controller Subscribers --theme MixerApi/Bake

The validations is is skip at this situation

The routes

Building your RESTful routes with or without MixerAPI/Rest.
The second link is empty (404)
I try the " RESTful Routes " from the left menu
bin/cake mixerapi:rest route create
This modify the routes.php

bin/cake mixerapi:rest route list
-------------------------------------------------------------------------------
| Finding routes...
-------------------------------------------------------------------------------
+--------------------+-------------------+------------+-------------+--------+--------+
| Route name         | URI template      | Method(s)  | Controller  | Action | Plugin |
+--------------------+-------------------+------------+-------------+--------+--------+
| sites:add          | /sites            | POST       | Sites       | add    |        |
| sites:delete       | /sites/{id}       | DELETE     | Sites       | delete |        |
| sites:edit         | /sites/{id}       | PUT, PATCH | Sites       | edit   |        |
| sites:index        | /sites            | GET        | Sites       | index  |        |
| sites:view         | /sites/{id}       | GET        | Sites       | view   |        |
| subscribers:add    | /subscribers      | POST       | Subscribers | add    |        |
| subscribers:delete | /subscribers/{id} | DELETE     | Subscribers | delete |        |
| subscribers:edit   | /subscribers/{id} | PUT, PATCH | Subscribers | edit   |        |
| subscribers:index  | /subscribers      | GET        | Subscribers | index  |        |
| subscribers:view   | /subscribers/{id} | GET        | Subscribers | view   |        |
| welcome:info       | /welcome/info     | GET        | Welcome     | info   |        |
+--------------------+-------------------+------------+-------------+--------+--------+

At this point I check in browser http://127.0.0.1:8006/subscribers/1001

Missing Template
Cake\View\Exception\MissingTemplateException

http://127.0.0.1:8006/subscribers/1001.json
Ready come back the json

I want result without the json extension

I see the generated routes.php and I think is not correct is contain duplicated definition (I not change manual )

<?php
use Cake\Routing\Route\DashedRoute;
use Cake\Routing\RouteBuilder;
use MixerApi\Rest\Lib\AutoRouter;
$routes->setRouteClass(DashedRoute::class);
$routes->scope('/', function (RouteBuilder $builder) {
    $builder->setExtensions(['json', 'xml']);
    $builder->resources('Welcome', ['only' => ['info'], 'map' => ['info' => ['action' => 'info', 'method' => 'GET']]]);
    (new AutoRouter($builder))->buildResources();
    $builder->connect('/', ['plugin' => 'SwaggerBake', 'controller' => 'Swagger', 'action' => 'index']);
    $builder->connect('/contexts/*', ['plugin' => 'MixerApi/JsonLdView', 'controller' => 'JsonLd', 'action' => 'contexts']);
    $builder->connect('/vocab', ['plugin' => 'MixerApi/JsonLdView', 'controller' => 'JsonLd', 'action' => 'vocab']);
    $builder->fallbacks();
    $builder->resources('Sites');
    $builder->resources('Subscribers');
}, function (RouteBuilder $builder) {
    $builder->setExtensions(['json', 'xml']);
    $builder->resources('Welcome', ['only' => ['info'], 'map' => ['info' => ['action' => 'info', 'method' => 'GET']]]);
    (new AutoRouter($builder))->buildResources();
    $builder->connect('/', ['plugin' => 'SwaggerBake', 'controller' => 'Swagger', 'action' => 'index']);
    $builder->connect('/contexts/*', ['plugin' => 'MixerApi/JsonLdView', 'controller' => 'JsonLd', 'action' => 'contexts']);
    $builder->connect('/vocab', ['plugin' => 'MixerApi/JsonLdView', 'controller' => 'JsonLd', 'action' => 'vocab']);
    $builder->fallbacks();
    $builder->resources('Sites');
    $builder->resources('Subscribers');
});

Finale in production I need to use the mixerapi only with prefix (ApiV1, Apiv2 ...)

Base mixerapi tries to load Search plugin

Base mixerapi tries to load the Search plugin. This is only recommended and is not required in composer.json, so if you install only mixerapi, you get a MissingPluginException.

Add PHP 8.2 to github actions

Deprecation warning for PHP 8.1: Upgrade php-dot-notation dependency to ^2.3

I noticed this blob at the top of my documentation after upgrading to PHP 8.1:

Deprecated (8192) : Return type of Adbar\Dot::jsonSerialize() should either be compatible with JsonSerializable::jsonSerialize(): mixed, or the #[\ReturnTypeWillChange] attribute should be used to temporarily suppress the notice [in /shared/httpd/ticketsauce-api/vendor/adbario/php-dot-notation/src/Dot.php, line 603]
Warning (512) : Unable to emit headers. Headers sent in file=/shared/httpd/ticketsauce-api/vendor/cakephp/cakephp/src/Error/Renderer/HtmlErrorRenderer.php line=36 [in /shared/httpd/ticketsauce-api/vendor/cakephp/cakephp/src/Http/ResponseEmitter.php, line 71]
Warning (2) : Cannot modify header information - headers already sent by (output started at /shared/httpd/ticketsauce-api/vendor/cakephp/cakephp/src/Error/Renderer/HtmlErrorRenderer.php:36) [in /shared/httpd/ticketsauce-api/vendor/cakephp/cakephp/src/Http/ResponseEmitter.php, line 168]
Warning (2) : Cannot modify header information - headers already sent by (output started at /shared/httpd/ticketsauce-api/vendor/cakephp/cakephp/src/Error/Renderer/HtmlErrorRenderer.php:36) [in /shared/httpd/ticketsauce-api/vendor/cakephp/cakephp/src/Http/ResponseEmitter.php, line 197]

Digging into the dependencies, I found that mixerapi/collection-view has a dependency on v2.2 of the adbario/php-dot-notation package. This deprecation issue has been fixed in v2.3 of the package.

Could the maintainers of mixerapi/collection-view please evaluate whether an upgrade to v2.3 is appropriate so the deprecation error goes away? It would be much appreciated.

I have install mixerApi with cakephp5

when i install mixerapi it is work with cakephp4 but when i install with cakephp5

i have this

bin/cake mixerapi install
[Cake\Core\Exception\MissingPluginException] Plugin `Search` could not be found. in C:\Users\elarbi.msahel\workspace\mixerapi\vendor\cakephp\cakephp\src\Core\PluginCollection.php on line 190

Exception Attributes

array (
  'plugin' => 'Search',
)

Stack Trace:

Cake\Core\PluginCollection->findPath() - CORE\src\Core\PluginCollection.php, line 314
Cake\Core\PluginCollection->create() - CORE\src\Http\BaseApplication.php, line 139
Cake\Http\BaseApplication->addPlugin() - ROOT\vendor\mixerapi\mixerapi\src\Plugin.php, line 47
MixerApi\Plugin->bootstrap() - CORE\src\Http\BaseApplication.php, line 198
Cake\Http\BaseApplication->pluginBootstrap() - CORE\src\Console\CommandRunner.php, line 192
Cake\Console\CommandRunner->bootstrap() - CORE\src\Console\CommandRunner.php, line 137
Cake\Console\CommandRunner->run() - ROOT\bin\cake.php, line 10
[main] - [main], line 0